Как лучше всего создавать справочные страницы? Должен ли я писать, используя стандартные макросы man, или сейчас доступен какой-то умный пакет, который берет какой-то XML-ориентированный источник и может выводить man-страницы, HTML, ASCII и что-то еще?
Спасибо
Для моей программы atinout я использовал ronn, который позволяет вам писать справочные страницы с очень, очень удобочитаемым синтаксисом, подобным уценке. Я очень доволен этим.
atinout(1) -- Send AT commands to modem, capturing the response
===============================================================
## SYNOPSIS
`atinout` <input_file>|`-` <modem_device> <output_file>|`-`<br>
`atinout` `--version`<br>
`atinout` `--usage`<br>
`atinout` `--help`<br>
## DESCRIPTION
**Atinout** reads a list of AT commands. It sends those commands one by one
to the modem, waiting for the final result code for the
currently running command before continuing with the next command in
the list. The output from the commands is saved.
...
atinout?
- person vy32; 15.10.2017
Раньше я использовал версию nroff для GNU, которая называлась groff, для написания справочных страниц.
Хорошая вводная статья об этом здесь:
http://www.linuxjournal.com/article/1158
Doxygen — это то, что вам нужно. Имейте в виду, что он предназначен для документирования исходного кода, но вы можете легко адаптировать его.
Он также может генерировать документацию в формате html, pdf и латекс.
Если вы хотите написать один раз и создать различные выходные форматы, такие как справочные страницы, HTML, обычный текст или даже PDF, тогда docbook должен работать лучше всего.
В сообществе Tcl обычно используется инструмент doctools, который может создавать ограниченное (но полезное) подмножество формата страницы руководства, подходящего для рендеринга с помощью groff или nroff. Он также может напрямую генерировать как обычный текст, так и HTML.
