Warum gibt es auf Manpages keine Beispiele?

Gibt es einen Grund, warum die meisten Manpages nicht einige gängige Beispiele enthalten? Sie erklären normalerweise alle möglichen Optionen, aber das macht es für einen Anfänger noch schwieriger zu verstehen, wie es "normalerweise" verwendet wird.

Das hängt von den Manpages ab ... Traditionell haben sie einen Abschnitt mit Beispielen enthalten - aber aus irgendeinem Grund fehlt dies normalerweise in den Manpages unter Linux (und ich gehe davon aus, dass andere GNU-Befehle verwendet werden - das sind die meisten dieser Tage). Auf Solaris hingegen enthält fast jede Manpage den Abschnitt Example, häufig mit mehreren Beispielen.

Wenn ich raten sollte, hat FSF / GNU lange Zeit davon abgeraten, manSeiten zu verwenden, und Benutzer ziehen es vor, stattdessen Informationen für die Dokumentation zu verwenden. infoSeiten sind in der Regel umfassender als man - Seiten zu sein, und in der Regel keine Beispiele umfassen. infoSeiten sind auch "aktueller" - dh verwandte Befehle (z. B. Befehle zum Suchen von Dateien) können oft zusammen gefunden werden.

Ein weiterer Grund kann sein, dass GNU und seine manSeiten auf vielen verschiedenen Betriebssystemen verwendet werden, die sich voneinander unterscheiden können (es gibt schließlich viele Unterschiede nur zwischen verschiedenen Linux-Distributionen). Die Absicht könnte gewesen sein, dass der Verlag Beispiele hinzufügte, die für das jeweilige Betriebssystem / die jeweilige Distribution relevant sind - was offensichtlich selten der Fall ist.

Ich würde auch hinzufügen, dass manSeiten niemals dazu gedacht waren, "Anfänger zu unterrichten". UNIX wurde von Computerfachleuten (alter Begriff "Hacker") entwickelt und soll von Computerfachleuten verwendet werden. Die Handbuchseiten wurden daher nicht erstellt, um Anfänger zu unterrichten, sondern um einem Computerexperten schnell zu helfen, der eine Erinnerung für eine undurchsichtige Option oder ein seltsames Dateiformat benötigte - und dies spiegelt sich in der Aufteilung einer Handbuchseite wider.

man-Seiten sind also gedacht als

• Eine Kurzreferenz, um Ihr Gedächtnis aufzufrischen. Zeigt an, wie der Befehl aufgerufen werden soll, und listet die verfügbaren Optionen auf.
• Eine ausführliche und in der Regel sehr technische Beschreibung aller Aspekte des Befehls. Es wurde von Computerexperten für Computerkollegen geschrieben.
• Liste der Umgebungsvariablen und -dateien (dh Konfigurationsdateien), die vom Befehl verwendet werden.
• Verweis auf andere Dokumentation (z. B. Bücher) und andere manSeiten - z. für das Format von Konfigurationsdateien und verwandten / ähnlichen Befehlen.

Trotzdem stimme ich Ihnen sehr zu, dass manSeiten Beispiele enthalten sollten, da sie die Verwendung besser erklären können als das Durchblättern der Manpage. Schade, dass Beispiele auf Linux- manSeiten im Allgemeinen nicht verfügbar sind ...

Beispiel für den Beispielteil einer Solaris-Manpage - zfs (1M):

(...)
Beispiele
     Beispiel 1 Erstellen einer ZFS-Dateisystemhierarchie

     Die folgenden Befehle erstellen ein Dateisystem mit dem Namen pool / home
     und ein Dateisystem namens pool / home / bob. Der Einhängepunkt
     / export / home ist für das übergeordnete Dateisystem festgelegt und lautet
     automatisch vom untergeordneten Dateisystem geerbt.

       # zfs erstelle pool / home
       # zfs set mountpoint = / export / home pool / home
       # zfs create pool / home / bob

     Beispiel 2 Erstellen eines ZFS-Snapshots

     Der folgende Befehl erstellt einen Snapshot mit dem Namen "gestern".
     Dieser Snapshot wird bei Bedarf im .zfs / Snapshot bereitgestellt
     Verzeichnis im Stammverzeichnis des Dateisystems pool / home / bob.

       # zfs snapshot pool / home / bob @ gestern

     Beispiel 3 Erstellen und Löschen mehrerer Snapshots

     Mit dem folgenden Befehl werden Snapshots mit dem Namen "gestern von" erstellt
     pool / home und alle untergeordneten Dateisysteme. Jeder
     Der Snapshot wird bei Bedarf im Verzeichnis .zfs / snapshot bereitgestellt
     an der Wurzel seines Dateisystems. Der zweite Befehl zerstört
     die neu erstellten Schnappschüsse.

       # zfs snapshot -r pool / home @ gestern
       # zfs destroy -r pool / home @ gestern

SunOS 5.11 Letzte Änderung: 23. Juli 2012 51

Systemadministrationsbefehle zfs (1M)

     Beispiel 4 Deaktivieren und Aktivieren der Dateisystemkomprimierung

     Der folgende Befehl deaktiviert die Komprimierungseigenschaft für
(...)

Diese spezielle Manpage enthält 16 (!) Solcher Beispiele ... Ein großes Lob an Solaris!
(Und ich gebe zu, dass ich selbst diesen Beispielen größtenteils gefolgt bin, anstatt die gesamte Manpage für diesen Befehl zu lesen ...)

Ich glaube nicht, dass es eine gute Antwort darauf gibt. Es ist eine Kultursache. Einige Handbuchseiten verwenden Beispiele. Eg man rsync. Sie können versuchen, die Kultur zu ändern, indem Sie dem Autor der Manpage schreiben und ihn bitten, einige Beispiele für die Verwendung hinzuzufügen oder (viel besser) einige Beispiele für die Verwendung selbst anzubieten. Wenn Sie einem freien Software-Autor einen Patch, insbesondere einen Dokumentations-Patch, anbieten, ist es ungefähr zehntausendmal wahrscheinlicher, das gewünschte Ergebnis zu erzielen als eine einfache Anfrage.

Es hängt davon ab, ob:

• Die meisten der für Sie interessanten Programme wurden über einen bestimmten Zeitraum entwickelt, um zunächst ein Problem zu lösen und später die Lösung zu verbessern. Die Entwickler der Programme erklären, was sie für wichtig hielten (und die Dokumentation war nicht das Problem, das sie lösten).

• für einige Programme, bevorzugen die Entwickler Probe zur Verfügung zu stellen Programme oder Skripte , die zeigen , wie ein bestimmtes Programm (oder Bibliothek) verwenden. Auch dies geschieht, um ein Problem zu lösen: Das Programm ist einfacher zu testen.

  Einige der Beispiele basieren möglicherweise auf Fehlerberichten von Benutzern und wenn short einen Platz im Handbuch findet. Ausführliche Beispiele werden in Handbüchern selten zur Verfügung gestellt, und kurze Beispiele haben das Problem, dass sie in der Regel trivial und repetitiv sind und dem Benutzer nicht so viel Einsicht bieten wie eine gut organisierte Beschreibung der Funktionsweise eines Programms.

• In einigen Fällen finden Sie Dokumentation, die von anderen Personen bereitgestellt wird, die nicht am Entwicklungsprozess beteiligt sind. Das heißt, die Entwickler haben nur an der Überprüfung der Dokumentation teilgenommen. Diese Art von Anstrengung kann ignoriert werden.

Wenn Sie nach einer Alternative zu Manpages suchen, können Sie immer Bro-Pages ausprobieren , die einem Befehl nur verschiedene Beispiele zeigen, über die Sie dann in einer Liste von Beispielen abstimmen können, die von der Community eingereicht wurden. Der Befehl bro targibt beispielsweise Folgendes aus: