man-Seiten sind großartig, das Problem sind die man-Reader

• Kritik an man-Seiten wie „es gibt keine verlinkten Verweise“ oder „wenn man das Terminalfenster verkleinert, wird der Text nicht neu umbrochen“ ist weit verbreitet, tatsächlich unterstützt das man-Format selbst aber sowohl Verlinkungen als auch Neuumbruch
• Das Problem ist, dass die Werkzeuge zum Lesen von man-Seiten (der man-Befehl, less usw.) diese Funktionen nicht richtig implementiert haben

Aufbau des man-Seiten-Formats

• man-Dokumente werden hauptsächlich in zwei Formaten geschrieben:
  • mdoc(7): modernes, semantikbasiertes Markup-Format
  • man(7): veraltetes Format, das von 1979 bis 1989 verwendet wurde
• Beispiel (ein Teil der mdoc-Syntax):

  .Sh NAME  
  .Nm openrc  
  .Nd stops and starts services for the specified runlevel  
  .Sh SYNOPSIS  
  

• .Sh, .Nm und .Nd stehen jeweils für Abschnittsüberschrift, Befehlsname und Beschreibung
• Wer direkt bearbeiten will, muss die Liste der mdoc-Makros nachschlagen

Auch die Verweisfunktion ist eingebaut

• Das mdoc-Format enthält die folgenden Link-Makros:
• .Xr: Querverweis auf eine andere man-Seite
• .Sx: Verweis auf einen anderen Abschnitt innerhalb derselben Seite
• Bei der Umwandlung in HTML werden sie als echte Links gerendert und sind im Browser anklickbar
• Abschnittsüberschriften mit .Sh werden als Anker behandelt und können als Ziel von .Sx-Links dienen
• Beim Anzeigen im Terminal mit dem man-Befehl funktionieren diese Link-Funktionen jedoch nicht

Fazit: Das Problem ist nicht das man-Format, sondern der Viewer

• Der aktuelle man-Befehl zeigt Seiten an, indem er sie an less weiterleitet; auf diese Weise lassen sich Links nicht verarbeiten
• Die Lösung ist:
• Ein neuer Seiten-Viewer, der das man-Format versteht und Links unterstützt
• Noch besser wäre es, wenn dabei auch automatischer Text-Neuumbruch (reflow) bei Änderungen der Terminalbreite implementiert würde

Hintergrundinformationen

• mdoc(7) wurde in den 1990er-Jahren mit 4.4BSD eingeführt
• man(7) ist ein klassisches Format, das zwischen 1979 und 1989 verwendet wurde und heute kaum noch im Einsatz ist

[scari]

Ich habe im Slackbot-Benachrichtigungsfeed schon nach der ersten Zeile sofort mitgefühlt und geklickt. Ich stimme der Einschätzung, dass der Reader das Problem ist, ebenfalls zu 100 % zu.

...Aber die moderne Menschheit scheint ja weder man noch überhaupt das Terminal zu benutzen. rtfm ist wohl zu einem Relikt aus der romantischen Vergangenheit geworden.

[winterjung]

Ich habe auf dem Mac Folgendes definiert und nutze es dann wie pman ls, um die Ausgabe als PDF anzusehen.

pman() {  
  mandoc -Tpdf "$(man -w $@)" | open -f -a Preview  
}  

[pcj9024]

Mega-Tipp ... danke!

[pkj3186]

Wow, vielen Dank!

[bbulbum]

Wow, das fühle ich total. Wenn man man gut lesen kann, ist es wirklich großartig, aber es ist einfach verdammt schwer, es gut zu lesen..

[GN⁺]

Hacker-News-Kommentar

• Es gibt die Meinung, dass man zwar seit Langem Dokumente in den Formaten mdoc und mandb schreibt, es aber schwierig ist, die Sprache wirklich zu beherrschen
  • mdoc und mandb sind so etwas wie Makro-Sets auf roff
  • Es gibt den Vorschlag, alle man-Seiten in Markdown zu konvertieren und sie so im System anzuzeigen
  • Für Markdown gibt es mehr Werkzeuge, und auch nichttechnische Nutzer können damit leichter Dokumentation schreiben
  • Allerdings ist Markdown weniger formalisiert, sodass in verschiedenen Programmen unterschiedliche Dialekte existieren
• Das Navigieren in Info-Seiten in Emacs ist nützlich, und Ähnliches sollte auch mit man-Seiten möglich sein
  • Der Reichtum bestehender man-Seiten ist ein Vorteil, den viele nicht wahrnehmen
  • Es wird bedauert, dass manche auf Markdown umsteigen wollen
  • Bei einer Umstellung auf Markdown dürfte es schwierig werden, Links und die allgemeine Semantik bestehender Lösungen umzusetzen
  • An Beispielen, bei denen Daten nach JSON verschoben wurden, zeigt sich, dass dann versucht wird, komplexe Funktionen hinzuzufügen
• Die Verwendung des eingebauten ft-man-Plugins von Vim als Standardanzeige für man-Seiten hilft bei der Problemlösung
  • Links funktionieren, und beim Zeilenumbruch bleibt die Einrückung erhalten
  • Die Standardeinstellungen von less ließen sich verbessern, allerdings wäre horizontales Scrollen nötig
• Viele Web-Versionen von man-Seiten verwenden leider eine monotone Schriftart
  • Die Online-man-Seiten von OpenBSD sind hervorragend
  • Es ist auch gut, man-Seiten im Terminal zu lesen
  • Hauptsächlich werden die Suchfunktion und das Scrollen um eine halbe Seite genutzt
• pinfo ist eigentlich zum Anzeigen von GNU-Info-Seiten gedacht, kann aber auch man-Seiten darstellen
  • Es erkennt Querverweise zwischen Seiten und ermöglicht die Navigation
• Es wird der Wunsch geäußert, direkt zur Beschreibung eines bestimmten Flags springen zu können
  • Derzeit werden reguläre Ausdrücke verwendet, um die Beschreibung eines Flags zu finden
• Es wird vorgeschlagen, das mandoc-Projekt in Betracht zu ziehen
  • Da Seiten semantisch verarbeitet werden, lassen sich bessere Ergebnisse erzielen
• Es gibt die Meinung, dass Markdown die bessere Lösung ist
  • Man hat sich daran gewöhnt, Dokumentation im Web oder im Code-Editor zu lesen, daher sind andere Oberflächen unbequem
  • Entwickler sind mit Markdown vertraut, und die meiste Dokumentation wird ebenfalls in Markdown geschrieben
  • man-Seiten sind sowohl für Autoren als auch für Leser die schlechtere Lösung