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

       By all means include full URLs (or URIs) in  the  text  itself;  some  tools  such  as  man2html(1)   can
       automatically  turn  them  into  hypertext links. You can also use the new URL macro to identify links to
       related information. If you include URLs, use the full URL (e.g., http://www.kernelnotes.org)  to  ensure
       that tools can automatically find the URLs.

       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

       This page is part of release 3.54 of the Linux man-pages project.  A  description  of  the  project,  and
       information about reporting bugs, can be found at 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)