Comment écrire des pages de manuel? [fermé]

16

Comment écrire une page de manuel?

Où puis-je trouver une référence de tous les codes de formatage?

Existe-t-il de bons didacticiels sur la rédaction de pages de manuel?

Quelle est la façon la plus pratique d'écrire une page de manuel? Dois-je le saisir directement dans un éditeur de texte? Existe-t-il des éditeurs WYSIWYG? Ou dois-je l'écrire dans un format différent, puis le convertir?

Quelles règles une bonne page de manuel doit-elle suivre?

documentation

— amarillion
source

Cette question semble trop large. Il n'a réussi qu'à attirer un tas de réponses de liens uniquement et quelques opinions non étayées.

— 200_success

man man, man groff.

— Jenny D

13

Voici quelques pages Web qui vous aideront à démarrer:

Quelques outils utiles:

— En pause jusqu'à nouvel ordre.
source

6

Il existe des outils pour écrire des pages de manuel qui contournent le formatage troff. les pages de manuel sont un petit langage bien délimité et facile à cibler.

Deux outils populaires sont:

xmltoman , un petit langage xml bien structuré qui peut générer des pages de manuel et du html. Il est utilisé par les projets de Lennart Poettering, syrep et pulseaudio par exemple .
asciidoc , utilisé par git par exemple .

yodl et zoem semblent être d'autres formats sympas dans cet espace.

Dans l'ensemble, je recommanderais xmltoman car c'est un dsl très spécifique à la page de manuel qui vous guidera de près.

— Tobu
source

"dsl" == "langue spécifique au domaine"?

— pause jusqu'à nouvel ordre.

oui (da. si. 15 car.)

— Tobu

1

Une autre bonne option est ronn , qui lit le langage de balisage de texte Markdown plus largement utilisé.

— poolie

5

J'ai écrit un article de blog assez complet sur le sujet, que vous pouvez trouver ici:

http://2buntu.com/articles/1034/how-to-write-a-manpage/

— Nathan Osman
source

4

Il serait utile que vous puissiez au moins résumer l'article ici - les liens seuls ne valent rien une fois que la page liée se déplace ou disparaît inévitablement.

— Caleb

Je ne suis pas d'accord avec Caleb. C'est le web. Le Web est basé sur des liens, et stackexchange ne comporte aucune exception spéciale à cela. La copie de contenu est contre-productive. Toute mauvaise chose qui peut arriver à cette page ou à ce document peut aussi arriver à celui- ci. Nous ne pouvons pas thésauriser des copies grattées de tout le contenu simplement parce que le reste du Web pourrait disparaître. (Laissez ce travail à des sites comme la machine de retour).

— Kaz

Kaz, vous n'êtes peut-être pas d'accord, mais le commentaire de Caleb est certainement la meilleure pratique de ServerFault.

— MadHatter

2

Je ne connais aucun IDE ou tutoriel, mais vous pouvez commencer par copier une page de manuel existante et la modifier selon vos besoins.

Pour une référence du langage groff avec les macros MAN (qui est utilisé par une page de manuel) consultez la page de manuel groff_man , ou lisez-la en ligne ici

— Dan Andreatta
source

2

Jetez un œil au projet ronn . C'est un démarque pour le générateur de page de manuel. Il peut également générer les pages de manuel en html, comme ceci .

J'aime l'idée d'écrire toute ma documentation logicielle dans un seul format. Markdown IMO est un bon choix

— Bruno Polaco
source