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

в настоящее время 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 `finding `configure' input' in the autoconf manual), то `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.