Extrait des GNU coding standards FSF: GNU Manuals Don't use Unix man pages as a model for how to write GNU
documentation; most of them are terse, badly structured, and give
inadequate explanation of the underlying concepts. (There are, of course,
some exceptions.) Also, Unix man pages use a particular format which is
different from what we use in GNU manuals. Man
Pages In the GNU project, man pages are secondary. It is not necessary or
expected for every GNU program to have a man page, but some of them do.
It's your choice whether to include a man page in your program.
When you make this decision, consider that supporting a man page requires
continual effort each time the program is changed. The time you spend on
the man page is time taken away from more useful work.
For a simple program which changes little, updating the man page may be a
small job. Then there is little reason not to include a man page, if you
have one.
For a large program that changes a great deal, updating a man page may be
a substantial burden. If a user offers to donate a man page, you may find
this gift costly to accept. It may be better to refuse the man page unless
the same person agrees to take full responsibility for maintaining it--so
that you can wash your hands of it entirely. If this volunteer later ceases
to do the job, then don't feel obliged to pick it up yourself; it may be
better to withdraw the man page from the distribution until someone else
agrees to update it.
When a program changes only a little, you may feel that the discrepancies
are small enough that the man page remains useful without updating. If so,
put a prominent note near the beginning of the man page explaining that you
don't maintain it and that the Texinfo manual is more authoritative. The
note should say how to access the Texinfo documentation.
J'hésite à faire des commentaires : ces documents parlent d'eux même. Le
logiciel libre se veut pouvoir être utilisable par tous et partageable. Les
manuels sont une choses importantes pour que les personnes puissent
utiliser les logiciels. Les man pages ont deux choses pour elles :
elles sont utilisées sur tous les systèmes utilisées sur tous les
Unix dignes de ce nom,
et elles sont standards.
Le type de documentation conseillée en lieu et place le format
texinfo a juste pour seul avantage de tourner sur emacs le logiciel
de saint IgnuCIUS (sa sainteté R. M.Stallman.)
(Évidemment, j'ai bien compris que St IgnuCIUS est une preuve
d'auto ironie de RMS, de toute façon personne ne peut se prendre au
sérieux dans un costume pareil.)
4. DOCUMENTATION CONVENTIONS
Here are the conventions that are currently used for LDP documents. If you
are interested in writing another document using different conventions,
please let us know of your plans first.
All HOWTO documents must be in one of the two SGML formats:
LinuxDoc or DocBook. LinuxDoc is the simplest while DocBook is more
complex with more features.
The guides -- full books produced by the LDP -- have historically
been done in LaTeX, as their primary goal has been to be printed
documentation. However, guide authors have been moving towards SGML with
the DocBook DTD, because it allows them to create more different kinds of
output, both printed and on-line. If you use LaTeX, we have a style file
you can use to keep your printed look consistent with other LDP
documents.
The man pages -- the Unix standard for online manuals -- are created
with the Unix standard nroff man (or BSD mdoc) macros.
Contrairement à la vision GNU, les systèmes d'exploitation Unix qui se
veulent utilisables, investissent des efforts particuliers dans le fait
d'avoir des pages de
manuels complètes et auto-suffisantes.
Le futur
Le projet XML/Docbook permet
de générer le contenu indépendamment de la forme finale. Donc, finalement
utiliser des man pages, texinfo, des pages web n'est plus l'enjeu.
Conclusions
J'espère qu'après ces morceaux choisis vous vous serez votre opinion. Le
mienne tend à dire qu'il ne faut pas s'intéresser à ce que l'on vous dit
comme étant le BIEN ou le MAL, mais au résultat. J'espère que si vous avez
l'intention d'écrire un programme vous livrerez des documentations claires
et utilisables contenant:
