Сторінка керівництва програми написаної для UNIX

Основний документацією по команді зазвичай є сторінка керів ництва – односторінкове опис в довідковому керівництві по UNIX (див рис 92) Сторінка керівництва зберігається в стандартному каталозі, зазвичай / usr / man, в підкаталозі з номером, відповідним номеру розділу керівництва Сторінка керівництва по hoc, наприклад, зберігається в / usr/man/man1/hoc1 (так як вона описує призначену для користувача команду)

Сторінки керівництва виводяться за допомогою команди man (1) – файла оболонки, який запускає nroff-man, тому man hoc друкує керівництво по hoc Якщо одне імя зустрічається в кількох розділах (Це стосується, наприклад, самої команди man, так як в розділі 1 описується команда, а в розділі 7 – макрос), можна вказати для man номер розділу:

$ man  7 man

виводить тільки опис макросу За замовчуванням виводяться всі стра ниці з вказаним імям (використовується nroff), а man-t генерує набрання сторінки за допомогою troff

Автор сторінки керівництва створює файл у відповідному підкаталозі / usr / man Команда man викликає nroff або troff з макропакет для друку сторінки, що можна побачити, переглядаючи команду man в пошуку звернення до форматує програмам Результат буде виглядати наступним чином:

$ grep  roff `which  man`

nroff $opt  –man  $all ;

neqn  $all  |  nroff  $opt  –man  ; troff  $opt  –man  $all  ;

troff  –t  $opt  –man  $all |  tc ; eqn  $all |  troff  $opt  –man  ;

eqn $all | troff –t  $opt  –man  | tc ;

$

Різноманіття виникає через можливість завдання різних пара метрів: nroff або troff, запускати чи ні eqn, і т д Макроси керівництва, викликані troff-man, визначають команди troff, які здійснюють форматування в потрібному стилі По суті, вони схожі на макроси ms, але є й відмінності, зокрема це відноситься до команд зміни шрифтів і виведення назви Про ці макроси можна прочитати в man (7) (Там представлено їх короткий опис), основні ж неважко запамятати Макет сторінки керівництва виглядає так:

.TH  КОМАНДА номер розділу

.SH  NAME

команда \–  короткий опис функції

.SH  SYNOPSIS

.B  команда параметри

.SH  DESCRIPTION

Докладна розповідь про програми та параметрах

Нові абзаци вводяться командою PP

.PP

Це новий абзац

.SH  FILES

файли, використовувані командою, наприклад вpasswd(1) згадується /etc/  passwd

.SH  &quotSEE ALSO&quot

Посилання на споріднені документи, в тому числі інші сторінки керівництва

.SH  DIAGNOSTICS

Опис будь-якого незвичайного висновку (наприклад, дивcmp(1))

.S&nbsp&nbsp&nbsp&nbsp H  BUGS

Несподівані властивості (не обовязково помилки, див нижче)

Якщо якась секція порожня, її заголовок опускається Рядок TH та секції NAME, SYNOPSIS і DESCRIPTION обовязкові

Рядок

.T&nbsp&nbsp&nbsp&nbsp H  КОМАНДА номер5раздела

представляє імя команди і вказує номер розділу Різноманітні рядка SH ідентифікують секції сторінки керівництва Секції NAME і SYNOPSIS є спеціальними в інших міститься звичайна нудна інформація Секція NAME називає команду (Цього разу в нижньому регістрі) і надає її однорядкове опис Секція SYNOPSIS перераховує параметри, але не описує їх Як і в будь-який інший секції, вхідні дані можуть вводитися в будь-якому вигляді, тому можна задати зміни шрифту за допомогою макросів B, I і R У секції SYNOPSIS назва команди і параметри надруковані напівжирним шрифтом, а решта інформації – звичайним прямим Наприклад, секції NAME і SYNOPSIS для ed (1) задаються так:

.SH  NAME

ed \–  text editor

.SH  SYNOPSIS

.B ed [

.B \–

] [

.B \–x

] [ name ]

Виводяться вони наступним чином:

NAME

ed text editor

SYNOPSIS

ed  [ – ] [ –x  ] [ name ]

Зверніть увагу, що замість простого символу – використовується \ –

Секція DESCRIPTION описує команду і її параметри У більшості випадків це саме опис команди, а не мови, який команда визначає Сторінка керівництва cc (1) не описує мова Сі в ній розповідається про те, як запустити команду cc, щоб скомпілювати програму, написану на Сі, як викликати оптимізатор, де залишаються вихідні дані, і т д Мова описується в довідковому керівництві по Сі, посилання на яке наводиться в секції SEE ALSO стра-

Ниці cc (1) З іншого боку, не буває правил без винятків:

man (7) – це опис мови макросів man

Прийнято виводити курсивом імена команд і теги для параметрів (наприклад, «name» на сторінці про ed) в секції DESCRIPTION Макроси I (виводити перший аргумент курсивом) і IR (виводити перший аргу мент курсивом, а другий – прямим шрифтом) роблять цю операцію надзвичайно простий Макрос IR потрібен тому, що макрос I пакета man і не виконує жодних другий аргумент тим недокументованим, але зручним способом, яким це робить макрос пакета ms

Секція FILES вказує файли, неявно використовуються командою DIAG-NOSTICS потрібна, тільки якщо команда виводить якісь незвичайні дані Це можуть бути діагностичні повідомлення, коди завершення або незрозумілі варіації нормального поведінки команди Секція BUGS також названа не дуже вдало Ті дефекти, про які в ній повідомляється, є не стільки помилками, скільки недоліками, адже помилки повинні бути виправлені до того, як команда інсталюється Для того щоб відчути, що ж потрапляє в секцію DIAGNOS-TICS, а що – в BUGS, перегляньте стандартне керівництво

Приклад повинен пролити світло на те, як написати сторінку керівництва Оригінальний текст для hoc (1), / usr/man/man1/hoc1, представлений на рис 91, а рис 92 відображає висновок команди

$ man  -t hoc

Вправа 98Напишіть сторінку керівництва для doctype Напишіть версію команди man, яка переглядала би власний ка талог користувача man в пошуку документації на його особисті програми ~

Джерело: Керниган Б, Пайк Р, UNIX Програмне оточення – Пер з англ – СПб: Символ-Плюс, 2003 – 416 с, Мул

Схожі статті:


Сподобалася стаття? Ви можете залишити відгук або підписатися на RSS , щоб автоматично отримувати інформацію про нові статтях.

Коментарів поки що немає.

Ваш отзыв

Поділ на параграфи відбувається автоматично, адреса електронної пошти ніколи не буде опублікований, допустимий HTML: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

*

*