automake - Построение документации

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


Построение документации

В настоящее время Automake обеспечивает поддержку Texinfo и страниц руководства.

Texinfo

Если текущий каталог содержит исходный текст Texinfo, то вы должны указать это с помощью основной переменной `TEXINFOS'. В общем случае файлы Texinfo могут быть преобразованы в формат info, и поэтому макрос info_TEXINFOS является наиболее часто используемым. Заметьте, что имена файлов исходных текстов Texinfo должны заканчиваться на `.texi' или `.texinfo'.

Если файл `.texi' включает в себя с помощью `@include' файл `version.texi', то он будет сгенерирован автоматически. Файл `version.texi' определяет три макроса Texinfo, на которые вы можете ссылаться: EDITION, VERSION и UPDATED. Первые два макроса содержат номер версии вашего пакета (но для ясности они разделены на две части); последний макрос содержит дату изменения основного файла. Поддержка `version.texi' требует наличия программы mdate-sh; эта программа поставляется с Automake и автоматически включается при запуске automake с ключом --add-missing.

Иногда файл info зависит от более чем одного файла `.texi'. Например, в пакете GNU Hello, файл `hello.texi' включает файл `gpl.texi'. Вы можете сообщить об этих зависимостях Automake, используя переменную texi_TEXINFOS. Вот как это делается в GNU Hello:

info_TEXINFOS = hello.texi
hello_TEXINFOS = gpl.texi

По умолчанию Automake требует наличия файла `texinfo.tex' в том же каталоге, что и исходные файлы Texinfo. Однако, если вы используете в файле `configure.in' макрос AC_CONFIG_AUX_DIR (see section `Hахождение ввода `configure'' in Руководство Autoconf), то `texinfo.tex' ищется в заданном каталоге. Automake устанавливает файл `texinfo.tex', если задан ключ `--add-missing'.

Если в вашем пакете файлы Texinfo находятся в нескольких каталогах, то вы можете использовать переменную TEXINFO_TEX для того, чтобы сообщить Automake, где найти файл `texinfo.tex'. Значением этой переменной должен быть относительный путь от текущего файла `Makefile.am' к файлу `texinfo.tex':

TEXINFO_TEX = ../doc/texinfo.tex

Ключ `no-texinfo.tex' может быть использован для отмены требования наличия файла `texinfo.tex'. Однако предпочтительней использование переменной TEXINFO_TEX, поскольку это позволяет работать цели dvi.

Automake создает цель install-info; она, очевидно, используется некоторыми. По умолчанию страницы info устанавливаются при выполнении `make install'. Это поведение может быть изменено, используя ключ no-installinfo.

Страницы руководства

Пакет также может включать в свой состав справочные страницы (но взгляните на стандартны GNU за информацией о них, section `Man Pages' in The GNU Coding Standards). Страницы руководства объявляются с помощью основной переменной `MANS'. Обычно используется макрос man_MANS. Справочные страницы автоматически устанавливаются в зависимости от расширения файлов в соответствующие подкаталоги mandir. Они не включаются в состав дистрибутива автоматически.

По умолчанию страницы руководства устанавливаются при выполнении `make install'. Однако, поскольку проекты GNU не требуют наличия справочных страниц, то многие разработчики проектов не расходуют время на поддержание справочных страниц в обновленном состоянии. В этих случаях опция no-installman отключит установку справочных страниц по умолчанию. Пользователь все равно будет иметь возможность явно установить справочные страницы, используя команду `make install-man'.

Вот как документация обрабатывается в пакете GNU cpio (который включает в себя как документацию в Texinfo, так и справочные страницы):

info_TEXINFOS = cpio.texi
man_MANS = cpio.1 mt.1
EXTRA_DIST = $(man_MANS)

Исходные тексты Texinfo и страницы info считаются исходными файлами и включаются в состав дистрибутива.

В настоящее время страницы руководства не рассматриваются как исходные файлы, потому что зачастую они генерируются автоматически. Именно поэтому они и не включаются автоматически в состав дистрибутива.


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