Come scrivo le pagine man? [chiuso]

16

Come scrivo una pagina man?

Dove posso trovare un riferimento di tutti i codici di formattazione?

Ci sono dei buoni tutorial per scrivere pagine man?

Qual è il modo più conveniente per scrivere una pagina man? Devo inserirlo direttamente in un editor di testo? Ci sono editor WYSIWYG? O dovrei scriverlo in un formato diverso e poi convertirlo?

Quali regole dovrebbe seguire una buona man page?

documentation

— amarillion
fonte

Questa domanda sembra essere troppo ampia. È riuscito solo ad attrarre un sacco di risposte solo link e alcune opinioni non supportate.

— 200_successo

man man, man groff.

— Jenny D,

13

Ecco alcune pagine Web che ti aiuteranno a iniziare:

Un paio di strumenti utili:

— In pausa fino a nuovo avviso.
fonte

6

Ci sono strumenti per scrivere pagine man che aggirano la formattazione di troff. le manpage sono un linguaggio piccolo, ben delimitato e facile da indirizzare.

Due strumenti popolari sono:

xmltoman , un linguaggio xml piccolo e ben strutturato in grado di generare manpage e html. È utilizzato dai progetti di Lennart Poettering, ad esempio syrep e pulseaudio .
asciidoc , usato ad esempio da git .

yodl e zoem sembrano essere altri formati carini in questo spazio.

Tutto sommato, consiglierei xmltoman perché è una dsl molto specifica per la manpage che ti guiderà da vicino.

— Tobu
fonte

"dsl" == "lingua specifica del dominio"?

— In pausa fino a nuovo avviso.

si (da. si. 15 caratteri)

— Tobu

1

Un'altra buona opzione è ronn , che legge il linguaggio di markup del testo Markdown più ampiamente utilizzato.

— poolie

5

Ho scritto un articolo di blog piuttosto ampio sull'argomento, che puoi trovare qui:

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

— Nathan Osman
fonte

4

Sarebbe utile se tu potessi almeno riassumere l'articolo qui - i collegamenti da soli sono inutili una volta che la pagina collegata si sposta inevitabilmente o scompare.

— Caleb,

Non sono d'accordo con Caleb. Questa è la rete Il web si basa su collegamenti e stackexchange non presenta alcuna eccezione speciale a questo. La copia del contenuto è controproducente. Qualunque cosa brutta possa accadere a quella pagina o documento può succedere anche a questa . Non possiamo accumulare copie scaricate di tutto il contenuto solo perché il resto del Web potrebbe scomparire. (Lascia quel lavoro su siti come la macchina di ritorno).

— Kaz,

Kaz, potresti non essere d'accordo, ma il commento di Caleb è sicuramente la migliore pratica di ServerFault.

— MadHatter,

2

Non conosco IDE o tutorial, ma puoi iniziare copiando una pagina man esistente e modificandola in base alle tue esigenze.

Per un riferimento del linguaggio groff con le macro MAN (che è ciò che viene utilizzato da una pagina man) consultare la pagina man groff_man o leggerla online qui

— Dan Andreatta
fonte

2

Dai un'occhiata al progetto ronn . È un markdown per il generatore di pagine man. Può anche generare le pagine man in html, in questo modo .

Mi piace l'idea di scrivere tutta la documentazione del mio software in un unico formato. Markdown IMO è una buona scelta

— Bruno Polaco
fonte