Ubuntu Manpage: man - Makros für das Formatieren von Handbuchseiten

BEZEICHNUNG

       man - Makros für das Formatieren von Handbuchseiten

ÜBERSICHT

       groff -Tascii -man Datei ...

       groff -Tps -man Datei ...

       man [Abschnitt] Titel

BESCHREIBUNG

Diese Handbuchseite beschreibt das Groff-Makropaket tmac.an, das oft als das man-Paket
bezeichnet wird. Es sollte von Entwicklern benutzt werden, die Handbuchseiten für Linux
schreiben oder portieren. Es ist nahezu vollständig kompatibel zu älteren Versionen dieses
Paketes. Daher sollte es relativ problemlos möglich sein, andere Handbuchseiten zu
konvertieren. (Zu den Ausnahmen gehört die NET-2 BSD-Veröffentlichung, die das völlig
andere Makropaket mdoc(7) benutzt.)

Beachten Sie, dass Handbuchseiten von NET-2 BSD mit Groff durch die Nutzung der Option
-mdoc anstelle der Option -man benutzt werden können. Es wird die Wahl der Option -mandoc
empfohlen, da diese automatisch das benutzte Makropaket erkennt.

Wenn Sie Handbuchseiten für das Linux-Paket »man-pages« schreiben, lesen Sie bitte
man-pages(7). Dort finden Sie die Konventionen, an die Sie sich halten sollten.

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

.TH Titel Abschnitt Datum Quelle Handbuch

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:

.SH BEZEICHNUNG
Element \- Beschreibung

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 Schrifttyp Roman (besonders praktisch für den Verweis auf andere
Handbuchseiten)

.I Kursiv

.IB Kursiv, abwechselnd mit fett

.IR Kursiv, abwechselnd mit der Schrift Roman

.RB Roman, abwechselnd mit fett

.RI Roman, 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. Alle Argumente werden hintereinander
ohne die dazwischenliegenden Leerzeichen ausgegeben, sodass beispielsweise mit dem
Kommando .BR ein Wort im Fettdruck, gefolgt von einem Wort in der Schrift Roman
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
Diese Möglichkeit bietet nur Groff. Um die Makros für Hypertext-Links zu benutzen, müssen
Sie das Makropaket www.tmac laden. Verwenden Sie dafür die Anweisung .mso www.tmac.

.URL URL Link Nachsatz
Fügt einen Hypertext-Link zu dem URI (URL) url mit link als Verweistext ein. Der
Nachsatz wird unmittelbar danach ausgegeben. Beim Erzeugen von HTML sollte dies
in den HTML-Befehl <A HREF="url">link</A>Nachsatz übersetzt werden.

Diese und andere verwandte Makros sind neu. Viele Werkzeuge werden sie nicht
bearbeiten. Da aber viele Werkzeuge (einschließlich Troff) nicht definierte
Makros einfach ignorieren (oder im schlimmsten Fall ihren Text einfügen), können
Sie diese Makros ohne Bedenken einfügen.

Es kann nützlich sein, für andere Roff-Betrachter als Groff Ihr eigenes URL-Makro
zu definieren. Auf diese Weise bleiben die URL, Verweistext und Nachsatz (falls
vorhanden) noch sichtbar.

Ein Beispiel:
.de URL
\\$2 \(laURL: \\$1 \(ra\\$3
..
.if \n[.g] .mso www.tmac
.TH ...
(weiter unten auf der Seite)
Diese Software stammt vom
.URL "http://www.gnu.org/" "GNU-Projekt" " der"
.URL "http://www.fsf.org/" "Free Software Foundation" .

Im oben stehenden Text wird bei Verwendung von Groff die Definition aus dem
Makropaket www.tmac die lokale Definition ersetzen.

Es gibt eine Reihe weiterer Link-Makros. Weitere Details finden Sie in groff_www(7).

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: ™

\*(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.

DATEIEN

       /usr/share/groff/[*/]tmac/an.tmac
       /usr/man/whatis

ANMERKUNGEN

       Geben Sie auf alle Fälle im Text vollständige URLs (oder URIs) an.  Einige  Werkzeuge  wie
       man2html(1)  können sie automatisch in Hypertext-Links umwandeln. Sie können auch das neue
       Makro URL verwenden, um Verweise zu verwandten Informationen  zu  kennzeichnen.  Wenn  Sie
       URLs     einschließen,     verwenden     Sie     die     vollständige    URLs    (z.    B.
       ⟨http://www.kernelnotes.org⟩)  ),  um  sicherzustellen,  dass  die  Werkzeuge   die   URLs
       automatisch finden können.

       Werkzeuge,  die solche Dateien verarbeiten, sollten die Datei öffnen und das erste Zeichen
       prüfen, das kein Whitespace ist. Ein Punkt (.) oder  einfaches  Anführungszeichen  (')  am
       Anfang  einer  Zeile  kennzeichnet eine Troff-Datei (wie man oder mdoc). Eine linke spitze
       Klammer (<) zeigt eine SGML/XML-basierte Datei an (z. B. HTML oder DocBook). Alles  Andere
       lässt einfachen ASCII-Text vermuten (z. B. ein Ergebnis von »catman«).

       Viele  Handbuchseiten  beginnen mit ´\", gefolgt von einem Leerzeichen und einer Liste von
       Zeichen, welche die Vorverarbeitung der Seite festlegt. Um  der  Portabilität  zu  anderen
       Programmen  als  Troff  willen wird empfohlen, alles andere als tbl(1) zu vermeiden, damit
       Linux das automatisch erkennt. Allerdings möchten Sie vielleicht  diese  Informationen  in
       Ihre  Handbuchseite aufnehmen, damit diese von anderen (weniger leistungsfähigen) Systemen
       verarbeitet werden kann. Mit diesen Zeichen rufen Sie die folgenden Präprozessoren auf:

       e  eqn(1)

       g  grap(1)

       p  pic(1)

       r  refer(1)

       t  tbl(1)

       v  vgrind(1)

FEHLER

       Im Vergleich zu  Formaten  wie  mdoc  und  DocBook  beschreibt  die  Mehrzahl  der  Makros
       Formatierungen   (z.  B.  Schriftart  und  Zeilenabstand)  statt  semantische  Inhalte  zu
       kennzeichnen (z. B.: Dieser Text verweist auf eine andere Seite). Sogar HTML verfügt  über
       mehr  semantische  Markierungen.  Diese Situation macht es schwieriger, das man-Format für
       verschiedene Medien zu variieren, die Formatierung für ein bestimmtes Medium konsistent zu
       machen  und  automatisch  Querverweise  einzufügen.  Mit  der  Beschränkung  auf  die oben
       beschriebene sichere Teilmenge sollte es einfacher sein, den zukünftigen Übergang zu einem
       anderen Format für Referenzseiten (wie z. B. Manual Pages) zu automatisieren.

       Der Sun-Makro TX ist nicht implementiert.

SIEHE AUCH

       apropos(1),   groff(1),   lexgrog(1),   man(1),   man2html(1),  groff_mdoc(7),  whatis(1),
       groff_man(7), groff_www(7), man-pages(7), mdoc(7)

KOLOPHON

       Diese Seite  ist  Teil  der  Veröffentlichung  4.04  des  Projekts  Linux-man-pages.  Eine
       Beschreibung  des  Projekts,  Informationen,  wie  Fehler gemeldet werden können sowie die
       aktuelle Version dieser Seite finden sich unter http://www.kernel.org/doc/man-pages/.

ÜBERSETZUNG

       Die deutsche Übersetzung dieser Handbuchseite wurde  von  René  Tschirley  <gremlin@cs.tu-
       berlin.de> und Martin Eberhard Schauer <Martin.E.Schauer@gmx.de> erstellt.

       Diese  Übersetzung  ist  Freie  Dokumentation;  lesen  Sie  die GNU General Public License
       Version  3  oder  neuer  bezüglich  der  Copyright-Bedingungen.  Es  wird  KEINE   HAFTUNG
       übernommen.

       Wenn Sie Fehler in der Übersetzung dieser Handbuchseite finden, schicken Sie bitte eine E-
       Mail an <debian-l10n-german@lists.debian.org>.