Quelle est la meilleure façon de créer des pages de manuel? Devrais-je écrire en utilisant les macros man standard, ou y at-il un paquet intelligent disponible maintenant qui prend une sorte de source XML-ified et peut produire des pages man, HTML, ASCII, et quoi d'autre?Meilleure façon d'écrire des pages de manuel?
Merci
Pour mon programme atinout J'ai utilisé ronn qui vous permet d'écrire des pages de man dans une syntaxe de type markdown très, très lisible. Je suis extrêmement content de cela.
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.
...
C'est plutôt cool! – vy32
Bien, comment distribuez-vous un script de configuration qui lance automatiquement 'atinout'? – vy32
Vous voulez dire "... automatiquement run ronn"? Eh bien, je ne le fais pas. Les deux hat atinout n'ont pas de script configure et aussi je distribue un premade atinout.1 pour que ronn ne soit pas une dépendance de construction dure (seulement si vous voulez modifier la page de man en avez-vous besoin). – hlovdal
Doxygen est ce que vous recherchez. N'oubliez pas qu'il est conçu pour documenter le code source, mais vous pouvez facilement l'adapter.
Il peut également générer de la documentation html, pdf et latex.
Doxygen est un système puissant, mais je n'arrive pas à comprendre comment je l'ai fait pour émettre de belles pages man pour les options de ligne de commande et autres. – vy32
Ya. Vous avez probablement besoin d'autre chose. –
Vous pouvez obtenir doxygen pour générer des pages au format man en définissant GENERATE_MAN, puis éventuellement MAN-OUTPUT (pour définir l'emplacement de la sortie) dans le fichier de configuration doxygen: http://www.doxygen.nl/config.html#cfg_man_output Comme mentionné dans docs, si vous laissez la valeur man-output vide, les pages man seront placées sous un sous-répertoire appelé 'man'. – DEzra
Si vous envisagez d'écrire une seule fois et de générer différents formats de sortie tels que les pages de manuel, HTML, txt simple ou PDF, alors docbook devrait fonctionner au mieux.
docbook ne produit pas de pages man. Il peut les ingérer, mais ne pas les produire. – vy32
Je pense que shadow-utils l'utilise avec succès, quelque chose comme "xsltproc -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/profile-docbook.xsl $ FILE" –
J'ai précédemment utilisé la version GNU de nroff appelée groff pour écrire des pages man.
article Nice intro ici:
+1 même si ce n'est pas vraiment l'outil pour * les écrire * autant que pour les mettre en forme. –
vrai, bon point :-) – DEzra
Un outil qui est couramment utilisé dans la communauté Tcl est doctools qui peut produire un restreint (mais utile) sous-ensemble du format manpage, approprié pour le rendu avec groff ou nroff. Il peut également générer à la fois du texte brut et HTML directement.
@ vy32: qu'avez-vous fini par utiliser finalement? – Lazer
J'ai fini par le faire dans nroff. – vy32