Стандарт кодирования GNU. : Документирование программ
Вперед Назад Содержание19. Документирование программ
Для документирования программ следует использовать Texinfo. Посмотрите руководство по пакету Texinfo - напечатанное, или версию в info-подсистеме в среде GNU Emacs (C-h i). Посмотрите в качестве примера на существующие Texinfo-файлы (например, в каталоге man/ в поставке GNU Emacs).
Титульный лист руководства должен содержать версию программы, для которой это руководство написано. Эта информация должна содержаться и в Top-узле руководства. Если руководство изменяется более часто или независимо от программы, укажите так же номер версии руководства и в том, и в другом месте.
Руководство должно описывать все аргументы командной строки и все команды. Должны приводиться примеры их использования. Но не следует организовывать руководство как перечень возможностей. Лучше предварительно поместить концепции, которые пользователь должен постичь, прежде чем он дойдет до такого места в руководстве. Поставте перед пользователем цель, что он должен иметь в голове, и объясните, как он может достичь этого. Не стоит использовать man-страницы Unix как образец при написании GNU-документации; они являют собой плохой пример для подражания.
Руководство должно иметь узел с именем 'program Invocation' or 'Invoking program', где program означает название описываемой программы, такое же, как вы набираете в shell'е, чтобы ее запустить. Этот узел (вместе со всеми подузлами, если они будут) должет описывать аргументы командной строки программы и как она должна запускаться (информация типа той, что обычно люди видят на man-страницах). Начните с '@example', который содержит шаблоны для всех опций и аргументов, которые программа использует.
Можно также поместить элементы в некоторое меню для каждого такого шаблона.
Если одно руководство описывает несколько программ, такой узел должен присутствовать для каждой описываемой программы.
Кроме руководства, пакет должен содержать файл с именем 'NEWS', который содержит список видимых для пользователя и заслуживающих внимания изменений. Для каждой новой версии надо добавлять пункты в начало этого файла и указывать номер версии, к которой они принадлежат. Не уничтожайте старые записи, оставляйте их в файле следом за новыми. Это нужно для того, чтобы пользователь мог узнать, что нового он получил при переходе к более новой версии продукта.
Если файл 'NEWS' становится слишком длинным, переместите некоторые старые записи в файл с именем ONEWS и поместите примечение в конце, которое ссылается на этот файл.
Не надо использовать термин "pathname", часто встречающийся в Unix-документации; вместо этого используйте словосочетание "file name" Слово "path" мы используем только для путей поиска, которые из себя представляют списки из имен файлов.
При желании, Вы можете приложить man-страницу к программе. Но имейте ввиду, что поддержка man-страницы требует непрерывных усилий при каждом изменении программы. То время, которое Вы проводите над man-страницей, можно использовать более полезно.
Так что, даже если доброволец-пользователь подарит Вам man-страницу, Вы можете посчитать слишком дорогим принять ее. Если у Вас нет времени, может быть лучше отказаться от нее, если конечно этот доброволец не согласится принять на себя всю ответственность за ее поддержание - тогда Вы сможете полностью умыть руки от этого дела. Если доброволец перестанет выполнять эту работу, то не чуствуйте себя обязанным делать это самому; может оказаться лучшим изъять эту man-страницу до той поры, пока не найдется другой доброволец.
Если же Вы считаете, что различия между man-страницей и документом будут незначительными, и она будет все равно оставаться полезной, поместите хорошо заметное примечание где-то в начале страницы, объясняющее, что Вы не поддерживаете ее, что Texinfo-руководство более полно, и поясняющее, как воспользоваться Texinfo-документацией.
Вперед Назад Содержание