Go to the first, previous, next, last section, table of contents.


Советы и подсказки

Вот несколько советов по написанию документации в Texinfo:

Больше именных указателей!

Пишите много вхождений в именные указатели, различными способами. Читателям нравятся именные указатели; они полезны и удобны.

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

Вот еще несколько советов, которые мы сочли полезными:

Пустые строки

Завершайте фразы

Завершенные фразы легче читать, чем ...

Редакции, даты и версии

Пишите дату и номера редакции и версии в трех местах в каждом руководстве:

  1. В первом разделе @ifinfo, для читающих Texinfo-файл.
  2. В разделе @titlepage, для читающих печатное руководство.
  3. В первой ноде , для читающих Info-файл.

Также полезно написать заметку перед первым разделом @ifinfo для объяснения, что вы делаете.

Например:

@c ===> ВНИМАНИЕ! <==
@c Укажите дату и номера редакции и версии
@c в *трех* местах:
@c   1. Первый раздел ifinfo   2. титульный лист  3. первая нода
@c Чтобы найти эти места, ищите !!установить

@ifinfo
@c !!установить редакцию, дату, версию
Редакция 4.03, @cite{Руководство по GDB} для GDB версии 4.3,
январь 1992 г.

...

--- или используйте @set и @value (see section Пример применения @value).

Команды для определений

Команды для определений, а это @deffn, @defun, @defmac и им подобные, позволяют вам делать описания в едином формате.

Заглавные буквы

Пробелы

Не используйте для форматирования Texinfo-файла пробелы, за исключением текста внутри @example ... @end example и похожих блоков.

Например, TeX заполняет следующее:

    @kbd{C-x v}
    @kbd{M-x vc-next-action}
       Производит следующую логическую операцию
       над файлом с контролем версий,
       соответствующим текущему буферу.

таким образом, что оно выглядит так:

C-x v M-x vc-next-action Производит следующую логическую операцию над файлом с контролем версий, соответствующим текущему буферу.

В этом случае, текст нужно форматировать с помощью @table, @item и @itemx, для создания таблицы.

@code, @samp, @var и `---'

Точки вне кавычек

Помещайте точки и другие знаки препинания вне кавычек, если только эти знаки препинания не относятся к словам, заключенным в кавычки. Эта практика противоречит издательским соглашениям, принятым в Соединенных Штатах@transnote{Но соответствует правилам пунктуации русского языка.}, но позволяет читателю различать содержимое кавычек и целого отрывка.

Например, вы должны написать точку в следующем предложении вне кавычек:

Очевидно, `au' является сокращением от ``author''.

так как `au' не служит сокращением от `author.' (с точкой после слова).

Введение новых терминов

@pxref

Абсолютно никогда не используйте @pxref, кроме как в особом контексте, для которого она была разработана: внутри круглых скобок, когда закрывающая круглая скобка идет сразу после закрывающей фигурной. Одна форматирующая программа автоматически вставляет закрывающие знаки препинания, а вторая -- нет. Это означает, что вывод выглядит правильно и на печати, и в Info-файле, но только если эта команда применена внутри круглых скобок.

Вызов из оболочки

Вы можете вызвать такие программы, как Emacs, GCC и gawk из оболочки. Документация для любой программы должна содержать раздел, описывающий это. К сожалению, если имена нод и названия этих разделов всегда различны, читатели считают, что найти этот раздел трудно.

Называйте такие разделы фразой, начинающейся словом `Вызов ...', например `Вызов Emacs'; тогда пользователи смогут легко найти этот раздел.

Синтаксис ANSI C

Когда вы используете @example для описания соглашений о вызове функции Си, используйте синтаксис ANSI C, как здесь:

void dld_init (char *@var{path});

И в последующем обсуждении ссылайтесь на значения аргументов по тем же именам аргументов, снова выделяя их с помощью @var.

Избегайте использования устаревшего синтаксиса, выглядящего так:

#include <dld.h>

dld_init (path)
char *path;

Также, лучше избегать написания #include над объявлением лишь для того, чтобы показать, что эта функция объявлена в заголовочном файле. Это может произвести неправильное впечатление, что #include относится к объявлению функции. Либо скажите явно, какой заголовочный файл содержит объявление, либо, что еще лучше, напишите имя заголовочного файла, используемого для группы функций, в начале раздела, описывающего эти функции.

Плохие примеры

Вот несколько примеров плохого стиля, которого нужно избегать:

В этом примере скажите " ... you must @dfn{check in} the new version." Это более гладко читается.

When you are done editing the file, you must perform a @dfn{check in}.

В следующем примере скажите "... makes a unified interface such as VC mode possible."

SCCS, RCS and other version-control systems all perform similar functions in broadly similar ways (it is this resemblance which makes a unified control mode like this possible).

И в этом примере, вам нужно указать, к чему относится `it':

If you are working with other people, it assists in coordinating everyone's changes so they do not step on each other.

И наконец ...


Go to the first, previous, next, last section, table of contents.