Яндекс.Метрика
Copyright © 2010—2011, Kristaps Dzonsons
релиз от 2011/11/07 22:04:26
All content licensed under Creative Commons' Attribution Share-Alike: deriving works must attribute the author(s) and use a similar license. Citations should include the current version, 0.1.2, and date, 07 November 2011.

Перевод: Михайлов Алексей aka iboxjo
(перевод АКТИВЕН, дата последнего обновления 24.05.2012, 28.05.2012)

Предисловие

 | Утилита без руководства - утилита не для всех.


 Это руководство по написанию руководств UNIX на языке mdoc. Если вы новичок в написании руководств UNIX, или хотите узнать о передовом опыте с целью создания высококачественных руководств, эта книга может оказаться полезной для вашей работы.

 Для тех кто знаком с UNIX, mdoc - язык документирования утилит, программных функций, файлов, форматов, аппаратных интерфейсов и т.п. Под языком, я имею ввиду структурированный, машиночитаемый формат документа, такой как HTML - основной язык web-страниц, или RTF, используемый текстовыми процессорами. man - утилита для запроса документов на mdoc и других языках, обычно называемых man-страницами.

 Далее приведён пример вывода man для команды cat:

NAME
cat — concatenate and print files
SYNOPSIS
cat     [-benstuv] [file ...]
DESCRIPTION
The cat utility reads files sequentially, writing them to the standard output. The file operands are processed in command-line order. If file is a single dash (‘​-') or absent, cat reads from the standard input.

Почему mdoc? В конце концов, есть множество других языков для написания руководств UNIX, от исторического man до DocBook. В кратце, mdoc это:


 Ни один иной формат не может похвастаться всеми этими достоинствами одновременно.

 На самом деле, хотя я уже несколько раз упоминал UNIX, mdoc связан не только с ним. Несмотря на то, что UNIX и mdoc исторически связаны, mdoc инструменты, с открытым исходным кодом, существуют для любой операционной системы. Кроме того, документирование совместимое с mdoc относится ко всем ОС - не только к UNIX.

 Однако, в этой книге я предполагаю, что вы знакомы с man и его выводом. Это позволит нам сосредоточиться на руководстве по форматированию этого вывода. Таким образом, если вы не знакомы с утилитой man, самое время прочитать на эту тему что-то для начинающих (например "Руководство UNIX для начинающих"), или, по крайней мере, ознакомиться с содержимым вывода команды $man man (руководства man).

 Конечно, это не канонические ссылки! Язык mdoc не стандартизируется. Для получения официальной информации, обратитесь к руководству распространяемому с вашей целевой системой, $man mdoc. Эта работа, в первую очередь, обращается к элементам mdoc, общим для любого развёртывания UNIX, отмечая только общие отличия в портируемости.

Учебник: Введение
 Давайте начнём работать с практическими примерами mdoc.

 Целевая аудитория этой части книги - те кто никогда не писал руководства на mdoc. Хотя у вас может возникнуть желание, перейти к главе соответствующей вашему типу руководства (например команды или библиотеки функций), лучше читать главы по порядку. Я буду объяснять синтаксис mdoc в порядке изложения.

 Если вы уже написали несколько руководств, вы всё равно можете прочитать эту часть учебника: здесь разъясняются технические концепции языка, и даются некоторые рекомендации по переносимости между различными средами mdoc.

 Я буду часто ссылаться на результаты вывода mdoc отображаемые с помощью man утилиты UNIX. Кроме того, я буду ссылаться на вызов команд в традиционном стиле UNIX - в командной строке. Короче говоря, некоторое знание UNIX поможет избежать большой путаницы. Однако, по мере необходимости, я кратко представлю синтаксис вызова команды.

Команды
 Команды, это способ, которым пользователь управляет своим компьютером. Я уже говорил о команде man: если вы работали с системой UNIX, вы, вероятно, использовали команды $man intro и $man man для изучения системы.

 В этой главе, я расскажу о том, как документировать эти команды с помощью mdoc.

 Что-то может показаться вам непривычным, особенно если вы привыкли работать с графическим интерфейсом - все наши примеры относятся к командной строке и используют текстовые команды. Если ваша целевая среда не является системой UNIX, всё равно следует ознакомиться с этими примерами, поскольку они будут рассматривать рудиментарные структуры языка mdoc. Как упоминалось ранее, чтение текста введения UNIX поможет избежать путаницы.

 Давайте начнём делать ментальные отметки, которые помогут создать хорошее руководство для команды. Этот перечень отметок возникает при открытие читателем нашего руководства: что же делает команда и как её использовать?

+++ 25.05.2012

 Лучшим тестом будет ваш друг или коллега, который может прочитать вашу инструкцию и попробовать использовать команду без какой-либо помощи с вашей стороны. Не следует расстраиваться, если что-то не так - может потребоваться несколько попыток, чтобы получилось хорошо.

 Начнём с простой команды hi, которая печатает на экране "Hello World". Далее, я добавлю для этой команды некоторые аргументы командной строки. К тому времени, как вы закончите чтение этой главы, вы должны получить представление синтаксиса mdoc и некоторых наиболее широко используемых макросов.

 В данном тексте я буду ссылаться на вызов команд как $cmd [-flag farg] arg. Здесь, cmd - имя вызываемой команды, -flag флаги (или переключатели) для этой команды, farg - аргументы к флагам (не все флаги имеют аргументы), и arg - аргументы команды.

 Дефис перед флагом указывает на флаг, а квадратные скобки, указывают, что flag является необязательной частью вызова. Поскольку аргумент не находится в квадратных скобках, он является обязательной частью вызова.

 Данное соглашение оформлено стандартом POSIX.1-2008 (Базовые определения, раздел 12.1), т.ч. вы можете ожидать, что в UNIX, в большинстве случаев, это именно так.

Простая команда
Рассмотрим простую команду UNIX - hi, которая печатает hello world и завершается. Давайте создадим страницу руководства hi.1, которая документирует данную команду. В этом примере, я начну с полного полного руководства. В последующих примерах, мы будем постепенно наращивать отдельные части руководства.

.Dd May 30, 2011
.Dt HI 1
.Os
.Sh NAME
.Nm hi
.Nd print \(dqhello, world\(dq
.Sh SYNOPSIS
.Nm
.Sh DESCRIPTION
Print
.Qq hello, world
and exit.

 Как отображается эта страница руководства - зависит от вашей системы.

 Традиционно, для форматирования руководств UNIX используется команда nroff. Пока мы будем придерживаться этого подхода.

 Для отображения вывода, необходимо вызвать nroff в виде $nroff -mandoc file. Флаг -mandoc указывает, что ввод производится в формате mdoc. В дальнешем, я буду называть nroff просто средством форматирования (форматером), что позволит избежать путаницы, поскольку доступно множество форматеров mdoc.

NAME
hi — print "hello, world"
SYNOPSIS
hi   
DESCRIPTION
Print “hello, world” and exit.

 Давайте начнём изучение с ввода и вывода. Мы видим, что большая часть текста транслируется в вывод, например ввод заголовка NAME выравниватся по левому краю и выделяется жирным шрифтом. То же самое с SYNOPSIS и DESCRIPTION, хотя текст .Sh перед этими определениями отсутствует. Мы можем видеть вывод предложения Print "hello, world" and exit в стоках 10-12:

Print
.Qq hello, world
and exit.

 Давайте более подробно рассмотрим этот фрагмент.

 .Qq является частью синтаксической инструкции mdoc. Входные строки начинающиеся с точки являются инструкциями форматирования и называются макросами mdoc, или просто макросами. Имя макроса состоит из двух-трёх символов предварённых точкой, например Qq. Имя макроса, кратко намекает на выполняемые им функции. Слова следующие после Qq, вплоть до конца строки, являются аргументами в рамках макроса. Область видимости (scope) - технический термин, используемый в языках программирования, ссылающийся на тело ввода содержащее инструкции или переменные. В mdoc, область видимости макроса - блок текста и инструкции в контексте форматирования данного макроса. Рассматривая ввод и вывод, можно сделать вывод, что область видимости Qq заключена в кавычки (форматирование в данном случае).

.Qq hello, world
Print “hello, world” and exit.

 Когда мы исследуем больше макросов, мы увидим, что каждый макрос следует одному из правил. Уже понятно, что Qq имеет ограниченную область вызова строки. Обратите внимание, что форматер распознаёт содержимое между макросами Sh, как требующее углубления (indentation). Таким образом, становится ясно, что mdoc включает такое понятие как многострочные области. На самом деле, Sh имеет строковые аргументы для именования разделов; и многострочные аргументы для содержимого разделов.

.Sh SECTION 1
Section text.
.Sh SECTION 2
New section text.

 Кроме того, существование Qq в области Sh означает, что области могут быть вложенными. В следующем разделе мы увидим, что несколько макросов могут быть указаны в одной строке.

.Sh SECTION 1
Section text.
.Sh SECTION 2
.Qq Section text nested in a quote.

 Следовательно, мы можем визуализировать эту область с внешней и внутренней областями:

.Sh SECTION 2
.Qq Section text nested in a quote.

 Давайте теперь вернёмся к hi, вооружённые новыми знаниями о макросах и областях.


--- декорировать текст пока нет возможности - будет позже

+++ 28.05.2012
Мы видим всего семь макросов: Dd, Dt, Os, Sh, Nm, Nd и Qq. Сейчас мы знаем, что Qq помещает свой аргумент в двойные кавычки, а Sh начинает именованный раздел с отступом многострочного аргумента.

Среди остальных макросов; Dd - формирует дату последнего изменения руководства в формате "день месяца, год". Dt указывает название руководства, HI и его категорию, 1. Номер категории руководства подчиняется конвенции UNIX, но может быть применима к любой операционной системе. В этой книге, мы рассмотрим наиболее стандартные категории. Обратите внимание, что HI указывается в верхнем регистре: в соответвии с соглашением, Dt всегда должен формировать название документа в верхнем регистре. В следующих главах книги, мы поговорим подробнее о титулах и разделах. Сейчас, давайте предположим, что номер категории определяет тему руководства, где 1 означает категорию утилит.

Os указвает операционную систему на которой производится форматирование. Если данный макрос не указан, форматер будет возвращать значение текущей операционной системы (например OpenBSD 4.9, Linux 2.6.32-5 или Microsoft Windows XP).

.Dd May 30, 2011
.Dt HI 1
.Os \" Current operating system.

Обратите внимание, что текст после маркера \" - является комментарием mdoc, который имеет следующий синтаксис:

Text. \" Comment to end of the line. (Коментарий до конца строки)
.\" Extending across the full line. 

Комментарии имеют область видимости строки, подобно Qq:

.\" .Sh NAME

Nm, определяет имя руководства. Он отличается от Dt тем, что одно руководство может документировать несколько компонентов. Примеры этого, мы увидим в следующих главах. Наконец, Nd определяет краткое описание - однострочное описание команды.

.Sh NAME
.Nm hi
.Nd print \(dqhello, world\(dq

Вы можете видеть, что мы вновь используем Nm в SYNOPSIS, только уже без аргументов. Форматер достаточно сообразителен, чтобы заполнить свой аргумент в соответствии с последним использованным аргументом, в данном случае hi.

Поскольку наша простая команда не имеет аргументов командной строки, она вызывается простым именем команды.

.Sh SYNOPSIS
.Nm

Объединив всё вместе, мы получим следующее:

.Dd May 30, 2011
.Dt HI 1
.Os
.Sh NAME
.Nm hi
.Nd print \(dqhello, world\(dq
.Sh SYNOPSIS
.Nm
.Sh DESCRIPTION
Print
.Qq hello, world
and exit.