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>.

Linux                                            5. August 2012                                           MAN(7)