groff - Front-End für das GNU roff-Dokumentformatierungssystem
Synopsis
groff [-abcCeEgGijklNpRsStUVXzZ] [-d ctext] [-d string=text] [-D fallback-encoding] [-f fontfamily] [-F font-directory] [-I inclusion-directory] [-K input-encoding] [-L spoolerargument] [-m macro-package] [-M macro-directory] [-n page-number] [-o page-list]
[-P postprocessor-argument] [-r cnumeric-expression] [-r register=numeric-expression]
[-T output-device] [-w warning-category] [-W warning-category] [file ...]
groff -h
groff --help
groff -v [option ...] [file ...]
groff --version [option ...] [file ...]
Beschreibung
groff ist das primäre Front-End für das GNU roff-Dokumentformatierungssystem. GNU roff ist ein Typografie-System, das einfache Textdateien liest, die Formatierungsbefehle enthalten, um Ausgaben in PostScript, PDF, HTML, DVI oder anderen Formaten oder zur Anzeige auf einem Terminal zu erzeugen. Formatierungsbefehle können Low-Level-Typografie-Primitive, Makros aus einem bereitgestellten Paket oder benutzerdefinierte Makros sein. Alle drei Ansätze können kombiniert werden. Wenn keine Dateiopferanden angegeben werden oder die Datei "-" ist, liest groff den Standardeingabestrom.
Groff ist eine Neuimplementierung und Erweiterung des Typsetzers von AT&T Unix und ist auf den meisten POSIX-Systemen vorhanden, was auf seine lange Verbindung mit Unix-Handbüchern (einschließlich Manpages) zurückzuführen ist. Es und sein Vorgänger sind bekannt für die Erstellung von mehreren Bestseller-Texten zum Thema Software-Engineering. Groff ist in der Lage, typografisch anspruchsvolle Dokumente zu erstellen und gleichzeitig minimale Systemressourcen zu verbrauchen.
Der Befehl groff steuert die Ausführung von Vorprozessoren, die Transformation von Eingabedokumenten in eine geräteunabhängige Seitenbeschreibungssprache und die Erzeugung von Ausgaben aus dieser Sprache.
Optionen
-h und --help zeigen eine Hilfemeldung an und beenden das Programm.
Da groff dazu gedacht ist, die meisten direkten Aufrufe des troff(1)-Formatierers durch Benutzer zu ersetzen, teilen sich die beiden Programme eine Reihe von Optionen. Groff hat jedoch einige Optionen, die troff nicht hat, und andere, die groff anders interpretiert. Nicht alle gültigen troff-Optionen können gleichzeitig an groff übergeben werden.
Groff-spezifische Optionen
Die folgenden Optionen existieren entweder nicht in GNU troff oder werden von groff anders interpretiert.
-D enc Legt die Fallback-Eingabe-Kodierung fest, die von preconv(1) verwendet wird; impliziert -k.
-e Führt den eqn(1)-Vorprozessor aus.
-g Führt den grn(1)-Vorprozessor aus.
-G Führt den grap(1)-Vorprozessor aus; impliziert -p.
-I dir Funktioniert wie die Option von troff (siehe unten), impliziert aber auch -g und -s. Sie wird an soelim(1) und das Ausgabetreiberprogramm übergeben, und grn erhält eine Option -M mit dir als Argument.
-j Führt den chem(1)-Präprozessor aus; impliziert -p.
-k Führt den preconv(1)-Präprozessor aus. Siehe die Manpage für sein Verhalten, wenn weder die Option -K noch -D von groff angegeben ist.
-K enc Setzt die Eingabekodierung, die von preconv(1) verwendet wird, auf enc; impliziert -k.
-l Sendet die Ausgabe an ein Spooler-Programm zum Drucken. Die „print“-Direktive in der Gerätebeschreibungsdatei gibt den Standardbefehl an, der verwendet werden soll; siehe groff_font(5). Wenn keine solche Direktive für das Ausgabegerät vorhanden ist, wird die Ausgabe an lpr(1) weitergeleitet. Siehe die Optionen -L und -X.
-L arg Übergibt arg an das Druck-Spooler-Programm. Wenn mehrere Argumente erforderlich sind, wird jedes mit einer separaten Option -L übergeben. groff fügt dem Argument vor der Übergabe an das Spooler-Programm keinen vorangestellten Bindestrich hinzu.
-M Wirkt wie die Option von troff (siehe unten), wird aber auch an eqn(1), grap(1) und grn(1) übergeben.
-N Verhindert Zeilenumbrüche zwischen Eqn-Begrenzern: übergibt -N an eqn(1).
-p Führt den pic(1)-Präprozessor aus.
-P arg Übergibt arg an den Postprozessor. Wenn mehrere Argumente erforderlich sind, wird jedes mit einer separaten Option -P übergeben. groff fügt dem Argument vor der Übergabe an den Postprozessor keinen vorangestellten Bindestrich hinzu.
-R Führt den refer(1)-Präprozessor aus. Es gibt keinen Mechanismus, um Argumente an refer zu übergeben, da die meisten refer-Optionen äquivalente Sprachkonstrukte haben, die innerhalb des Dokuments angegeben werden können.
-s Führt den soelim(1)-Präprozessor aus.
-S Betreibt in einem „sichereren“ Modus; siehe -U unten für das Gegenteil. Aus Sicherheitsgründen ist der sichere Modus standardmäßig aktiviert.
-t Führt den tbl(1)-Präprozessor aus.
-T dev Weist troff an, die Eingabe für das Ausgabegerät dev zu formatieren. groff ruft dann einen Ausgabetreiber auf, um die Ausgabe von troff in ein für dev geeignetes Format zu konvertieren; siehe den Abschnitt „Ausgabegeräte“ unten.
-U Betreibt in einem unsicheren Modus: übergibt die Option -U an pic und troff.
-v
--version
Schreibt Versionsinformationen für groff und alle von ihm ausgeführten Programme auf den Standardausgabestream; d. h. die angegebene Befehlszeile wird auf die übliche Weise verarbeitet, wobei -v an den Formatter und alle aufgerufenen Prä- oder Postprozessoren übergeben wird.
-V Gibt die Pipeline aus, die groff auf dem Standardausgabestream ausführen würde, führt sie aber nicht aus. Wenn dies mehr als einmal angegeben wird, schreibt groff die Pipeline sowohl aus als auch führt sie aus.
-X Verwendet gxditview(1) anstelle des üblichen Postprozessors, um ein Dokument auf einem X11-Display (vor)anzusehen. Die Kombination dieser Option mit -Tps verwendet die Fontmetriken des PostScript-Geräts, während die Optionen -TX75 und -TX100 die Metriken der X11-Fonts verwenden.
-Z Deaktiviert die Nachbearbeitung. Die Ausgabe von troff wird auf den Standardausgabestream ausgegeben (es sei denn, sie wird mit -z unterdrückt); siehe groff_out(5) für eine Beschreibung dieses Formats.
Transparente Optionen
Die folgenden Optionen werden unverändert an das Formatterprogramm troff(1) übergeben und werden detaillierter in dessen Manpage beschrieben.
-a Generiere eine Textapproximation der formatierten Ausgabe.
-b Schreibe bei jedem Fehler oder jeder Warnung einen Backtrace in den Standardfehlerstrom.
-c Starte mit deaktivierter Farbausgabe.
-C Aktiviere den AT&T troff-Kompatibilitätsmodus; impliziert -c.
-d cs
-d name=string
Definiere String.
-E Unterdrücke troff-Fehlermeldungen; impliziert -Ww.
-f fam Lege die Standard-Schriftfamilie fest.
-F dir Suche im Verzeichnis dir nach den Verzeichnisdateien für Geräte und Schriftarten des ausgewählten Ausgabegeräts.
-i Verarbeite die Standardeingabe nach den angegebenen Eingabedateien.
-I dir Suche im Verzeichnis dir nach Eingabedateien.
-m name
Verarbeite name.tmac vor den Eingabedateien.
-M dir Suche im Verzeichnis dir nach Makrodateien.
-n num Nummeriere die erste Seite mit num.
-o list Gib nur die Seiten in der Liste aus.
-r cnumeric-expression
-r register=numeric-expression
Definiere Register.
-w name
-W name
Aktiviere (-w) oder deaktiviere (-W) die Ausgabe von Warnungen in der Kategorie name.
-z Unterdrücke die formatierte, geräteunabhängige Ausgabe von troff.
Verwendung
Die Architektur des GNU roff-Systems folgt der anderer geräteunabhängiger roff-Implementierungen und umfasst Vorprozessoren, Makropakete, Ausgabetreiber (oder „Nachprozessoren“) und eine Reihe von Dienstprogrammen sowie das Kernstück, den Formatter troff. Siehe roff(7) für einen Überblick darüber, wie ein roff-System funktioniert.
Die Frontend-Programme, die im GNU roff-System verfügbar sind, machen die Verwendung einfacher als bei herkömmlichen roff-Systemen, die den Aufbau von Pipelines oder die Verwendung von temporären Dateien erforderten, um ein Quelldokument von einem bearbeitbaren Format in ein gerätebereites Format zu übertragen. Die folgende Beschreibung fasst die einzelnen Teile des GNU roff-Systems zusammen. Sie ergänzt roff(7) mit groff-spezifischen Informationen.
Erste Schritte
Wer lieber durch Experimentieren lernt oder ein schnelles Feedback vom System wünscht, kann mit einem „Hallo, Welt!“-Dokument beginnen.
$ echo "Hallo, Welt!" | groff -Tascii | sed '/^$/d'
Hallo, Welt!
Wir haben einen sed-Befehl verwendet, um nur die 66 Leerzeilen zu entfernen, die sonst den Terminalbildschirm fluten würden. (roff-Systeme wurden in den Zeiten von papierbasierten Terminals mit 66 Zeilen pro Seite entwickelt.)
Heutige Benutzer bevorzugen möglicherweise eine Ausgabe in einem UTF-8-fähigen Terminal.
$ echo "Hallo, Welt!" | groff -Tutf8 | sed '/^$/d'
Das Erstellen von PDF, HTML oder TeX's DVI ist ebenfalls unkompliziert. Das Schwierige ist möglicherweise die Auswahl eines Viewer-Programms für die Ausgabe.
$ echo "Hallo, Welt!" | groff -Tpdf > hallo.pdf
$ evince hallo.pdf
$ echo "Hallo, Welt!" | groff -Thtml > hallo.html
$ firefox hallo.html
$ echo "Hallo, Welt!" | groff -Tdvi > hallo.dvi
$ xdvi hallo.html
Verwendung von groff als REPL
Wer programmieraffin ist, wird sich freuen, dass er groff in einer Read-Evaluate-Print-Schleife (REPL) verwenden kann. Dies kann nützlich sein, um das Verständnis des Formatters und seiner Syntax zu überprüfen. Das Aktivieren aller Warnungen mit -ww kann dieses Ziel unterstützen.
$ groff -ww -Tutf8
# Dies ist ein Kommentar. Lassen Sie uns ein Register definieren.
.nr a 1
# Führen Sie eine ganzzahlige Arithmetik mit Operatoren aus, die von links nach rechts ausgewertet werden.
.nr b \n[a]+5/2
# Lassen Sie uns das Ergebnis in den Standardfehlerstrom ausgeben.
.tm \n[b]
3 # Jetzt definieren wir einen String.
.ds name Leslie" Dies ist eine weitere Form von Kommentar.
.nr b (\n[a] + (7/2))
# Zentriere die nächsten beiden Textzeilen.
.ce 2
Hallo, \n[name].
Deine Geheimzahl ist \n[b].
# Wir werden sehen, dass die Division auf Null gerundet wird.
Es ist
# Hier ist eine If-Else-Kontrollstruktur.
.ie (\n[b] % 2) odd.
.el even.
# Dieser Trick setzt die Seitenlänge auf die aktuelle vertikale Position, so dass keine Leerzeilen ausgegeben werden, wenn wir fertig sind.
.pl \n[nl]u
<Control-D>
Hallo, Leslie.
Deine Geheimzahl ist 4.
Es ist gerade.
Papierformat
In GNU roff werden die Seitengrößen für den Formatter troff und für Ausgabegeräte separat behandelt. Im Formatter werden Anfragen verwendet, um die Seitenlänge (.pl), den Seitenabstand (oder linke Rand, .po) und die Zeilenlänge (.ll) festzulegen. Der rechte Rand wird nicht explizit konfiguriert; die Kombination aus Seitenabstand und Zeilenlänge liefert die Informationen, die zur Berechnung benötigt werden. Das Makropaket papersize, das automatisch von troff geladen wird, bietet eine Schnittstelle zum Konfigurieren von Seitengrößen mithilfe von praktischen Namen wie „letter“ oder „A4“; siehe groff_tmac(5). Der Standardwert des Formatters in dieser Installation ist „A4“.
Es liegt an jedem Makropaket, die auf diese Weise konfigurierten Seitengrößen zu respektieren. Einige bieten alternative Mechanismen an.
Für jedes Ausgabegerät kann die Größe des Ausgabemediums in seiner DESC-Datei festgelegt werden. Die meisten Ausgabetreiber erkennen auch eine Befehlszeilenoption -p, um die Standardabmessungen zu überschreiben, und eine Option -l, um die Landschaftsorientierung zu verwenden. Siehe groff_font(5) für eine Beschreibung der Direktive papersize, die ein Argument im gleichen Format wie -p akzeptiert. Die Manpage des Ausgabetreiber, z. B. grops(1), kann ebenfalls hilfreich sein. groff verwendet die Befehlszeilenoption -P, um Optionen an Ausgabegeräte zu übergeben; verwenden Sie beispielsweise Folgendes für PostScript-Ausgabe auf A4-Papier im Landschaftsformat.
groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
Frontend
Das Programm groff ist ein Wrapper um das Programm troff(1). Es ermöglicht die Angabe von Präprozessoren über Befehlszeilenoptionen und führt automatisch den entsprechenden Nachprozessor für das ausgewählte Ausgabegerät aus. Auf diese Weise kann die manuelle Erstellung von Pipelines oder die Verwaltung von temporären Dateien, die von Benutzern traditioneller roff(7)-Systeme erforderlich sind, vermieden werden. Verwenden Sie das Programm grog(1), um eine geeignete groff-Befehlszeile zum Formatieren eines Dokuments zu ermitteln.
Sprache
Die Eingabe für ein roff-System ist reiner Text, der mit Steuerzeichen und Escape-Sequenzen vermischt ist. Die Kombination ergibt ein Dokument in einer der Sprachfamilien, die wir ebenfalls als roff bezeichnen; siehe roff(7) für Hintergrundinformationen. Eine Übersicht über die Syntax und die Funktionen der GNU-roff-Sprache, einschließlich Listen aller unterstützten Escape-Sequenzen, Anfragen und vordefinierten Register, finden Sie in groff(7). Die GNU-roff-Erweiterungen für die AT&T-troff-Sprache, eine übliche Teilmenge der heute vorhandenen roff-Dialekte, sind in groff_diff(7) detailliert beschrieben.
Vorprozessoren
Ein Vorprozessor interpretiert eine domänenspezifische Sprache, die roff-Sprachausgabe erzeugt. Häufig ist eine solche Eingabe auf Abschnitte oder Bereiche einer roff-Eingabedatei beschränkt (eingeschlossen in Makroaufrufe, die für jeden Vorprozessor spezifisch sind), welche der Vorprozessor ersetzt. Vorprozessoren interpretieren daher oft eine Teilmenge der roff-Syntax zusammen mit ihrer eigenen Sprache. GNU roff bietet Reimplementierungen der meisten Vorprozessoren, die Benutzern von AT&T troff bekannt sind; diese verfügen in der Regel über erweiterte Funktionen und/oder erfordern GNU troff, um ihre Ausgabe zu formatieren.
tbl formatiert Tabellen; eqn setzt mathematische Formeln; pic zeichnet Diagramme; refer verarbeitet bibliografische Referenzen; soelim verarbeitet „eingebundene“ Eingabedateien; grn rendert gremlin(1)-Diagramme; chem zeichnet chemische Strukturformeln mit pic; gperl füllt groff-Register und -Strings mit perl(1); glilypond bettet LilyPond-Noten ein; und gpinyin erleichtert die Eingabe von Mandarin-Chinesisch mit Hanyu Pinyin.
Ein Vorprozessor, der exklusiv für GNU roff ist, ist preconv(1), der verschiedene Eingabe-Encodierungen in ein Format konvertiert, das GNU troff versteht. Wenn verwendet, wird er vor allen anderen Vorprozessoren ausgeführt.
Die meisten Vorprozessoren umschließen Inhalte zwischen einem Paar von charakteristischen Token. Ein solches Token muss am Anfang einer Eingabezeile stehen und das Punkt-Steuerzeichen verwenden. Leerzeichen und Tabulatoren dürfen nicht auf das Steuerzeichen folgen oder dem Ende der Eingabezeile vorausgehen. Das Abweichen von diesen Regeln verhindert, dass ein Token vom Vorprozessor erkannt wird. Token werden in der Regel in der Vorprozessorausgabe beibehalten und von troff als Makroaufrufe interpretiert. Der ideale Vorprozessor ist in groff noch nicht verfügbar.
┌──────────────┬─────────────────┬────────────────┐ │ Vorprozessor │ Start-Token │ End-Token │ ├──────────────┼─────────────────┼────────────────┤ │ chem │ .cstart │ .cend │ │ eqn │ .EQ │ .EN │ │ grap │ .G1 │ .G2 │ │ grn │ .GS │ .GE │ │ ideal │ .IS │ .IE │ │ │ │ .IF │ │ pic │ .PS │ .PE │ │ │ │ .PF │ │ │ │ .PY │ │ refer │ .R1 │ .R2 │ │ tbl │ .TS │ .TE │ ├──────────────┼─────────────────┼────────────────┤ │ glilypond │ .lilypond start │ .lilypond stop │ │ gperl │ .Perl start │ .Perl stop │ │ gpinyin │ .pinyin start │ .pinyin stop │ └──────────────┴─────────────────┴────────────────┘
Makropakete
Makrodateien sind roff-Eingabedateien, die dazu dienen, keine eigene Ausgabe zu erzeugen, sondern die Erstellung anderer roff-Dokumente zu erleichtern. Wenn eine Makrodatei an einem Standardort installiert ist und für die Verwendung durch ein breites Publikum geeignet ist, wird sie als Makropaket bezeichnet.
Makropakete können vor allen roff-Eingabedokumenten mit der Option -m geladen werden. Das GNU-roff- System implementiert die meisten bekannten Makropakete für AT&T troff auf kompatible Weise und erweitert diese. Diese haben ein- oder zweibuchstabige Namen, die aus intensiver Namensgebungspraxis in der frühen Unix-Kultur entstanden sind, einem lakonischen Ansatz, der dazu führte, dass viele der Pakete in der allgemeinen Verwendung mit dem nroff- und troff-Optionsbuchstaben, der zum Aufrufen verwendet wird, identifiziert wurden, manchmal mit einem Wortspiel, wie bei „man“ (kurz für „manual“) und sogar mit dem Options-Bindestrich, wie im Fall des Pakets „s“, das viel besser als „ms“ oder sogar „-ms“ bekannt ist.
Makropakete dienen einer Vielzahl von Zwecken. Einige sind „umfassende“ Pakete, die die Verantwortung für das Seitenlayout und andere grundlegende Aufgaben übernehmen und ihre eigene Sammlung von Makros für die Dokumenterstellung definieren; jedes dieser Pakete steht für sich, und ein bestimmtes Dokument kann höchstens eines verwenden.
an wird zum Erstellen von Manpages im Format verwendet, das in Version 7 Unix (1979) entstanden ist;
siehe groff_man(7). Es kann auf der Befehlszeile als -man angegeben werden.
doc wird zum Erstellen von Manpages im Format verwendet, das in 4.3BSD-Reno (1990) entstanden ist;
siehe groff_mdoc(7). Es kann auf der Befehlszeile als -mdoc angegeben werden.
e ist die Berkeley-basierte, universell einsetzbare Makrosammlung, die als Alternative zu AT&T's s
entwickelt wurde; siehe groff_me(7). Es kann auf der Befehlszeile als -me angegeben werden.
m implementiert das Format, das von der AT&T-Makrosammlung der zweiten Generation für allgemeine
Dokumente verwendet wird, einem Nachfolger von s; siehe groff_mm(7). Es kann auf der Befehlszeile als -mm angegeben werden.
om (immer als „mom“ bezeichnet) ist ein modernes Paket, das speziell für GNU roff von Peter Schaffter
geschrieben wurde. Konsultieren Sie das Mom-HTML-Handbuch für umfangreiche Dokumentation. Sie – denn Mom verwendet das weibliche Pronomen – kann auf der Befehlszeile als -mom angegeben werden.
s ist das ursprüngliche AT&T-Format für universell einsetzbare Dokumente; siehe groff_ms(7). Es kann
auf der Befehlszeile als -ms angegeben werden.
Andere sind ergänzend. Zum Beispiel ist andoc ein Wrapper-Paket, das spezifisch für GNU roff ist und erkennt, ob ein Dokument das Man- oder Mdoc-Format verwendet, und lädt das entsprechende Makropaket. Es kann auf der Befehlszeile als -mandoc angegeben werden. Ein man(1)-Bibliotheksprogramm kann diese Makrodatei verwenden, um das Laden des richtigen Makropakets zu delegieren; daher ist es nicht erforderlich, dass man selbst den Inhalt eines Dokuments scannt, um die Frage zu klären.
Viele Makrodateien erweitern die Funktionalität der Komplettpakete oder von roff-Dokumenten, die solche Pakete nicht verwenden – letztere werden manchmal als „roh“ bezeichnet. Diese Hilfspakete werden zusammen mit Details zur Benennung und Platzierung von Makrodateien in groff_tmac(5) beschrieben.
Formatierer
Der Formatierer, das Programm, das die roff-Spracheingabe interpretiert, ist troff(1). Er bietet die Funktionen der AT&T-Programme troff und nroff sowie viele Erweiterungen. Die Befehlszeilenoption -C schaltet troff in den Kompatibilitätsmodus, der versucht, AT&T troff so genau wie möglich zu emulieren, um das Formatieren von Dokumenten zu ermöglichen, die für das ältere System geschrieben wurden.
Ein Shell-Skript, nroff(1), emuliert das Verhalten von AT&T nroff. Es versucht, die Ausgabe basierend auf der Locale korrekt zu kodieren und befreit den Benutzer so von der Notwendigkeit, ein Ausgabegerät mit der Option -T anzugeben, und ist daher bequem für die Verwendung mit Terminalausgabegeräten, wie im nächsten Abschnitt beschrieben.
GNU troff generiert die Ausgabe in einer geräteunabhängigen, aber nicht geräteagnostischen, Seitendeskriptionssprache, die in groff_out(5) detailliert beschrieben ist.
Ausgabegeräte
Die troff-Ausgabe wird für ein bestimmtes Ausgabegerät formatiert, das typischerweise mit der Option -T an den Formatierer oder ein Front-End übergeben wird. Wenn weder diese Option noch die Umgebungsvariable GROFF_TYPESETTER verwendet wird, ist das Standardausgabegerät ps. Ein Ausgabegerät kann eines der folgenden sein:
ascii für Terminals, die den ISO 646 1991:IRV-Zeichensatz und die Kodierung verwenden, auch bekannt als USASCII.
cp1047 für Terminals, die den IBM-Codeseite-1047-Zeichensatz und die Kodierung verwenden.
dvi für TeX DVI-Format.
html
xhtml für HTML- bzw. XHTML-Ausgabe.
latin1 für Terminals, die den ISO Latin-1 (ISO 8859-1)-Zeichensatz und die Kodierung verwenden.
lbp für Canon CaPSL-Drucker (LBP-4- und LBP-8-Serie-Laserdrucker).
lj4 für HP LaserJet4-kompatible (oder andere PCL5-kompatible) Drucker.
pdf für PDF-Ausgabe.
ps für PostScript-Ausgabe.
utf8 für Terminals, die den ISO 10646 („Unicode“)-Zeichensatz in UTF-8-Kodierung verwenden.
X75 für die Vorschau mit gxditview mit einer Auflösung von 75 dpi und einer Schriftgröße von 10 Punkt.
X75-12 für die Vorschau mit gxditview mit einer Auflösung von 75 dpi und einer Schriftgröße von 12 Punkt.
X100 für die Vorschau mit gxditview mit einer Auflösung von 100 dpi und einer Schriftgröße von 10 Punkt.
X100-12 für die Vorschau mit gxditview mit einer Auflösung von 100 dpi und einer Schriftgröße von 12 Punkt.
Nachverarbeitungsprogramme
Jedes Programm, das die Ausgabe von GNU troff interpretiert, ist ein Nachverarbeitungsprogramm. Die von GNU roff bereitgestellten Nachverarbeitungsprogramme sind Ausgabetreiber, die ein Dokument für die Anzeige oder den Druck vorbereiten. Nachverarbeitungsprogramme für andere Zwecke, wie z. B. das Neuanordnen von Seiten oder die statistische Messung eines Dokuments, sind denkbar.
Ein Ausgabetreiber unterstützt ein oder mehrere Ausgabegeräte, von denen jedes seine eigene Gerätebeschreibungsdatei hat. Ein Gerät bestimmt sein Postprozessor-Programm mit der Postpro-Direktive in seiner Gerätebeschreibungsdatei; siehe groff_font(5). Die Option -X überschreibt diese Auswahl und bewirkt, dass gxditview als Ausgabetreiber dient.
grodvi(1)
erstellt DVI-Dateien.
grohtml(1)
erstellt HTML- und XHTML-Dateien.
grolbp(1)
erstellt LBP-Dateien.
grolj4(1)
erstellt LJ4-Dateien.
gropdf(1)
erstellt PDF-Dateien.
grops(1)
erstellt PS-Dateien.
grotty(1)
erstellt ASCII-, CP1047-, LATIN1- und UTF8-Dateien.
gxditview(1)
erstellt X75-, X75-12-, X100- und X100-12-Dateien und kann zusätzlich PS-Dateien in der Vorschau anzeigen.
Werkzeuge
GNU roff enthält eine Reihe von Werkzeugen.
gdiffmk(1)
markiert Unterschiede zwischen einem Paar von roff-Eingabedateien.
grog(1)
ermittelt den groff-Befehl, den ein Dokument benötigt.
Mehrere Werkzeuge erstellen Beschreibungen von Schriftarten, sodass der Formatter diese verwenden kann, wenn er Ausgaben für ein bestimmtes Gerät erstellt.
addftinfo(1)
fügt Informationen zu AT&T troff-Schriftartbeschreibungsdateien hinzu, um deren Verwendung mit GNU troff zu ermöglichen.
afmtodit(1)
erstellt Schriftartbeschreibungsdateien für PostScript Type 1-Schriftarten.
pfbtops(1)
konvertiert eine PostScript Type 1-Schriftart im PFB-Format (Printer Font Binary) in PFA-Format (Printer
Font ASCII), das dann von afmtodit interpretiert werden kann.
hpftodit(1)
erstellt Schriftartbeschreibungsdateien für die HP LaserJet 4-Familie von Druckern.
tfmtodit(1)
erstellt Schriftartbeschreibungsdateien für das TeX DVI-Gerät.
xtotroff(1)
erstellt Schriftartbeschreibungsdateien für X Window System-Standardschriftarten.
Ein Trio von Werkzeugen transformiert Material, das mit roff-Präprozessorsprachen erstellt wurde, in grafische Bilddateien.
eqn2graph(1)
konvertiert eine eqn-Gleichung in ein zugeschnittenes Bild.
grap2graph(1)
konvertiert ein grap-Diagramm in ein zugeschnittenes Bild.
pic2graph(1)
konvertiert ein pic-Diagramm in ein zugeschnittenes Bild.
Eine weitere Gruppe von Programmen arbeitet mit den bibliografischen Datendateien, die vom refer(1)-Präprozessor verwendet werden.
indxbib(1)
erstellt invertierte Indizes für bibliografische Datenbanken, um die Suchvorgänge in diesen zu beschleunigen.
lkbib(1)
durchsucht die Datenbanken.
lookbib(1)
durchsucht die Datenbanken interaktiv.
Exit-Status
groff beendet die Ausführung mit einem Fehlerstatus, wenn beim Parsen der Argumente ein Problem aufgetreten ist, und mit einem erfolgreichen Status, wenn entweder der Parameter -h oder --help angegeben wurde. Andernfalls führt groff eine Pipeline aus, um seine Eingabe zu verarbeiten; wenn alle Befehle innerhalb der Pipeline erfolgreich ausgeführt werden, tut groff dasselbe. Wenn nicht, kodiert der Exit-Status von groff eine Zusammenfassung der aufgetretenen Probleme, wobei Bit 0 gesetzt wird, wenn ein Befehl mit einem Fehlerstatus beendet wurde, Bit 1, wenn ein Befehl durch ein Signal beendet wurde, und Bit 2, wenn ein Befehl nicht ausgeführt werden konnte. (Wenn also alle drei Missgeschicke in einer Pipeline aufgetreten sind, würde groff mit dem Status 2^0 + 2^1 + 2^2 = 1+2+4 = 7 beendet). Um Probleme in einer Pipeline zu beheben, können Sie den groff-Befehl mit der Option -V erneut ausführen und die gemeldete Pipeline in separate Phasen aufteilen, wobei Sie den Exit-Status und die von jedem Befehl ausgegebenen Diagnosemeldungen überprüfen.
Umgebung
Normalerweise ist das Pfngtrennzeichen in Umgebungsvariablen, die mit PATH enden, ein Doppelpunkt; dies kann je nach Betriebssystem variieren. Beispielsweise verwendet Windows ein Semikolon.
GROFF_BIN_PATH
Dieser Suchpfad wird zusammen mit PATH verwendet, um die durch groff auszuführenden Befehle zu finden. Wenn er nicht gesetzt ist, wird das Installationsverzeichnis der GNU roff-Ausführdateien, /usr/bin, vor PATH durchsucht.
GROFF_COMMAND_PREFIX
GNU roff kann zur Kompilierzeit so konfiguriert werden, dass ein Präfix an die Namen der von ihm bereitgestellten Programme angehängt wird, die ein Gegenstück in AT&T troff hatten, um Namenskonflikte zur Laufzeit zu vermeiden. Das Standardpräfix ist leer.
Wenn verwendet, ist dieses Präfix konventionell der Buchstabe „g“. Beispielsweise würde GNU troff als gtroff installiert. Neben troff gilt das Präfix auch für den Formatter nroff, die Präprozessoren eqn, grn, pic, refer, tbl und soelim sowie die Hilfsprogramme indxbib und lookbib.
GROFF_ENCODING
Der Wert dieser Variablen wird an die Option -e des Preprozessors preconv(1) übergeben, um die Zeichenkodierung der Eingabedateien auszuwählen. Das Vorhandensein dieser Variablen impliziert die groff-Option -k. Wenn sie gesetzt ist, aber leer, ruft groff preconv ohne eine -e-Option auf. Die Option -K von groff überschreibt GROFF_ENCODING.
GROFF_FONT_PATH
Suchen Sie in dieser Liste von Verzeichnissen nach dem Verzeichnis der Geräte- und Schriftbeschreibungsdateien des ausgewählten Ausgabegeräts. Siehe troff(1) und groff_font(5).
GROFF_TMAC_PATH
Suchen Sie in dieser Liste von Verzeichnissen nach Makrodateien. Siehe troff(1) und groff_tmac(5).
GROFF_TMPDIR
Erstellen Sie temporäre Dateien in diesem Verzeichnis. Wenn dies nicht gesetzt ist, aber die Umgebungsvariable TMPDIR gesetzt ist, werden temporäre Dateien stattdessen dort erstellt. Auf Windows-Systemen werden, wenn keines der beiden Vorangehenden gesetzt ist, auch die Umgebungsvariablen TMP und TEMP (in dieser Reihenfolge) überprüft. Andernfalls werden temporäre Dateien in /tmp erstellt. Die Befehle refer(1), grohtml(1) und gropens(1) verwenden temporäre Dateien.
GROFF_TYPESETTER
Setzen Sie das Standardausgabegerät. Wenn leer oder nicht gesetzt, wird ps verwendet. Die Option -T überschreibt GROFF_TYPESETTER.
SOURCE_DATE_EPOCH
Ein Zeitstempel (ausgedrückt in Sekunden seit der Unix-Epoche), der anstelle der aktuellen Zeit als Ausgabeerstellungszeitstempel verwendet werden soll. Die Zeit wird mit gmtime(3) und asctime(3) in ein für Menschen lesbares Format konvertiert, wenn der Formatter startet, und in Registern gespeichert, auf die von Dokumenten und Makropaketen zugegriffen werden kann.
TZ Die Zeitzone, die bei der Konvertierung der aktuellen Zeit in ein für Menschen lesbares Format verwendet werden soll; siehe tzset(3). Wenn SOURCE_DATE_EPOCH verwendet wird, wird sie immer in ein für Menschen lesbares Format unter Verwendung von UTC konvertiert.
Beispiele
roff-Systeme sind vor allem für die Formatierung von Manpages bekannt. Sobald ein [man]-Bibliotheksprogramm (1) eine Manpage gefunden hat, kann es einen groff-Befehl ähnlich dem folgenden ausführen. groff -t -man -Tutf8 /usr/share/man/man1/groff.1 Die Bibliotheksprogramm wird die Ausgabe auch durch einen Pager leiten, der möglicherweise die SGR-Terminal-Escape-Sequenzen, die groff für Fettdruck, Unterstreichung oder Kursivschrift ausgibt, nicht interpretiert; siehe Abschnitt „Einschränkungen“ unten.
Um eine roff-Eingabedatei mithilfe der Präprozessoren tbl und pic sowie des Makropakets me so zu verarbeiten, wie es AT&T-troff-Benutzer gewohnt waren, würde man eine Pipeline eingeben (oder ein Skript erstellen).
pic foo.me | tbl | troff -me -Tutf8 | grotty
Mit groff kann diese Pipeline zu einem äquivalenten Befehl verkürzt werden.
groff -p -t -me -T utf8 foo.me
Noch einfacher geht es, wenn man grog(1) verwendet, um die Präprozessor- und Makrooptionen zu erraten und das Ergebnis mithilfe der Befehlssubstitution der Shell auszuführen.
$(grog -Tutf8 foo.me)
Jede Befehlszeilenoption für einen Postprozessor muss mit allen erforderlichen vorangestellten Bindestrichen „-“ angegeben werden, da groff die Argumente unverändert an den Postprozessor übergibt; dies ermöglicht die Übertragung beliebiger Argumente. Um beispielsweise einen Titel an den Postprozessor gxditview zu übergeben, sind die Shell-Befehle groff -X -P -title -P 'trial run' mydoc.t und groff -X -Z mydoc.t | gxditview -title 'trial run' äquivalent.
Einschränkungen
Beim Paging der Ausgabe für die Geräte ascii, cp1047, latin1 und utf8 benötigen Programme wie more(1) und less(1) möglicherweise Befehlszeilenoptionen, um einige Terminal-Escape-Sequenzen korrekt zu verarbeiten; siehe grotty(1).
Auf EBCDIC-Hosts wie OS/390 Unix sind die Ausgabegeräte ascii und latin1 nicht verfügbar. Umgekehrt ist das Ausgabegerät cp1047 auf Systemen, die auf den Zeichenkodierungsstandards ISO 646 oder ISO 8859 basieren, nicht verfügbar.
Installationsverzeichnisse
GNU roff installiert Dateien an verschiedenen Orten, je nach Konfiguration zur Kompilierzeit. Bei dieser Installation werden die folgenden Speicherorte verwendet.
/etc/X11/app-defaults
Anwendungsverzeichnis für gxditview(1).
/usr/bin
Verzeichnis, das die ausführbaren Befehle von groff enthält.
/usr/share/groff/1.23.0/eign
Liste der gebräuchlichen Wörter für indxbib(1).
/usr/share/groff/1.23.0
Verzeichnis für Datendateien.
/usr/dict/papers/Ind
Standardindex für lkbib(1) und refer(1).
/usr/share/doc/groff-base
Dokumentationsverzeichnis.
/usr/share/doc/groff-base/examples
Beispielverzeichnis.
/usr/share/groff/1.23.0/font
Schriftartenverzeichnis.
/usr/share/doc/groff-base/html
HTML-Dokumentationsverzeichnis.
/usr/lib/font
Legacy-Schriftartenverzeichnis.
/usr/share/groff/site-font
Lokales Schriftartenverzeichnis.
/usr/share/groff/site-tmac
Lokales Makropaket (tmac-Datei)-Verzeichnis.
/usr/share/groff/1.23.0/tmac
Makropaket (tmac-Datei)-Verzeichnis.
/usr/share/groff/1.23.0/oldfont
Schriftartenverzeichnis für die Kompatibilität mit älteren Versionen von groff; siehe grops(1).
/usr/share/doc/groff-base/pdf
PDF-Dokumentationsverzeichnis.
groff-Makro-Verzeichnis
Die meisten mit GNU roff gelieferten Makrodateien werden im Verzeichnis /usr/share/groff/1.23.0/tmac für die Installation gespeichert, die dieser Dokumentation entspricht. In der Regel werden mehrere Verzeichnisse nach Makrodateien durchsucht; siehe troff(1). Eine Liste der von GNU roff bereitgestellten Makrodateien finden Sie unter groff_tmac(5).
Verzeichnis mit Geräte- und Schriftbeschreibungsdateien für groff. Geräte- und Schriftbeschreibungsdateien, die mit GNU roff geliefert werden, sind in /usr/share/groff/1.23.0/ gespeichert.
Schriftart für die Installation, die dieser Dokumentation entspricht. In der Regel werden mehrere Verzeichnisse nach Geräte- und Schriftbeschreibungsdateien durchsucht; siehe troff(1). Für die Formate dieser Dateien siehe groff_font(5).
Verfügbarkeit
Erhalten Sie Links zu groff-Releases zum Herunterladen, seinem Quellcode-Repository, Diskussions-Mailinglisten, einem Support-Ticket-Tracker und weitere Informationen von der groff-Seite der GNU-Website.
Eine kostenlose Implementierung des grap-Präprozessors, geschrieben von Ted Faber, finden Sie auf der grap-Website. groff unterstützt nur dieses grap.
Autoren
groff (sowohl das Frontend-Kommando als auch das gesamte System) wurde hauptsächlich von James Clark geschrieben. Zu den Mitwirkenden an diesem Dokument gehören Clark, Trent A. Fisher, Werner Lemberg, Bernd Warken und G. Branden Robinson.
Siehe auch
Groff: Die GNU-Implementierung von troff, von Trent A. Fisher und Werner Lemberg, ist das Haupt-groff-Handbuch. Sie können es interaktiv mit „info groff“ durchsuchen.
Einführung, Geschichte und weiterführende Lektüre: roff(7)
Betrachtungsprogramm für groff- (und AT&T-geräteunabhängige troff-) Dokumente: gxditview(1)
Präprozessoren:
chem(1), eqn(1), neqn(1), glilypond(1), grn(1), preconv(1), gperl(1), pic(1), gpinyin(1), refer(1), soelim(1), tbl(1)
Makro-Pakete und paketspezifische Dienstprogramme: groff_hdtbl(7), groff_man(7), groff_man_style(7), groff_mdoc(7), groff_me(7), groff_mm(7), groff_mmse(7) (nur in schwedischen Sprachpaketen), mmroff(1), groff_mom(7), pdfmom(1), groff_ms(7), groff_rfc1345(7), groff_trace(7), groff_www(7)
Bibliografische Datenbankverwaltungstools: indxbib(1), lkbib(1), lookbib(1)
Sprache, Konventionen und GNU-Erweiterungen: groff(7), groff_char(7), groff_diff(7), groff_font(5), groff_tmac(5)
Zwischenausgabe-Sprache: groff_out(5)
Formatierungsprogramm: troff(1)
Formatierungs-Wrapper: nroff(1), pdfroff(1)
Nachbearbeitungsprogramme für Ausgabegeräte: grodvi(1), grohtml(1), grolbp(1), grolj4(1), gropdf(1), grops(1), grotty(1)
Schriftart-Unterstützungsdienstprogramme: addftinfo(1), afmtodit(1), hpftodit(1), pfbtops(1), tfmtodit(1), xtotroff(1)
Grafikkonvertierungsdienstprogramme: eqn2graph(1), grap2graph(1), pic2graph(1)
Dienstprogramm zum Markieren von Unterschieden: gdiffmk(1)
„groff guess“-Dienstprogramm:
grog(1)