Es ist eine sehr häufige Tatsache, dass niemand gerne Dokumentation schreibt. Heck, niemand liest es auch gerne gerne. Es gibt jedoch Zeiten, in denen wir es lesen müssen, um das Projekt pünktlich zu beenden oder, insbesondere bei der Arbeit in der Softwareentwicklung, sogar zu schreiben. Wenn Sie es nur lesen müssen, haben wir Sie immer dazu ermutigt, dies zu tun, aber wenn Sie die manuellen Seiten schreiben müssen und einen Kickstart benötigen, ist hier der Artikel für Sie. Wenn Sie zuvor mit HTML gearbeitet haben, wird Ihr Leben einfacher, aber wenn nicht, ist es in Ordnung. Schreiben von Handbuchseiten für Linux ist trotz des Aussehens der Seiten beim Lesen in einfacher Text nicht so schwer. Im Grunde benötigen Sie also einige Linux -Kenntnisse und die Möglichkeit, einen Texteditor zu verwenden. Sie lernen (natürlich mit Beispielen) die Hauptkonzepte in der Textformatierung, die auf Menschenseiten angewendet werden und wie man eine einfache manuelle Seite schreibt. Da wir Yest als Beispiel für unser C -Entwicklungs -Tutorial verwendet haben, werden wir Snippets von seiner manuellen Seite verwenden, um unseren Standpunkt während dieses Artikels zu veranschaulichen.

Ein bisschen Geschichte

Die ersten geschriebenen manuellen Pakete sollen 1971 von Dennis Ritchie und Ken Thompson verfasst werden. Die verwendete Formatierungssoftware war TOFF, und dieses Format wird bis heute verwendet, obwohl die Tools möglicherweise unterschiedlich sein können. Das Textformatierungswerkzeug auf Linux -Systemen ist jetzt verwiesen, wobei das führende 'g' von GNU stammt. Die Existenz von Groff ist der Tatsache zu verdanken, dass Terminals, wenn Troff geschrieben wurde, etwas anderes in Bezug auf die Fähigkeiten als das, was sie heute meinen,. Ein weiterer starker Anreiz für das GNU -Projekt zur Schaffung von Groff war die proprietäre Lizenz von Trooff. Troff lebt immer noch in anderen UNIX -Systemen wie OpenSolaris oder Plan9 weiter, obwohl unter Open -Source -Lizenzen.

Bevor wir anfangen, müssen wir Ihnen etwas über *Roff: Es sind zum Beispiel Tex Software erzählt, und es ist eine Sprache in seiner eigenen Recht. Wir werden diesen Artikel nicht in ein Madenhandbuch verwandeln, noch werden wir eine Liste von Unterschieden zwischen Groff und Troff erstellen. Dies ist nur ein Starter für ein einfaches Schreiben von manuellem Seite. Wenn Sie mehr benötigen, finden Sie viele Dokumentationen im Internet.

Alternativen

Wenn Sie nach dem Lesen das Gefühl haben, dass die Syntax entmutigend ist, haben wir eine Lösung für Ihr Problem: pod2man. POD steht für einfache alte Dokumentation und bietet eine einfachere Syntax, und es gibt POD2man, ein Perl -Modul (Teil von Perlpod), das Dokumentation übersetzt, die im POD -Format in das Manpage -Format geschrieben wurden. Perlpod bietet auch Tools zum Konvertieren von POD in Text oder HTML.

Handbuchseiten

Kategorien

Handbuchseiten sind in Kategorien unterteilt, je nachdem, welches Fach sie behandeln. Sie unterscheiden sich nicht in Linux -Verteilungen, aber andere UNIX -Systeme haben unterschiedliche Möglichkeiten, um manuelle Seiten zu teilen. Verwendung

 $ MAN MAN

Geben Sie Ihnen diese Kategorien und viel mehr in Bezug auf die Verwendung des Man -Befehls. Die Kategorien unter Linux sind wie folgt:

 1 ausführbare Programme oder Shell -Befehle
2 Systemaufrufe (vom Kernel bereitgestellte Funktionen)
3 Bibliotheksaufrufe (Funktionen in Programmbibliotheken)
4 Sonderdateien (normalerweise in /dev)
5 Dateiformate und Konventionen zB /etc /passwd
6 Spiele
7 Verschiedenes (einschließlich Makropakete und Konventionen), e.G. Mann (7), Groff (7)
8 Systemverwaltungsbefehle (normalerweise nur für Root)
9 Kernel -Routinen [Nicht -Standard]

Sie werden empfohlen, die Manual Manual -Seite zu lesen, da dies kein Tutorial darüber ist, wie es geht verwenden sie, aber wie zu schreiben ihnen.

Layout einer manuellen Seite

Seit vor einigen Jahren gibt es einen Standard, wie man Handbuchseiten schreibt, was sie enthalten sollten, und Stilprobleme. Sie sollten präzise sein, das Layout respektieren und so viele Informationen in so wenig Raum wie möglich komprimieren. Wenn man ein 100-seitiges Handbuch sieht, wird der erste Reflex weggehen.

Weit weit weg. Auf der anderen Seite wird eine kurze, aber informative Handbuchseite, auf der dem Leser das wissen, dass er wissen möchte. Wenn das Programm, für das Sie Schaltseiten schreiben. Jetzt möchten wir vermeiden, langweilig oder beängstigend zu sein. Beginnen wir mit dem Layout.

Zunächst sollte der Name der Datei $ CommandName sein.$ kategorie wie zum Beispiel vim.1. Diese Datei sollte bei der Installation gzipiert und in das entsprechende Verzeichnis kopiert werden, das für VIM/usr/Share/Man/Man1 sein sollte. Die nicht komprimierte Datei ist eine einfache Textdatei, nichts weiter. Wenn Sie eine manuelle Seite lesen, erhalten Sie eine Vorstellung davon. Nicht alle diese sind obligatorisch, aber es wird empfohlen, dass Sie ihnen alle Platz für eine bessere Benutzererfahrung ausreichen sollten, für eine bessere Benutzererfahrung.

Die Markup -Sprache

Wie bereits erwähnt, finden Sie die Syntax einfach, wenn Sie es gewohnt sind, XML oder HTML zu schreiben. In der Tat ist es sowieso einfach, wenn Sie sich daran gewöhnt haben. Wir beginnen mit dem Überschrift, Und die erste Überschrift ist die Titelüberschrift. Die anderen sind normalerweise auf Makros gestoßen (das Äquivalent von Tags in Markup -Sprachen) sind Betreffüberschriften Und Absätze, Aber mehr zu diesen später.

Die Titelüberschrift muss Folgendes enthalten: Name, Kapitel (Kategorie) und das Datum, an dem die Seite zuletzt geändert wurde. Um Ihre Füße nass zu machen, sollte es so aussehen:

.Th yest 1 "19. April 2010"

TH steht für Titelüberschriften und da es sich um ein Makro handelt. yest ist der Name der Anwendung, Kategorie 1, zuletzt am 19. April 2010 bearbeitet. Bevor wir weiter gehen, möchten Sie möglicherweise einige Kommentare in Ihre Datei einfügen. Diese beginnen mit .\ ”(DOT Backslash -Zitat) und kann so aussehen:

.\ ”Copyright 2004, 2006, 2010 Kimball Hawkins .

.\" Alle Rechte vorbehalten.

Fügen Sie nun diese Zeilen ein (die Überschrift und den Kommentar darüber) und überprüfen Sie das Ergebnis mit

 $ Groff -Man -tascii yest.1

-Tascii weist das Groff an, im ASCII -Format (Text) auszugeben, aber das Groff unterstützt andere Arten von Ausgabe. Wir laden Sie ein, sich dafür auf die Hubsthandbuchseite anzusehen.

Als nächstes, da wir jetzt wissen, wie man mit Titelüberschriften umgeht, gehen wir zur Abschnitt Überschriften. Wie Sie vielleicht vermutet haben, ist das Makro .SH und was es tut, ist den Namen, die Zusammenfassung, die Beschreibung usw. Abschnitte wie oben geschrieben. Die Syntax wird also:

.Sch Name yest - Datum Manipulation Dienstprogramm.

.Sch ZUSAMMENFASSUNG .B yest \ fr -Help

.P .B yest \ fr -LIZENSE

.P .B yest \ fr -Verssion

.P .B yest \ fr [\ fb-idf = \ fist \ fr] [\ fb-tz = \ fitzone \ fr] [\ fb- \ fr \ fr | \ fbm \ fr]] [\ fidate \ fr] [\ fiformat-String \ fr] .

Sch Beschreibung Dies wird als ""Yest"" bezeichnet. Dieses Dienstprogramm kennt sich über Schaltjahr, Tageslichtsparungszeit und solche Variationen. Dieses Dienstprogramm fügt oder subtrahiert Tage, Stunden und/oder Minuten ab einem bestimmten Datum und gibt die Ergebnisse im angegebenen Format aus. Die Standardeinstellung ist, wenn keine Anpassung angegeben ist, ""-1d"" ist

Dies ist natürlich nur ein Teil des Handbuchs, aber lassen Sie uns sehen, was die neuen Makros bedeuten ... B steht für BOLD und wir empfehlen, diesen Code in eine Datei einzufügen und ihn wie Sie zu testen, mit dem oben genannten Groff -Befehl… P steht vor für Absatz, denn wie Sie sehen können, nach jedem .P Es gibt eine doppelte neue Zeile auf der formatierten Seite. Die \ f* sind Schriftstellungs -Fluchtsequenzen, und was dies bedeutet, ist, dass nach dem Wort ""Synopsis"" .B fordert Groff an, fett gedruckt zu drucken. Nach dem Wort „yest“, das tatsächlich fett gedruckt ist, müssen wir ""-Help"" mit regulären Schriftarten gedruckt werden. Umgekehrt steht \ fb für „drucken in fett“ und kann mit austauschbar mit verwendet werden .B . Mit Logik können Sie verstehen, wofür \ fl zum Beispiel steht.

Einfacher Text, der Text ist, der keine Überschrift oder Abschnitt ist, ist in Absätze enthalten. Ein einfacher Absatz wird durch a abgegrenzt .PP -Makro, das einen kleinen vertikalen Raum zwischen dem tatsächlichen und dem nächsten erstellt. Wenn Sie einen markierten Absatz wünschen, können Sie ihn mit haben .Tp . Als nächstes werden wir darüber sprechen Vertiefung.

Die relative Eindringung bedeutet, dass der Text relativ zum vorhergehenden und folgenden Text eingewiesen ist. Verwenden .RS (relativer Start) und um es zu beenden .Re (relatives Ende). Hier ist ein Beispiel:

.Rs.7i Wenn es in der Zeichenfolge Leerzeichen oder Sonderzeichen gibt, muss es zitiert werden. Das Programm erkennt die meisten Konventionen von Fbecho \ fr-ähnlichen Flucht wie „\\ n“ (Newline) und „\\ T“ (Tab) in \ fiformat-String \ fr an, und Octal Escapes (\\ 0nn) werden unterstützt.

.P Wenn nur eine Tagesanpassung angegeben wird, ist der Standard \ fiformat-String \ fr ""%x"". Wenn \ fiadjustment \ fr enthält, wird ein zeitliches Element, der Standard \ fiformat-String \ fr wird ""%x-%r"".

.BETREFF

Wie Sie sehen können, können Sie eine haben .P -Makro in einem relativ eingerichteten Textstück… P ist nur ein Alias ​​für .PP, damit sie austauschbar verwendet werden können. Sie haben vielleicht das ""bemerkt"".7i ”nach .RS: Das sagt Groff, mit sieben Räumen den Text im Inneren einzustufen.

Die Verwendung von Tabellen ist genauso einfach wie die Verwendung von relativen Einrücken: .Ts und .Te. Sie können, wie bereits erwähnt, ein Wort oder einen gesamten Absatz (aus typografischer Sicht, das heißt) mit Makros ändern. Die drei Möglichkeiten, wie Sie einen Charakter verändern können, sind, wie jeder weiß, mutig, kursiv und römisch. Also zum Beispiel, .BI verändert den folgenden Text darin, dass er beide erscheint deutlich Und kursiv.

Abschluss

Bitte beachten Sie, dass dies möglicherweise ausreicht, um Ihnen den Einstieg zu erleichtern, aber es ist nicht vollständig. Dies sind nicht alle Makros, und wenn Sie zu einem BSD -System wechseln, stellen Sie möglicherweise fest, dass sie Mandoc anstelle von Groff verwenden. Als nächstes lesen Sie bitte ein paar manuelle Seiten, um die wichtigsten Konventionen zu sehen, die respektiert werden müssen, z. Die Zahnspangen müssen verwendet werden. Alles in allem ist das Dokumentieren Ihrer Software, auch wenn Sie nicht von Ihrem Arbeitgeber gezwungen sind, gut für Sie und die Benutzer Ihrer Software. Sie werden als sorgfältiger Entwickler angesehen und die Benutzer können Ihre Erstellung leichter verwenden und wissen, was sie können und was sie nicht können.

Verwandte Linux -Tutorials:

• Dinge zu installieren auf Ubuntu 20.04
• Dinge zu tun nach der Installation Ubuntu 20.04 fokale Fossa Linux
• So führen Sie unbeaufsichtigte Linux -Installationen mit Kickstart durch
• So überprüfen Sie die Akkulaufzeit bei Ubuntu
• Dinge zu tun nach der Installation Ubuntu 22.04 Jammy Quallen…
• Eine Einführung in Linux -Automatisierung, Tools und Techniken
• Hung Linux System? Wie man zur Befehlszeile entkommt und…
• Dinge zu installieren auf Ubuntu 22.04
• Mint 20: Besser als Ubuntu und Microsoft Windows?
• Installieren Sie Arch Linux in VMware Workstation