Jak pisać strony podręcznika man? [Zamknięte]

16

Jak napisać stronę podręcznika?

Gdzie mogę znaleźć odniesienie do wszystkich kodów formatujących?

Czy są jakieś dobre tutoriale na temat pisania stron podręcznika?

Jaki jest najwygodniejszy sposób napisania strony podręcznika? Czy powinienem wpisać go bezpośrednio w edytorze tekstu? Czy są edytory WYSIWYG? A może powinienem napisać go w innym formacie, a następnie przekonwertować?

Jakie zasady powinna stosować dobra strona podręcznika?

documentation

— amarillion
źródło

To pytanie wydaje się zbyt ogólne. Udało mu się tylko przyciągnąć garść odpowiedzi zawierających tylko linki i kilka niepotwierdzonych opinii.

— 200_success

man man, man groff.

— Jenny D

13

Oto kilka stron internetowych, które pomogą Ci zacząć:

Kilka przydatnych narzędzi:

— Wstrzymano do odwołania.
źródło

6

Istnieją narzędzia do pisania stron podręcznika, które omijają formatowanie troff. strony to mały, dobrze odgraniczony język i łatwy do celowania.

Dwa popularne narzędzia to:

xmltoman , mały i dobrze zorganizowany język xml, który może generować strony podręczne i HTML. Jest używany przez projekty Lennarta Poetteringa, na przykład syrep i pulseaudio .
asciidoc , używany na przykład przez git .

yodl i zoem wydają się być inne formaty miły w tej przestrzeni.

Podsumowując, poleciłbym xmltoman, ponieważ jest to bardzo specyficzny dla strony dsl dsl, który poprowadzi cię ściśle.

— Tobu
źródło

„dsl” == „język specyficzny dla domeny”?

— Wstrzymano do odwołania.

tak (da. si. 15 znaków)

— Tobu

1

Inną dobrą opcją jest ronn , który odczytuje powszechnie używany język znaczników tekstu Markdown.

— poolie

5

Napisałem dość obszerny artykuł na blogu na ten temat, który można znaleźć tutaj:

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

— Nathan Osman
źródło

4

Przydałoby się przynajmniej streszczenie tego artykułu - same linki są bezwartościowe, gdy połączona strona nieuchronnie się poruszy lub zniknie.

— Caleb

Nie zgadzam się z Calebem. To jest sieć. Sieć oparta jest na linkach, a stackexchange nie zawiera w tym względzie żadnego specjalnego wyjątku. Kopiowanie treści przynosi efekt przeciwny do zamierzonego. Cokolwiek złego może się stać z tą stroną lub dokumentem, może się również przytrafić tej stronie . Nie możemy gromadzić zeskrobanych kopii całej zawartości tylko dlatego, że reszta sieci może zniknąć. (Zostaw to zadanie stronom takim jak maszyna do powrotu).

— Kaz.

Kaz, możesz się nie zgodzić, ale komentarz Caleba jest zdecydowanie najlepszą praktyką ServerFault.

— MadHatter

2

Nie znam żadnych IDE ani samouczków, ale możesz zacząć od skopiowania istniejącej strony podręcznika i zmodyfikować ją zgodnie z własnymi potrzebami.

Aby zapoznać się z językiem groff z makrami MAN (który jest używany przez stronę man), odwiedź stronę man groff_man lub przeczytaj tutaj online

— Dan Andreatta
źródło

2

Spójrz na projekt Ronn . Jest to zniżka do generatora stron podręcznika. Może również generować strony podręcznika w formacie HTML, jak to .

Podoba mi się pomysł napisania całej dokumentacji oprogramowania w jednym formacie. Markdown IMO to dobry wybór

— Bruno Polaco
źródło