Titelzeile

Der erste Befehl in einer Handbuchseite nach den Kommentarzeilen (die mit .\" beginnen) sollte

sein. Für Details zu den Argumenten für den Befehlt TH sei auf man-pages(7) verwiesen.

Beachten Sie, dass mit mdoc(7) formatierte BSD-Seiten nicht mit dem Befehl TH beginnen, sondern mit Dd.

Abschnitte

Abschnitte beginnen mit .SH, gefolgt von ihrem Titel.

Der einzige obligatorische Bestandteil ist BEZEICHNUNG. Er sollte der erste Abschnitt werden und in der nächsten Zeile eine einzeilige Beschreibung des Programms folgen:

Es ist überaus wichtig, dass dieses Format eingehalten wird und dass ein Rückwärtsschrägstrich (\) vor dem einzelnen Bindestrich nach dem Elementenamen steht. Dieses Format wird vom Programm mandb(8) benutzt, um eine Datenbank mit Kurzbeschreibungen für die Befehle whatis(1) und apropos(1) aufzubauen. (Lesen Sie lexgrog(1) für weitere Details bezüglich der Syntax des Abschnitts NAME.)

Eine Liste weiterer möglicher Abschnitte einer Handbuchseite finden Sie in man-pages(7).

Schriften

Die Befehle für die Auswahl der Schriftart sind:

.B

Fett

.BI

Fett, abwechselnd mit kursiv (besonders praktisch für Funktions-Deklarationen)

.BR

Fett, abwechselnd mit normalem Schrifttyp (besonders praktisch für den Verweis auf andere Handbuchseiten)

.I

Kursiv

.IB

Kursiv, abwechselnd mit fett

.IR

Kursiv, abwechselnd mit normalem Schrifttyp

.RB

Normaler Schrifttyp, abwechselnd mit fett

.RI

Normaler Schrifttyp, abwechselnd mit kursiv

.SB

Klein, abwechselnd mit fett

.SM

Klein (praktisch für Akronyme)

Traditionell darf ein Befehl bis zu sechs Argumente haben, doch die GNU-Version überschreitet diese Begrenzung. (Sie werden sich aber vielleicht trotzdem auf sechs Argumente beschränken, um portable Handbuchseiten zu schreiben.) Die Argumente werden durch Leerzeichen getrennt. Sollen Argumente Leerzeichen enthalten, müssen die Argumente in doppelte Anführungszeichen eingeschlossen werden. Für die Makros, die wechselnde Schriftarten erstellen, werden hintereinander ohne die dazwischenliegenden Leerzeichen ausgegeben, sodass beispielsweise mit dem Befehl .BR ein Wort im Fettdruck, gefolgt von einem Wort im normalen Schrifttyp dargestellt werden kann. Ohne Argumente wird der Befehl auf die nächste Textzeile angewendet.

Weitere Makros und Zeichenketten

Im Folgenden werden weitere relevante Makros und vordefinierte Zeichenfolgen aufgelistet. Sofern nicht anders angegeben, beenden alle Makros die aktuelle Textzeile. Viele dieser Makros setzen oder verwenden den aktuellen »vorherrschenden Einzug« (prevailing indent). Der Wert für den Einzug wird für jedes Makro mit dem unten erläuterten Parameter i bestimmt. Makros können i auslassen und so der bisher verwendete Einzug beibehalten werden. Als Ergebnis können die folgenden Absätze den gleichen Einzug verwenden, ohne diesen erneut einzugeben. Ein normaler (nicht eingezogener) Absatz setzt den Einzug wieder auf den Standardwert (0,5 Zoll) zurück. Standardmäßig wird der Einzug in der typografischen Einheit En gemessen. Versuchen Sie, die Einzüge in den Einheiten En oder Em festzulegen, da diese sich automatisch an Änderungen der Schriftgröße anpassen. Weitere wichtige Makros sind wie folgt definiert:

Normale Absätze

.LP

Das Gleiche wie .PP (einen neuen Absatz anfangen)

.P

Das Gleiche wie .PP (einen neuen Absatz anfangen)

.PP

Einen neuen Absatz anfangen und den Einzug zurücksetzen

Relativer Randeinzug

.RS i

Anfang des relativen Randeinzugs: bewegt den linken Rand i nach rechts (wenn i weggelassen wird, wird der aktuelle Wert für den Einzug verwendet). Der Wert für den Einzug wird neu auf 0,5 Zoll festgesetzt. Als Ergebnis werden alle folgenden Absätze bis zum nächsten B.RE eingezogen.

.RE

Beendet den relativen Randeinzug und stellt den früheren Wert für den Randeinzug wieder her.

Makros für Absätze mit Einzug

.HP i

Anfang eines Absatzes mit hängendem Einzug: Die linke Rand der ersten Zeile des Absatzes stimmt mit dem normaler Absätze überein, die restlichen Zeilen des Absatzes sind eingezogen.

.IP x i

Eingerückter Absatz mit optionaler hängender Beschriftung. Wenn der Hinweis (das Tag) x weggelassen wird, wird der gesamte folgende Absatz um i eingerückt. Wenn das Tag x vorhanden ist, wird die Beschriftung am linken Rand vor dem folgenden eingerückten Absatz aufgehängt. (Dies entspricht .TP mit dem Unterschied, dass die Beschriftung im Befehl enthalten ist und nicht auf der nächsten Zeile steht.) Wenn die Beschriftung zu lang ist, wird der Text nach der Beschriftung auf die nächste Zeile verschoben. (Es geht kein Text verloren, auch wird kein Text verstümmelt.) Für Aufzählungen mit Aufzählungszeichen verwenden Sie dieses Makro mit \(bu (Aufzählungszeichen) oder \(em (Geviertstrich) als Beschriftung. Für nummerierte Listen verwenden Sie eine Zahl oder einen Buchstaben, denen ein Punkt folgt. Dies vereinfacht die Übersetzung in andere Formate.

.TP i

Beginn eines Absatzes mit einer hängenden Beschriftung. Die Beschriftung wird auf der nächsten Zeile angegeben, aber die Ergebnisse ähneln denen des Befehls .IP.

Makros für Hypertext-Links

.UR URL

Fügt einen Hypertext-Link zu der URI (URL) URL ein, wobei sämtlicher Text bis zum folgenden Makro .UE der Link-Text ist.

.UE [ Nachsatz ]

Beendet den Link-Text des vorhergehenden Makros .UR, wobei der optionale Nachsatz (falls vorhanden, normalerweise eine schließende Klammer und/oder einen Satzendesatzzeichen) sofort folgt. For Ausgabegeräte ohne HTML (z.B. man -Tutf8) folgt dem Link-Text die URL in spitzen Klammern; falls es keinen Link-Text gibt, wird die URL selbst als Link-Text, eingeschlossen in spitze Klammern, ausgegeben. (Nicht auf allen Ausgabegeräten könnten spitze Klammern verfügbar sein.) Für das HTML-Ausgabegerät wird der Link-Text als Hyperlink auf die URL ausgeführt, falls es keinen Link-Text gibt wird die URL selbst als Link-Text ausgegeben.

Diese Makros werden seit GNU-Troff 1.20 (2009-01-05) und Heirloom Doctools Troff seit 160217 (2016-02-17) unterstützt.

Verschiedene Makros

.DT

Stellt den Standardwert für Tabulatoren (alle 0,5 Zoll) wieder her; führt nicht zu einem Zeilenumbruch.

.PD d

Setzt den vertikalen Abstand zwischen Absätzen auf d (ohne Angabe d=0,4v); führt nicht zu einem Zeilenumbruch.

.SS t

Unterüberschriften (ähnlich wie .SH, aber für Unterabschnitte innerhalb eines Abschnitts).

Vordefinierte Zeichenketten

Zum man-Paket gehören die folgenden vordefinierten Zeichenketten:

\*R

Anmeldungssymbol: ®

\*S

Wechsel zur Standard-Schriftgröße

\*(Tm

Markenzeichen: (Tm)

\*(lq

links abgewinkeltes doppeltes Anführungszeichen: “

\*(rq

rechts abgewinkeltes doppeltes Anführungszeichen: ”

Sichere Teilmenge

Obwohl technisch gesehen man ein Troff-Makropaket ist, gibt es eine große Zahl von anderen Werkzeugen, die Handbuchseitendateien verarbeiten und nicht alle Troff-Fähigkeiten implementieren. Daher vermeiden Sie am besten den Einsatz einiger eher exotischer Troff-Fähigkeiten soweit wie möglich, damit andere Werkzeuge korrekt arbeiten können. Vermeiden Sie die Verwendung der verschiedenen Troff-Präprozessoren. (Wenn es sein muss, verwenden Sie tbl(1). Versuchen Sie aber, zweispaltige Tabellen mit den Befehlen IP und TP zu realisieren). Vermeiden Sie Berechnungen, die meisten anderen Werkzeuge können sie nicht verarbeiten. Verwenden Sie einfache Befehle, die leicht in andere Formate zu übersetzen sind. Die folgenden Troff-Makros werden als sicher angesehen: \", ., ad, bp, br, ce, de, ds, el, ie, if, fi, ft, hy, ig, in, na, ne, nf, nh, ps, so, sp, ti, tr.

Sie können auch viele Troff-Escape-Sequenzen verwenden (diese Sequenzen beginnen mit \). Wenn Sie den umgekehrten Schrägstrich (Backslash) als normalen Text benötigen, verwenden Sie \e. Sie können auch die folgenden Sequenzen, in denen x oder xx für einen beliebigen Buchstaben und N für eine beliebige Ziffer stehen, verwenden: \', \`, \-, \., \", \%, \*x, \*(xx, \(xx, \$N, \nx, \n(xx, \fx und \f(xx. Vermeiden Sie es, mit Escape-Sequenzen Grafiken zu zeichnen.

Verwenden Sie nicht den optionalen Parameter für bp (Seitenumbruch). Verwenden Sie nur positive Werte für sp (vertikaler Abstand). Definieren Sie kein Makro (de) mit dem gleichen Namen wie ein Makro in diesem oder dem mdoc-Makropaket mit einer anderen Bedeutung; wahrscheinlich werden solche Neudefinitionen ignoriert. Jeder positive Einzug (in) sollte mit einem passenden negativen Einzug gekoppelt werden (obwohl Sie stattdessen die Makros RS und RE verwenden sollten). Beim Prüfen von Bedingungen (if,ie) sollten Sie sich auf 't' oder 'n' beschränken. Nur Übersetzungen (tr), die ignoriert werden können, sollten verwendet werden. Änderungen der Schriftart (ft und die Escape-Sequenz \f Escape-Sequenz) sollten nur die Werte 1, 2, 3, 4, R, I, B, P oder CW annehmen. (Der ft-Befehl darf auch keine Parameter haben).

Wenn Sie Fähigkeiten nutzen, die über das Erwähnte herausgehen, überprüfen Sie die Ergebnisse sorgfältig mit mehreren Programmen. Sobald Sie bestätigt haben, dass die zusätzliche Fähigkeit sicher ist, teilen Sie dem Betreuer dieses Dokuments den sicheren Befehl oder die Sequenz mit, damit sie zu dieser Liste hinzugefügt werden kann.