Wie schreibe ich Manpages? [geschlossen]

16

Wie schreibe ich eine Manpage?

Wo finde ich eine Referenz aller Formatierungscodes?

Gibt es gute Tutorials zum Schreiben von Manpages?

Was ist der bequemste Weg, eine Manpage zu schreiben? Soll ich es direkt in einen Texteditor eingeben? Gibt es WYSIWYG-Editoren? Oder soll ich es in ein anderes Format schreiben und dann konvertieren?

Welche Regeln sollte eine gute Manpage befolgen?

documentation

— Amarillion
quelle

Diese Frage scheint zu weit gefasst zu sein. Es ist nur gelungen, eine Reihe von Nur-Link-Antworten und einige nicht unterstützte Meinungen zu gewinnen.

— 200_success

man man, man groff.

— Jenny D sagt Reinstate Monica

13

Hier sind einige Webseiten, die Ihnen den Einstieg erleichtern:

Einige nützliche Tools:

— Bis auf weiteres angehalten.
quelle

6

Es gibt Tools zum Schreiben von Manpages, die die Formatierung von troff umgehen. Hilfeseiten sind eine kleine, gut abgegrenzte Sprache und leicht zu erreichen.

Zwei beliebte Tools sind:

xmltoman , eine kleine und gut strukturierte XML-Sprache, die Manpages und HTML generieren kann. Es wird zum Beispiel von Lennart Poetterings Projekten syrep und pulseaudio verwendet .
asciidoc , zum Beispiel von git .

Jodl und Zoem scheinen andere schöne Formate in diesem Raum zu sein.

Alles in allem würde ich xmltoman empfehlen, da es ein sehr manpage-spezifisches dsl ist, das Sie genau führt.

— Tobu
quelle

"dsl" == "domänenspezifische Sprache"?

— Bis auf weiteres angehalten.

yes (da. si. 15 Zeichen.)

— Tobu

1

Eine weitere gute Option ist ronn , die die am weitesten verbreitete Markdown-Textauszeichnungssprache liest.

— Poolie

5

Ich habe einen ziemlich ausführlichen Blog-Artikel zu diesem Thema verfasst, den Sie hier finden:

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

— Nathan Osman
quelle

4

Es wäre hilfreich, wenn Sie den Artikel hier zumindest zusammenfassen könnten - Links allein sind wertlos, sobald die verknüpfte Seite unweigerlich verschoben oder entfernt wird.

— Caleb

Ich stimme Caleb nicht zu. Das ist das Web. Das Web basiert auf Links und StackExchange kennt keine besonderen Ausnahmen. Das Kopieren von Inhalten ist kontraproduktiv. Was auch immer schlechte Sache kann passieren , dass Seite oder ein Dokument kann auch passieren diese ein. Wir können keine verkratzten Kopien aller Inhalte horten, nur weil der Rest des Webs möglicherweise verschwindet. (Überlassen Sie diesen Job Sites wie der Wayback-Maschine).

— Kaz

Kaz, dem können Sie vielleicht nicht zustimmen, aber Calebs Kommentar ist definitiv eine bewährte Methode für ServerFault.

— MadHatter unterstützt Monica

2

Ich kenne keine IDEs oder Tutorials, aber Sie können zunächst eine vorhandene Manpage kopieren und an Ihre Bedürfnisse anpassen.

Eine Referenz der groff-Sprache mit MAN-Makros (die von einer Manpage verwendet wird) finden Sie auf der Manpage groff_man oder online hier

— Dan Andreatta
quelle

2

Schauen Sie sich das ronn-Projekt an . Es ist ein Abschlag für den Manpage-Generator. Es kann auch die man - Seiten in HTML, wie erzeugt diese .

Ich mag die Idee, alle meine Software-Dokumentationen in einem Format zu schreiben. Markdown IMO ist eine gute Wahl

— Bruno Polaco
quelle