Adventskalender 12. Dezember 2024 - nroff

[Meillo]

Hier kommt mein obligatorischer Beitrag zur Unix-Geschichte fuer diesen Adventskalender.

nroff ist ein Textformatierer, der -- falls ueberhaupt -- dann als Grundlage der Manpages bekannt ist. Wenn man als Entwickler heutzutage immer noch eine Manpage mit seinem Programm mitliefern will (was leider immer seltener wird), dann ist das zumeist der Zeitpunkt, an dem man zum ersten Mal nroff-Code sieht und erschrocken und unglaeubig lieber schnell das Weite suchen will. Lieber schaut man sich dann nach einem Programm um, das XML oder Markdown in Manpages uebersetzt, um sich bloss davor druecken zu koennen, dieses kryptische Durcheinander verstehen oder gar schreiben zu muessen.

Doch ohne nroff gaebe es Unix und damit GNU/Linux wohl nicht in der heutigen Form. Die historische Bedeutung dieses Programms ist gross ... und trotz des archaischen Stils besitzt es eine Schoenheit, die vor allem auf seiner Einfachheit bei gleichzeitiger Maechtigkeit basiert. Grund genug, einen Blick darauf zu werfen.


Historischer Hintergrund

Unix nahm seinen Anfang in Ueberlegungen Ken Thompsons zu einem neuen Dateisystem. Das MULTICS-Projekt scheiterte Mitte der 60er Jahre. Bell Labs zog sich daraus zurueck. Ken Thompson hatte daraufhin erstmal keine neue Aufgaben und liess seinen Dateisystemueberlegungen freien Lauf. Aus den Gespraechen und theoretischen Ueberlegungen wurde eine reale Umsetzung als fuer ihn, Dennis Ritchie und ein paar weitere Personen die Moeglichkeit bestand, eine nachts ungenutzte PDP-7 einer anderen Abteilung fuer ihre Experimente in Anspruch zu nehmen.

Das Projekt, das nun schon ein kleines Betriebssystem (in PDP-7-Assembler geschrieben) war, zeigte zunehmend sein Potenzial. Die nur in den Randzeiten nutzbare fremde PDP-7 wurde bald zur Beschraenkung. Ein eigener Computer musste her. Dieser konnte aber nur beschafft werden, wenn er einen Mehrwert fuer die Bell Labs schaffte -- und hier kommt nun nroff, bzw. sein Vorgaenger roff ins Spiel. Die Anschaffung der PDP-11 wurde naemlich dadurch durchgesetzt, dass man fuer die Patentabteilung eine Textverarbeitung zur Verfuegung stellte. Diese ist roff (spaeter nroff und troff), was sie damit zum ersten richtigen Anwenderprogramm von Unix macht.

Wenn die Mitarbeiter_innen (vor allem Sekreterinnen und Datentypistinnen) damals keine Probleme hatten, ihre Patentschriften mit ed fuer (n)roff zu schreiben, dann sollte uns erfahrenen Computernutzern von heute das sicherlich auch keine Probleme bereiten. Wir duerfen uns dafuer nur nicht selbst im Wege stehen, sondern muessen mit einem offenen Geist an die Sache gehen.


Technische Grundlagen

Nroff liest Eingabetext von Standard-In bzw. aus angegebenen Dateien, formatiert ihn um und gibt ihn wieder auf Standard-Out aus. Damit ist nroff zur Verwendung in Pipelines gedacht.

Nroff erzeugt reine Textausgaben, die im Terminal angezeigt werden koennen. Das Geschwisterprogramm troff erzeugt Ausgaben, die als PS oder PDF an grafischen Bildschrimen angezeigt oder auf Laserdruckern gedruckt werden koennen.

Die automatisch auf Debian installierte Implementierung von nroff aus dem groff Paket unterstuetzt leider kein UTF-8. Man muss daher die Eingangsdaten mit dem Programm `preconv' vorverarbeiten. (Aus diesem Grund verwende ich normalerweise die Implementierung der Heirloom Doctools, die besser fuer eine moderne Nutzung geeignet ist und UTF-8 voll unterstuetzt. Diese Implementierung kann aber nicht einfach als Debian-Paket installiert werden, daher sind alle Beispiele hier fuer die groff-Implementierung entworfen.)


Filling and Adjusting

Nroff hat einen einfachen Arbeitsmodus: Es liest Wort fuer Wort den Eingangstext ein und fuellt damit Zeile fuer Zeile (= Filling, also Auffuellen). Wenn eine Zeile so voll ist, dass das naechte Wort nicht mehr reinpasst, dann macht es einen Zeilenumbruch und erweitert die Wortzwischenraeume so lange bis die Zeile die gewuenschte Laenge erreicht hat (= Adjusting, also Ausrichten). So erzeugt nroff standardmaessig Blocksatz. Leerzeilen unterbrechen das Filling und beginnen einen neuen Absatz.

Beispiel:

Nehmen wir dieses Gedicht von Eichendorff als Ausgangstext:

Weihnachten.

Markt und Straßen stehn verlassen,
Still erleuchtet jedes Haus,
Sinnend geh’ ich durch die Gassen,
Alles sieht so festlich aus.

An den Fenstern haben Frauen
Buntes Spielzeug fromm geschmückt,
Tausend Kindlein stehn und schauen,
Sind so wunderstill beglückt.

Und ich wandre aus den Mauern
Bis hinaus in’s freie Feld,
Hehres Glänzen, heil’ges Schauern!
Wie so weit und still die Welt!

Sterne hoch die Kreise schlingen,
Aus des Schneees Einsamkeit
Steigt’s wie wunderbares Singen –
O du gnadenreiche Zeit!

Eine Blocksatzausgabe bekommen wir nun also mit:

Code: Alles auswählen

:-Q preconv weihnachten | nroff
Weihnachten.

Markt  und  Straßen stehn verlassen, Still erleuchtet jedes Haus,
Sinnend geh’ ich durch die Gassen, Alles sieht so festlich aus.

An den Fenstern haben Frauen Buntes Spielzeug  fromm  geschmückt,
Tausend Kindlein stehn und schauen, Sind so wunderstill beglückt.

Und  ich wandre aus den Mauern Bis hinaus in’s freie Feld, Hehres
Glänzen, heil’ges Schauern!  Wie so weit und still die Welt!

Sterne hoch die Kreise schlingen,  Aus  des  Schneees  Einsamkeit
Steigt’s wie wunderbares Singen – O du gnadenreiche Zeit!

(`:-Q' ist mein Prompt. Am Ende der Ausgabe stehen noch Leerzeilen, da nroff den Text fuer ganze Seiten formatiert. Als Seitenlaenge nimmt es 11 Zoll an. Die Zeilenlaenge entspricht 6,5 Zoll.)

Nroff hat jeden Absatz gefuellt und beidseitig zu einem geraden Rand ausgerichtet. Als Absatz versteht es jeweils die durch Leerzeilen getrennten hintereinanderfolgenden Textzeilen.

Indem wir alle Leerzeilen entfernen, wird ein einziger Absatz daraus:

Code: Alles auswählen

:-Q grep . weihnachten | preconv | nroff
Weihnachten.  Markt und Straßen stehn verlassen, Still erleuchtet
jedes Haus, Sinnend geh’ ich durch die  Gassen,  Alles  sieht  so
festlich  aus.   An  den  Fenstern  haben Frauen Buntes Spielzeug
fromm geschmückt, Tausend Kindlein stehn  und  schauen,  Sind  so
wunderstill  beglückt.   Und ich wandre aus den Mauern Bis hinaus
in’s freie Feld, Hehres Glänzen, heil’ges Schauern!  Wie so  weit
und  still  die  Welt!  Sterne hoch die Kreise schlingen, Aus des
Schneees Einsamkeit  Steigt’s  wie  wunderbares  Singen  –  O  du
gnadenreiche Zeit!

Man kann hier erkennen, dass das Adjusting, also das Auseinanderziehen der Zeilen durch Verbreitern der Leerraeume, abwechselnd von links und von rechts passiert. Zudem sieht man, dass nach Punkten zwei Leerzeichen stehen, die durch das Adjusting ggf. auch zu drei und mehr werden. Das ist dem (amerikanischen) Schreibmaschinenstil nachempfunden. Nroff sollte stets das nachbilden was man mit Schreibmaschinen damals auch gemacht haette.


Befehle

Zeilen, die mit einem Punkt (oder Singlequote) beginnen, sind Befehlszeilen. So eine Zeile wird als nroff-Befehl interpretiert und stellt keinen Eingabetext dar.

Wir koennen die Zeilenlaenge veraendern, indem wir folgenden Befehl an den Anfang der Datei schreiben:

Code: Alles auswählen

.ll 40

(`ll' steht fuer ``line length''.)

Das Ergebnis ist dann:

Code: Alles auswählen

:-Q preconv weihnachten2 | nroff      
Weihnachten.

Markt und Straßen stehn verlassen, Still
erleuchtet jedes Haus, Sinnend geh’  ich
durch  die  Gassen,  Alles sieht so fes‐
tlich aus.

An  den  Fenstern  haben  Frauen  Buntes
Spielzeug   fromm   geschmückt,  Tausend
Kindlein stehn und schauen, Sind so wun‐
derstill beglückt.

Und ich wandre aus den Mauern Bis hinaus
in’s   freie   Feld,   Hehres   Glänzen,
heil’ges  Schauern!   Wie  so  weit  und
still die Welt!

Sterne hoch die  Kreise  schlingen,  Aus
des  Schneees  Einsamkeit  Steigt’s  wie
wunderbares Singen – O  du  gnadenreiche
Zeit!

Mit

Code: Alles auswählen

.pl 1n

koennen wir nun auch die Seitenlaenge (``page length'') auf 1 Zeile reduzieren, was uns die Leerzeilen am Ende erspart. (Als Einheiten gibt es: `i' = Inch, `c' = Centimeter, `n' = Zeichen, und weitere.)

Ebenso koennen wir das Filling an- und abschalten:
- .fi = fill (default)
- .nf = no fill

Oder das Adjusting aendern:
- .na = no adjusting
- .ad l = linksbuendig
- .ad r = rechtsbuendig
- .ad c = zentriert
- .ad b = beidseitig, also Blocksatz (default)

Diese Aenderungen greifen erst wenn ein neuer Absatz beginnt. D.h. wir brauchen eine Leerzeile im Eingabetext oder wir fuegen mit `.sp' (= space) explizit selbst eine ein oder wir brechen mit `.br' (= break) explizit selbst um.

Hier sind diese Moeglichkeiten beispielhaft verwendet:

Code: Alles auswählen

.pl 1n
.ll 60
.ad c
Weihnachten.
.sp
.nf
Markt und Straßen stehn verlassen,
Still erleuchtet jedes Haus,
Sinnend geh’ ich durch die Gassen,
Alles sieht so festlich aus.
.fi

.ad r
An den Fenstern haben Frauen
Buntes Spielzeug fromm geschmückt,
Tausend Kindlein stehn und schauen,
Sind so wunderstill beglückt.

.ad c
Und ich wandre
.br
aus den Mauern
Bis hinaus in’s freie Feld,
.br
Hehres Glänzen, heil’ges Schauern!
.br
Wie so weit und still die Welt!

.ll 30
.ad b
Sterne hoch die Kreise schlingen,
Aus des Schneees Einsamkeit
Steigt’s wie wunderbares Singen –
O du gnadenreiche Zeit!

Daraus wird dann:

Code: Alles auswählen

:-Q preconv weihnachten3 | nroff
                        Weihnachten.

Markt und Straßen stehn verlassen,
Still erleuchtet jedes Haus,
Sinnend geh’ ich durch die Gassen,
Alles sieht so festlich aus.

         An den Fenstern haben Frauen Buntes Spielzeug fromm
geschmückt, Tausend Kindlein stehn und schauen, Sind so wun‐
                                          derstill beglückt.

                       Und ich wandre
         aus den Mauern Bis hinaus in’s freie Feld,
             Hehres Glänzen, heil’ges Schauern!
              Wie so weit und still die Welt!

Sterne hoch die Kreise schlin‐
gen,  Aus  des  Schneees  Ein‐
samkeit  Steigt’s  wie wunder‐
bares Singen – O du  gnadenre‐
iche Zeit!

Am letzten Absatz kann man besonders gut erkennen, dass nroff auch automatische Worttennungen beherrscht ... wenn auch hier nach den Regeln englischer Sprache auf einen deutschen Text angewandt, was beispielsweise bei ``gnadenreiche'' zu einem schlechten Ergebnis fuehrt. Das kann aber natuerlich auch umgestellt werden (`.hla' in groff, bzw. `.hylang' in Heirloom) oder man kann auch explizit potenzielle Trennmarkierungen fuer einzelne Woerter setzen. Mit `.nh' (= no hyphenation) schaltet man die automatische Trennung ab.


Gedichtformatierung

Ein Gedicht sollte natuerlich angemessen formatiert werden. D.h. die Zeilen sollen unveraendert bleiben, alles soll ein Stueck eingerueckt werden und wir wollen eine Zeilenzaehlung. Nroff bietet das natuerlich alles:

Code: Alles auswählen

.pl 1n  \" Seitenlaenge auf 1 Zeile
.ll 60  \" Zeilenlaenge auf 60 Zeichen
.ad c  \" zentrierter Text
Weihnachten.
.sp  \" eine Leerzeile
.nm 1 3 2 8  \" Zeilennummern, beginnend mit 1,
.\"           jede 3. nummerieren, 2 Zeichen Abstand
.\"           zum Text, alles 8 Zeichen einruecken
.nf  \" kein Filling (und folglich auch kein Adjusting)
Markt und Straßen stehn verlassen,
Still erleuchtet jedes Haus,
Sinnend geh’ ich durch die Gassen,
Alles sieht so festlich aus.

An den Fenstern haben Frauen
Buntes Spielzeug fromm geschmückt,
Tausend Kindlein stehn und schauen,
Sind so wunderstill beglückt.

Und ich wandre aus den Mauern
Bis hinaus in’s freie Feld,
Hehres Glänzen, heil’ges Schauern!
Wie so weit und still die Welt!

Sterne hoch die Kreise schlingen,
Aus des Schneees Einsamkeit
Steigt’s wie wunderbares Singen –
O du gnadenreiche Zeit!

Wie man sehen kann, leitet `\"' einen Kommentar ein. Will man eine ganze Zeile als Kommentarzeile haben, muss sie mit einem Punkt beginnen, damit sie als Befehlszeile gilt. Andernfalls wuerde der Kommentar zwar ignoriert aber dennoch eine leere Inputzeile gelesen werden, was u.a. das Ende des vorigen Absatzes bedeutet und damit die Ausgabe veraendert.

Generell kann man mit einem Backslash Escape-Sequenzen einleiten, um beispielsweise innerhalb eines Wortes die Schrift zu wechseln oder um Variablen auszugeben oder um Sonderzeichen und bestimmten Leerraum einzufuegen. Das geht aber ueber diese Einfuehrung hinaus.

Das Ergebnis ist folgendes:

Code: Alles auswählen

:-Q preconv weihnachten4 | nroff
                        Weihnachten.

             Markt und Straßen stehn verlassen,
             Still erleuchtet jedes Haus,
          3  Sinnend geh’ ich durch die Gassen,
             Alles sieht so festlich aus.

             An den Fenstern haben Frauen
          6  Buntes Spielzeug fromm geschmückt,
             Tausend Kindlein stehn und schauen,
             Sind so wunderstill beglückt.

          9  Und ich wandre aus den Mauern
             Bis hinaus in’s freie Feld,
             Hehres Glänzen, heil’ges Schauern!
         12  Wie so weit und still die Welt!

             Sterne hoch die Kreise schlingen,
             Aus des Schneees Einsamkeit
         15  Steigt’s wie wunderbares Singen –
             O du gnadenreiche Zeit!

Weitere Features

Nroff kann noch weit mehr:

- Kopf- und Fusszeilen
- Fussnoten
- verschiedene Schriften
- mehrspaltigen Text
- Schusterjungenvermeidung
- Tabellen (mit dem Hilfsprogramm `tbl')
- Literaturverzeichnisse (mit `refer')
- Bedingungen, Variablen
- (roemische) Seitennummern, Kapitelnummern und beliebige sonstige Zaehler
- Macros

Die Details findet man in der Dokumentation, fuer groff, bzw. fuer Heirloom nroff/troff.


Macropakete

Mittels Macros wurden Macropakete geschrieben, die mit `-m' verwendet werden koennen.

Das wichtigste Macropaket ist `an', das mit dem Aufruf `nroff -man' fuer Manpages verwendet wird. Dies laesst sich schnell testen:

Code: Alles auswählen

:-Q zcat /usr/share/man/man1/nroff.1.gz | nroff -man
NROFF(1)                                                              NROFF(1)



NAME
       nroff - emulate nroff command with groff

SYNOPSIS
       nroff [-CchipStUvwW] [-dcs] [-Mdir] [-mname] [-nnum] [-olist] [-rcn]
             [-Tname] [file ...]
       nroff --help
       nroff -v | --version

DESCRIPTION
       The nroff script emulates the nroff command using groff. [...]

Nichts anderes macht das `man'-Kommando intern letztlich. (Urspruenglich war `man' uebrigens nichts weiter als ein Shellscript. dass `nroff' mit der passenden Datei aufgerufen hat.)

Wenn man sich (mit `zless') den Quellcode der Manpage anschaut, dann erkennt man manches wieder, was wir schon kennengelernt haben, wie Befehlszeilen, die mit Punkt beginnen, und Kommentare. Man findet nroff-Kommandos, die aus zwei Kleinbuchstaben bestehen, und Macrokommandos, die aus ein oder zwei Grossbuchstaben bestehen. Letztere werden im Macropaket (oder wie im Beispiel von `OP' in der Manpage selbst) mit `.de' definiert (`..' markiert das Ende der Definition.)

Kurz zum Verstaendnis: `.SH' ist ein Section Heading. `.PP' ist ein (eingerueckter) Paragraph. `.B' steht fuer Bold Font (also Fettschrift), `.BR' bedeutet, dass das erste Argument fett formatiert werden soll und das zweite im nomalen (Roman) Font. `.SY' und `.OP' sind zur Angabe von Befehlsnamen (System Command) und Operatoren/Argumenten ... was man in Manpages halt so braucht.

Dass in nroff alle Befehle und Namen nur ein oder zwei Buchstaben haben, ist der Zeit seiner Entstehung geschuldet. Das muss man so akzeptieren. (Groff-Erweiterungen haben teilweise laengere Namen.)

Ein weiteres wichtiges Macropaket ist MS, also eigentlich `s', das man mit `-ms' nutzt. Damit lassen sich vor allem technische Papers gut schreiben. Es eignet sich auch gut als Basis fuer eigene Macropakete.


Troff

Troff ist der grosse Bruder zu nroff. Im Gegensatz zu nroff, das auf die Ausgabe von reinem Text im Terminal beschraenkt ist, kann troff beliebige Ausgaben fuer Laserdrucker, Plotter und PDF erzeugen. Es hat folglich deutlich mehr Faehigkeiten.

Generell kann mit troff & Co. jede nroff-Datei auch in ein PDF formatiert werden, wie beispielsweise eine Manpage:

Code: Alles auswählen

zcat /usr/share/man/man1/nroff.1.gz | troff -man | grops | ps2pdf - nroff.pdf

Auch lassen sich alle Macropakete gleichermassen mit nroff wie mit troff nutzen. Im Falle eines troff-Aufrufs machen sie nur meist zusaetzliche Dinge, die nur troff kann.

Dazu gehoeren:
- verschiedene Schriftarten in verschiedenen Schriftgroessen
- Linien und sonstige grafische Darstellungen wie Diagramme (mittels `pic' und `grap')
- mathematische Formeln beliebiger Komplexitaet (mittels `eqn')

Letztlich ist mit troff so gut wie alles moeglich was mit Latex auch moeglich ist (wenn auch in etwas archaischerer Weise). Einige bekannte Buecher sind damit gesetzt worden, siehe: https://www.troff.org/pubs.html


Schluss

Ich selbst verwende nroff und troff schon lange und regelmaessig. Fuer kuerzere Texte nutze ich nroff mit ein paar angepassten Macros. Bewerbungen und laengere Texte bis hin zu meiner Masterarbeit habe ich mit troff gesetzt. Man darf dabei natuerlich keinen heutigen Komfort erwarten, aber das tut man bei einem alten Rennwagen ja auch nicht, trotzdem ist es ein tolles Gefuehl, damit zu fahren ... der Sound, die Strasse direkt zu spueren, die Hitze, der Geruch ... so aehnlich sind nroff und troff auch -- einfach etwas fuer Liebhaber! ... und zum Verstaendnis von Unix und seiner Geschichte unerlaesslich.

Viel Vergnuegen beim Rumspielen!

[mn77de]

Vielen Dank für dieses lehrreiche Türchen!
Für meine eigenen Debian-Pakete wollte ich man-pages erstellen und bin anfangs ziemlich planlos vor dem nroff-Code gesessen.
Das erfordert echt einiges an Einarbeitungszeit!
Mächtig ja, aber ... puh!

Was wäre heutzutage die moderne Alternative? Vmtl. Markdown
Vielleicht würde eine Umstellung mehr Leute dazu bewegen, eine Man-Page zu erstellen?

Übrigens, es gibt auch Konverter, wie z.B.:

• pod2man
• info2man
• UUUUUnd: go-md2man

[uname]

Danke für den schönen Beitrag. Von nroff habe ich zuvor noch nichts gehört. Aber leider liest man auch immer weniger Manpages, obwohl Terminals so genial sind. Es ist schon traurig wie WYSIWYG-Systeme wie allen voran Mircosoft Word normale Schriftsetzungssysteme wie nroff, LaTeX, DocBook oder Markdown verhindern und praktisch jede automatisierte Bearbeitung unterbinden. Aber für Entscheidungsträger gibt es heute nur noch Single Vendor und damit Microsoft Office. Von den Milliarden bis Billionen Euro für unnötige Arbeitsstunden redet keiner. Schade.

[Meillo]

Für meine eigenen Debian-Pakete wollte ich man-pages erstellen und bin anfangs ziemlich planlos vor dem nroff-Code gesessen.
Das erfordert echt einiges an Einarbeitungszeit!
Mächtig ja, aber ... puh!

Diese Erfahrung kenne ich ... auch aus eigener Erfahrung damals. Ein bisschen ist das wie sed-Code zu sehen und nichts davon zu verstehen. Dabei ist es nicht unbedingt besonders schwierig, es ist nur vor allem ungewohnt. Fuer eine normale Manpage braucht man nicht viel: Befehlsnamen (.SY) und Argumente (.OP), Ueberschriften (.SH) und Absaetze (.PP), Fett-, Kursiv- und Normalschrift (.B, .I, .R plus Kombinationen wie .BR) ... das war's eigentlich schon. Es ist eher so, dass viele Manpages halt ein paar mehr Features nutzen als fuer einen Einsteiger noetig sind.

Markdown ist insofern gut, dass schon der Quellcode natuerlich lesbar ist. Dafuer ist es nur eine optische Auszeichnung, keine semantische. Ich kann also nicht unterscheiden, ob die Fettschrift ein Befehlsargument angibt oder eine Betonung ist.

Nroff ist zwar nicht intuitiv aber auch nicht schwer zu verstehen, wenn man sich darauf einlaesst. Die Huerde besteht nur aus einer gewissen Abwehrhaltung weil es auf den ersten Blick kryptisch aussieht und den meisten unbekannt ist (in der gleichen Weise wie sed und Regulaere Ausdruecke). Vielleicht hilft dieses Tuerchen dabei, diese Huerde zu reduzieren.

[hikaru]

Aber leider liest man auch immer weniger Manpages,

Manpages sind nicht meine Abendlektüre, aber wenn ich exakt genug weiß was ich will, um eine Fuzzy-Websuche unnötig zu machen, dann sind sie meine erste Anlaufstelle.
Ich gehe sogar so weit zu sagen, dass ich ein System ohne installierte Manpages als "kaputt" betrachte, genauso wie ich ein Desktop-System ohne Webbrowser als unvollständig betrachten würde.

Es ist schon traurig wie WYSIWYG-Systeme wie allen voran Mircosoft Word normale Schriftsetzungssysteme wie nroff, LaTeX, DocBook oder Markdown verhindern und praktisch jede automatisierte Bearbeitung unterbinden. Aber für Entscheidungsträger gibt es heute nur noch Single Vendor und damit Microsoft Office. Von den Milliarden bis Billionen Euro für unnötige Arbeitsstunden redet keiner. Schade.

Dass es auch dieses Problem gibt will ich nicht abstreiten. Hier sehe ich aber einen anderen Effekt am Werk: "Subproblem #5b: Inefficient is friendly" aus LNW. [1]
Ich musste mich nie mit Textsatz beschäftigen. Vom "Schusterjungen" hatte ich irgendwann schon mal gehört, wusste aber nicht mehr was es ist. Als ich es vorhin Meillos Beitrag las, bin ich also gleich rüber zu Wikipedia, um nochmal nachzuschauen.
Dass nroff irgendwas mit Manpages zu tun hat wusste ich. Meine Markdown-Kenntnisse sind eher "basic". Und mein Latex ist vermutlich schlechter als mein Klingonisch. Wenn ich alle paar Monate mal ein Textdokument (kein Plain-Text-ASCII) schreiben muss, dann ist ein WYSIWYG-Editer wie Libreoffice auf meinem Kenntnisstand schlicht einfacher zu bedienen, als mich z.B. weit genug in Latex einzufuchsen, um damit einen ansehnlichen Brief an eine Behörde verfassen zu können.


[1] https://linux.oneandoneis2.org/LNW.htm

[whisper]

Vielleicht hilft dieses Tuerchen dabei, diese Huerde zu reduzieren.

Türchen? Ein Garagentor für 2 Pickups
Ich ziehe den Hut vor deiner umfangreichen Beschreibung!


Apropos ManPage
Für die GUI affinen Leute: Ab trixie gibt es gtkman

(Früher war es tkman)

[MSfree]

Apropos ManPage
Für die GUI affinen Leute: Ab trixie gibt es gtkman

In den X11-apps gibt es xman. Das stammt mindestens aus den späten 1980ern, graphische Manpages sind also überhaupt nichts neues

[Huo]

Danke für das instruktive Türchen inklusive interessantem Ausflug in die Historie.

Die automatisch auf Debian installierte Implementierung von nroff aus dem Debiangroff Paket unterstuetzt leider kein UTF-8. Man muss daher die Eingangsdaten mit dem Programm `preconv' vorverarbeiten.

Ich mag archaische Kommandozeilen-Programme, mit nroff habe ich füher schon einmal experimentiert, um Texte zu formatieren. Leicht verzweifelt bin ich damals an der fehlenden UTF-8-Unterstützung. Auf die Lösung, preconv vorzuschalten, bin ich nicht gekommen. Dafür habe ich herausgefunden, dass es (unter Debian Bookworm) seltsamerweise mit purem groff und passenden Optionen klappt:

Code: Alles auswählen

$ groff -k -Tutf8 weihnachten4
                        Weihnachten.

             Markt und Straßen stehn verlassen,
             Still erleuchtet jedes Haus,
          3  Sinnend geh’ ich durch die Gassen,
             Alles sieht so festlich aus.

             An den Fenstern haben Frauen
          6  Buntes Spielzeug fromm geschmückt,
             Tausend Kindlein stehn und schauen,
             Sind so wunderstill beglückt.
             
             [...]

[Meillo]

Danke für das instruktive Türchen inklusive interessantem Ausflug in die Historie.

Die automatisch auf Debian installierte Implementierung von nroff aus dem Debiangroff Paket unterstuetzt leider kein UTF-8. Man muss daher die Eingangsdaten mit dem Programm `preconv' vorverarbeiten.

Auf die Lösung, preconv vorzuschalten, bin ich nicht gekommen. Dafür habe ich herausgefunden, dass es (unter Debian Bookworm) seltsamerweise mit purem groff und passenden Optionen klappt:

Code: Alles auswählen

$ groff -k -Tutf8 weihnachten4

-k Preprocess with preconv.

LOL

Das ist natuerlich einfacher ... allerdings zugleich komplexer. Die IMO wertvollste Lektion, die man von nroff lernen kann, ist IMO, dass man die meisten Probleme gut zerlegen kann und dass das Vorteile bietet. Bei nroff kann man jeden Zwischenschritt anschauen, die Pipeline an jeder Stelle auftrennen und reinschauen was passiert. Wenn ein Programm alle Teilschritte irgendwie magisch intern aufruft, dann ist es schwer, genau zu verstehen und begreifen zu koennen, was eigentlich passiert. So gesehen finde ich einen expliziten Aufruf von `preconv' besser, da er es erleichtert, zu verstehen, warum er noetig ist und was er tut. -- Das ist der Unterschied zwischen simple und easy.

(Heirloom nroff ruft intern kein `preconv' auf, sondern es unterstuetzt UTF-8 nativ.)

[whisper]

In den X11-apps gibt es xman. Das stammt mindestens aus den späten 1980ern, graphische Manpages sind also überhaupt nichts neues

Nee, kam das so rüber?
xman ist was für Leute, die Schmerzen mögen, tkman war damals das Mittel der Wahl für mich.
Gibt es nicht mehr, sondern jetzt gtkman.

Davon ab, nutze ich das auch nicht, sondern mache ein weiteres Tab im Terminal auf und starte da man und gut.

[Meillo]

Wenn ich alle paar Monate mal ein Textdokument (kein Plain-Text-ASCII) schreiben muss, dann ist ein WYSIWYG-Editer wie Libreoffice auf meinem Kenntnisstand schlicht einfacher zu bedienen, als mich z.B. weit genug in Latex einzufuchsen, um damit einen ansehnlichen Brief an eine Behörde verfassen zu können.

Gerade das waere eigentlich der optimale Usecase um Latex oder troff einzusetzen, mit einem passenden Macropaket bzw. einer passenden Vorlage, weil du dich dann eben nicht mehr um die Positionierung der Adresse und des Datums usw. kuemmern musst und neben einem professionellen Layout auch noch sowas wie Falt- und Lochmarkierungen geschenkt bekommst.

Siehe hierzu auch diesen Thread von vor acht Jahren: viewtopic.php?t=160032

Daraus stammen folgende zwei Links:

- Meine Briefmacros (fuer Heirloom troff): http://tmp.marmaro.de/troff-letter/brief
Sie sind okay, ihre Verwendung ist uebersichtlich, sie koennten aber noch semantischer gemacht werden (in der Form wie die Titelseiten bei den MS-Macros). Mein brief-Macros sind leider nicht groff-kompatibel und erfordern spezielle Schriften. (Das koennte ich aber aendern.)

- Von der groff-Mailingliste stammt diese Vorlage fuer DIN-Briefe: https://lists.gnu.org/archive/html/grof ... 00038.html
Das ist vom Ansatz meinem sehr aehnlich.


Eben habe ich noch ein Beispiel gefunden, wie man es nicht machen sollte:
https://www.preciouschicken.com/blog/po ... r-writing/
Das ist letztlich die Office-Denkweise: Die Positionierung der verschiedenen Teile wird bis zum User durchgereicht. Eigentlich sollte er davon gar nichts mitbekommen und damit auch nichts am Hut haben. Stattdessen sollte er nur inhaltlich sagen: ``Das ist die Zieladresse. Das ist der Betreff. Das ist ggf. mein Aktenzeichen. Das ist der Text.'' Alles Layouting sollte das Programm selbststaendig tun ... gerade bei etwas so standardisiertem wie einem formalen Brief. Einen besseren Usecase fuer den Einsatz von Latex oder troff gibt es kaum.

[Huo]

[...]Dafür habe ich herausgefunden, dass es (unter Debian Bookworm) seltsamerweise mit purem groff und passenden Optionen klappt:

Code: Alles auswählen

$ groff -k -Tutf8 weihnachten4

-k Preprocess with preconv.

LOL

Ha, hätte ich die Manpage sorgfältiger gelesen, hätte ich mir meine Verwunderung erspart.

Lese gerade im Changelog zu "Groff version 1.23.0":

nroff now recognizes the -b, -E, -k, -K, -R, and -z options and passes them through to groff.

Unter Bookworm habe ich noch Version 1.22.4, aber ab Trixie sollte man doch UTF-8-Unterstützung per nroff -k erhalten, oder?

[hikaru]

- Von der groff-Mailingliste stammt diese Vorlage fuer DIN-Briefe: https://lists.gnu.org/archive/html/grof ... 00038.html
Das ist vom Ansatz meinem sehr aehnlich.

Und ich fürchte, meine Reaktion darauf wäre ähnlich wie die, die der Autor dieser Vorlage bekam:
"Toll! Probier ich bei Gelegenheit aus und melde mich dann." ... 14 Jahre keine Rückmeldung.

[Meillo]

Lese gerade im Changelog zu "Groff version 1.23.0":

nroff now recognizes the -b, -E, -k, -K, -R, and -z options and passes them through to groff.

Unter Bookworm habe ich noch Version 1.22.4, aber ab Trixie sollte man doch UTF-8-Unterstützung per nroff -k erhalten, oder?

Sieht so aus. Das ist jedoch nur zur Bequemlichkeit, damit man `nroff -k' statt `groff -k -Tutf8' aufrufen kann. Die Funktionialitaet ist jetzt schon da, nur wird es vom nroff-Wrapper nicht intern an groff durchgereicht.

Man kann halt groff in seiner modernen Form nutzen. Oder man kann nroff in seiner alten Form nutzen. Die Frage ist, was soll passieren wenn man nroff in einer modernen Form nutzen will, z.B. fuer UTF-8-Input?

Die Antwort, die groff darauf bietet, finde ich nicht so gut: Wenn ich dann nroff mit neuen Optionen aufrufen muss, dann bin ich ja doch nicht mehr kompatibel und kann gleich groff aufrufen. Was gewinnt man dadurch nun?

Die Antwort von Heirloom nroff gefaellt mir besser: Das kann UTF-8 nativ verarbeiten und funktioniert damit einfach wie erwartet, ohne zusaetzliche Optionen.

Aber unterschiedliche Menschen bevorzugen unterschiedliche Herangehensweisen ...

Fast alle heutigen troff/nroff-User nutzen die groff-Implementierung. Sie hat eindeutig die groesste und auch eine aktive Community.

Heirloom troff/nroff ist in erster Linie ein Projekt, um den alten Code und das alte Verhalten von Programmen zu bewahren. Die ganzen (kompatiblen!) Erweiterungen bei nroff/troff sind wohl eher ein Liebhaberprojekt von Gunnar Ritter (aus Freiburg i. Br. ) gewesen. Die Qualitaet, die darin steckt, ist beeindruckend!

... aber das sind natuerlich Feinheiten, die fuer dieses Tuerchen eigentlich viel zu fortgeschritten sind.

[Meillo]

Vielleicht noch ein paar Worte zu Latex und troff.

Ich finde Latex ziemlich gut und habe damit auch schon viel gemacht. Letztlich ist das ja ein Macropaket fuer Tex. Heutzutage bietet es noch viel mehr drumherum. Erschreckend finde ich nur, dass ein Texlive (von 2013) knapp 4GB (!) gross ist. Dagegen umfassen die Heirloom doctools mit Sourcen und Binaries nicht mal 20MB!

Natuerlich kann Texlive viel mehr, bloss brauche ich das alles gar nicht. Ich will gar nicht mehr koennen als ich mit troff auch kann.

Wahrscheinlich gibt es auch kleinere Latex-Distributionen ... hat mir da jemand zufaellig einen Tipp?


Reines Tex ist fast so kryptisch wie nroff/troff, bloss dass es nie diese Beschraenkung der Bezeichner auf 1-2 Zeichen hatte. Man kann aber meist ganz ohne die Tex-Ebene auskommen und alles auf der Latex-Ebene machen. Bei nroff/troff muss man oefter low-level arbeiten.


Urspruenglich hat nroff Zeile fuer Zeile formatiert (wie ich es oben beschrieben habe). Tex dagegen war innovativ in der Weise, dass es ganze Absaetze auf einem formatiert hat und auch Absaetze dynamisch auf der Seite verteilen kann. Das fuehrt zu optisch besseren Ergebnissen. Absatzweises umbrechen kann nroff/troff inzwischen auch (zumindest als Heirloom-Erweiterung, wahrscheinlich in groff auch). Flexibles Layouten auf der Seite ist immer noch ein Problem. Auch lassen sich Hurenkinder kaum vermeiden (Schusterjungen dagegen schon).


Ein weiterer Unterschied ist, dass nroff problemlos und direkt eine reine Textversion eines grafischen troff-Dokuments erstellen kann, waehrend das bei Latex kaum moeglich ist. Ich glaube, ich habe damals dann einfach pdftotext genutzt.

Neben der deutlich groesseren Einfachheit und Verstehbarkeit ist die Moeglichkeit, auch reine Textdokumente zu formatieren, fuer mich ein wichtiger Grund, nroff/troff zu verwenden, statt Latex.

[chrbr]

Was wäre heutzutage die moderne Alternative? Vmtl. Markdown
Vielleicht würde eine Umstellung mehr Leute dazu bewegen, eine Man-Page zu erstellen?

Im netpbm Projekt wird ein Python-Skript "makeman" verwendet, das eine statische HTML-Seite in eine man-page konvertiert. Zu finden ist das Skript in den Quellen unter "buildtools". Die aktuelle Version hat einen kleinen Fehler, die in Bug#1087509 beschrieben und behoben ist. Irgendwann wird das hoffentlich Upstream einfliessen.

[chrbr]

Als kleines Beispiel:

Im vim-Projekt werden die man-pages in diesem Format gepflegt. Das wird sich vielleicht auch nicht ändern, weil die Aufrufe und Optionen inzwischen kaum einer Aktualisierung bedürfen. Für die Online-Hilfe wird dagegen po4a verwendet. Hier ist als Beispiel ein kurzer Abschnitt aus der Seite, die man als "man vim" angezeigt bekommt:

Code: Alles auswählen

...
 .PP
  vim [Optionen] [Dateiliste]
.PP
Bei einer fehlenden Dateiliste startet der Editor mit einem leeren
Puffer. Andernfalls werden nach den folgenden vier Möglichkeiten eine oder
mehrere Dateien bearbeitet:
.TP  12  
Datei …
Eine Liste von Dateinamen. Die erste Datei wird in den Puffer geladen und 
zur aktuellen. Der Cursor wird auf der ersten Zeile des Puffers
platziert. Zu den anderen Dateien kann mit dem Befehl »:next« gelangt
werden. Falls einer der Dateinamen mit einem Bindestrich beginnt, stellen
Sie der Dateiliste »\-\-« voran.
.TP 
\-
Die zu bearbeitende Datei wird von der Standardeingabe gelesen. Befehle
werden von der Standardfehlerausgabe gelesen, die ein Text\-Terminal sein
sollte.
...

Das ist nun wirklich kein Hexenwerk, oder?

[ralli]

Früher habe ich meine eigenen Dokus und Workshops mit Lyx und LaTeX verfasst. Seit einiger Zeit benutze ich allerdings das Dokumentationstool Scribble, das ein Teil der Lehrsprache Racket ist. Racket ist für Debian vorhanden und kommt mit einer eigenen IDE(DrRacket). Die Syntax (Gliederungsbefehle - section - subsection usw.) für ein mit Scribble geschriebenes Manual ist in den Grundzügen wie LaTeX. Da mußte ich nicht viel umdenken. Scribble erstellt dann auf Wunsch davon eine PDF Datei oder generiert komplettes HTML mit eigenen Style. Wenn Bedarf besteht, könnte ich ein Beispiel posten.

Für die PDF Ausgabe muß allerdings LateX installiert sein, und zwar das Paket texlive-full.

Nun aber zu Deinem Türchen. Danke dafür, großartig. Wollte mich schon immer mal mit nroff beschäftigen, bin dann aber warum auch immer davon abgekommen. Mir schwebt da ein Nutzen von nroff vor, das muß ich aber erst noch testen. Wenn ich in einer sqlite Datenbank ein Feld mit sehr langem Text habe (ähnlich einem Memofeld), dann möchte ich bei einer Suche eine formatierte Ausgabe im Blocktext haben, weil das übersichtlicher zu lesen ist. Das werde ich mir morgen mal anschauen.

Gruß ralli

[Meillo]

Wollte mich schon immer mal mit nroff beschäftigen, bin dann aber warum auch immer davon abgekommen. Mir schwebt da ein Nutzen von nroff vor, das muß ich aber erst noch testen. Wenn ich in einer sqlite Datenbank ein Feld mit sehr langem Text habe (ähnlich einem Memofeld), dann möchte ich bei einer Suche eine formatierte Ausgabe im Blocktext haben, weil das übersichtlicher zu lesen ist. Das werde ich mir morgen mal anschauen.

Wenn es nicht unbedingt Blocksatz sein muss, sondern auch ein auf eine gewuenschte Breite gebrachter Text sein kann, dann kannst du das auch mit `fmt' machen, was deutlich simpler als nroff ist.

Alternativ koenntest du auch einen Scripting-Contest hier im Forum starten, fuer ein Programm, das einfach nur Text als Blocksatz bestimmter Breite formatiert. Das hoert sich jedenfalls nach einer spassigen Aufgabe an. Das Verfahren kann man ja von nroff abkupfern.

Das waere in deinem Fall vielleicht geeigneter als nroff, da du nur genau einen Anwendungsfall hast, nroff aber so vieles kann, was du teilweise nicht haben willst. Falls in deinem Text naemlich eine Zeile mit einem Punkt oder Singlequote beginnen wuerde, dann wuerde diese nicht ausgegeben, sondern als Befehl interpretiert werden. (Unbekannte Befehle ignoriert nroff einfach.) Die Zeile wird dadurch ``verschwinden''. Auch alle Backslashes fuehren zu Problemen. Folglich muesstest du dir zuerst eine Verbatim-Umgebung um den Text rumbauen. Das ist schon moeglich, erfordert aber einen Mehraufwand, der fuer deinen Anwendungsfall eher zu hoch ist ... insofern du es nicht als Lernprojekt ansiehst.


Ich nutze nroff um solche Texte zu schreiben: http://marmaro.de/apov/txt/2018-09-02_kommentare.txt
Der nroff-Quellcode dafuer ist: 42266

Erlaeuterungen: .QS = Quote Start, .QE = Quote End, .CS = Code Start, .CE = Code End. Die Befehle in den ersten Zeilen der Datei erzeugen den Header. Der Footer wird automatisch erzeugt.

In den Codeabschnitten muss man Backslashes escapen. Wenn man das auch noch weg haben will, dann ist das moeglich, indem man den Backslash sowie Punkt und Singlequote am Zeilenbeginn auf andere, beispielsweise nicht druckbare Zeichen legt, wie ich es fuer meine Masterarbeit gemacht habe:

Code: Alles auswählen

.       \" VS - verbatim text start (\\ -> ^G; ' -> disabled; . -> ^B)
.de VS
.br
.ne 3
.sp \n(DDu
.di _V
.nf
.ft CW
.ps -.5
.\" set up verbatim environment
\.blm
\.ec ^G
\.c2 ""
\.cc ^B
..

.       \" VE - verbatim text end  (NOTE: Needs to be called as ^BVE !)
.de VE
^B\" restore the special characters
^Bcc
.c2
.ec
.br
.di
.ne \\n(dnu+1v \" ensure enough space on the page
.in +2u*\\n(PIu
.ta T 8n
\.ec ^G \" set up verbatim environment, once again
\.c2 ""
\.cc ^B
^B_V \" output the verbatim content
^B\" restore the special characters
^Bcc
.c2
.ec
.blm __
.in -2u*\\n(PIu
.sp \n(DDu
.ps +.5
.ft P
.fi
.TA
..

(Die `^B' und `^G' sind jeweils literal eingegebene Zeichen, die hier nur in ihrer Ersatzdarstellung sichtbar sind.)

Diese zwei Macros zu verstehen ist natuerlich sehr fortgeschritten, aber auch lehrreich. (Falls Bedarf daran besteht (und mich ChatGPT nicht schon ueberfluessig gemacht hat), kann ich Hilfestellungen dazu geben.)

[JTH]

Danke für das Türchen, Meillo

[ralli]

Danke für die detaillierte Antwort Meillo. Auch wenn es für die formatierte Ausgabe von sqlite nicht sinnvoll ist, so werde ich mir dennoch nroff näher anschauen.

Gruß ralli

[Meillo]

Alternativ koenntest du auch einen Scripting-Contest hier im Forum starten, fuer ein Programm, das einfach nur Text als Blocksatz bestimmter Breite formatiert. Das hoert sich jedenfalls nach einer spassigen Aufgabe an. Das Verfahren kann man ja von nroff abkupfern.

Auf diese Programmieridee hatte ich gestern Lust und habe sie mal umgesetzt, zuerst auf Byte-Basis und danach noch in einer Variante, die mit Multi-Byte-Encodings klar kommt, da das Weihnachtsgedicht Umlaute enthaelt.

http://tmp.marmaro.de/dfde/blocksatz.c
http://tmp.marmaro.de/dfde/blocksatz-mb.c

Das war eine nette Fingeruebung.

[Dogge]

Apropos ManPage
Für die GUI affinen Leute: Ab trixie gibt es gtkman

Mir ist zwar einfach `man program` im Terminal am Liebsten, aber wenn es schon grafisch sein muss, dann ist mir `yelp man:program` noch lieber als gtkman, da yelp Referenzen klickbar macht.

Zum Adventskalender: Wow, das ist echt verständlich erklärt. Ich fand das Format so abschreckend, dass ich meine manpages in markdown schreibe und dann mit ronn konvertiere.