Dlaczego strony podręcznika man nie mają przykładów?

Czy istnieje powód, dla którego większość stron podręcznika nie zawiera kilku typowych przykładów? Zazwyczaj wyjaśniają wszystkie możliwe opcje, ale to sprawia, że ​​początkujący jeszcze trudniej jest zrozumieć, w jaki sposób jest „zwykle” używany.

To zależy od strony człowieka ... Tradycyjnie, że nie zawiera sekcję z przykładów - ale z jakiegoś powodu, który jest zwykle brakuje stron podręcznika pod Linuksem (i zakładam inny pomocą poleceń GNU - które są w większości te dni). Z drugiej strony w systemie Solaris prawie każda strona podręcznika zawiera sekcję Przykład, często z kilkoma przykładami.

Jeśli miałbym zgadywać, FSF / GNU od dawna zniechęcają do korzystania ze manstron i wolą, aby użytkownicy zamiast tego używali informacji do dokumentacji. infostron wydają się być bardziej wszechstronny niż strony podręcznika i zazwyczaj nie zawierają przykłady. infostrony są również bardziej „aktualne” - tzn. powiązane polecenia (np. polecenia do wyszukiwania plików) często można znaleźć razem.

Innym powodem może być to, że GNU i jego manstrony są używane w wielu różnych systemach operacyjnych, które mogą się od siebie różnić (w końcu istnieje wiele różnic między poszczególnymi dystrybucjami Linuksa). Być może wydawca dodał przykłady związane z konkretnym systemem operacyjnym / dystrybucją - co oczywiście jest rzadko wykonywane.

Dodałbym również, że manstrony nigdy nie były przeznaczone do „nauczania początkujących”. UNIX został opracowany przez ekspertów komputerowych (dawne określenie „hakerzy”) i przeznaczony do wykorzystania przez ekspertów komputerowych. Strony podręcznika nie zostały więc stworzone, by uczyć nowicjusza, ale aby szybko pomóc ekspertowi komputerowemu, który potrzebował przypomnienia o jakiejś niejasnej opcji lub dziwnym formacie pliku - i znajduje to odzwierciedlenie w sposobie podziału strony podręcznika.

man-strony są zatem rozumiane jako

• Szybki przegląd, aby odświeżyć pamięć; pokazując, jak należy wywołać polecenie, i wyświetlając dostępne opcje.
• Dogłębny i dokładny - i zazwyczaj bardzo techniczny - opis wszystkich aspektów polecenia. Jest napisany przez ekspertów komputerowych, dla innych ekspertów komputerowych.
• Lista zmiennych środowiskowych i plików (tj. Plików konfiguracyjnych) używanych przez polecenie.
• Odniesienia do innej dokumentacji (np. Książek) i innych manstron - np. dla formatu plików konfiguracyjnych i powiązanych / podobnych poleceń.

To powiedziawszy, bardzo się z tobą zgadzam, że manstrony powinny mieć przykłady, ponieważ mogą one lepiej wyjaśnić użycie niż brodzenie przez samą stronę podręcznika. Szkoda, że ​​przykłady na ogół nie są dostępne na manstronach systemu Linux ...

Przykład przykładowej części strony podręcznika Solaris - zfs (1M):

(...)
PRZYKŁADY
     Przykład 1 Tworzenie hierarchii systemu plików ZFS

     Następujące polecenia tworzą system plików o nazwie pool / home
     oraz system plików o nazwie pool / home / bob. Punkt montowania
     / export / home jest ustawiony dla nadrzędnego systemu plików i ma wartość
     automatycznie dziedziczone przez podrzędny system plików.

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

     Przykład 2 Tworzenie migawki ZFS

     Następujące polecenie tworzy migawkę o nazwie wczoraj.
     Ta migawka jest montowana na żądanie w .zfs / snapshot
     katalog w katalogu głównym systemu plików pool / home / bob.

       # zfs snapshot pool / home / bob @ wczoraj

     Przykład 3 Tworzenie i niszczenie wielu migawek

     Następujące polecenie tworzy migawki o nazwie wczoraj
     pool / home i wszystkie jego potomne systemy plików. Każdy
     migawka jest montowana na żądanie w katalogu .zfs / snapshot
     w katalogu głównym systemu plików. Drugie polecenie niszczy
     nowo utworzone migawki.

       # migawka zfs -r pool / home @ wczoraj
       # zfs destroy -r pool / home @ wczoraj

SunOS 5.11 Ostatnia zmiana: 23 lipca 2012 r. 51

Polecenia administracji systemu zfs (1M)

     Przykład 4 Wyłączanie i włączanie kompresji systemu plików

     Następujące polecenie wyłącza właściwość kompresji dla
(...)

Ta konkretna strona podręcznika zawiera 16 (!) Takich przykładów ... Uznanie dla Solaris!
(I przyznaję, że sam najczęściej podążałem za tymi przykładami, zamiast czytać całą stronę podręcznika dla tego polecenia ...)

Myślę, że nie ma na to dobrej odpowiedzi. To kwestia kultury. Niektóre strony podręcznika mają przykładowe użycie. Np man rsync. Możesz spróbować zmienić kulturę, pisząc do autora strony podręcznika man i prosząc go o dodanie przykładowego użycia lub (znacznie lepiej) samemu oferując przykłady użycia próbki. Jeśli zaoferujesz autorowi bezpłatnego oprogramowania łatkę, szczególnie łatkę do dokumentacji, prawdopodobieństwo uzyskania pożądanego rezultatu będzie około dziesięć tysięcy razy większe niż zwykłe żądanie.

To zależy:

• większość programów, które mogą Cię zainteresować, są opracowywane przez pewien czas, początkowo w celu rozwiązania problemu, a następnie w celu ulepszenia rozwiązania. Twórcy programów wyjaśniają, co uważali za ważne, aby wiedzieć (a dokumentacja nie stanowiła problemu, który rozwiązali).

• w przypadku niektórych programów programiści wolą udostępnić przykładowe programy lub skrypty, które pokazują, jak korzystać z danego programu (lub biblioteki). Ponownie robi się to w celu rozwiązania problemu: ułatwienie testowania programu.

  Niektóre z przykładów mogą opierać się na raportach o błędach od użytkowników, a gdy w skrócie znajdzie miejsce w instrukcji. Długie przykłady rzadko są podawane w instrukcjach, a krótkie przykłady mają problem z tym, że są one trywialne, powtarzalne i tak naprawdę nie zapewniają użytkownikowi tyle wglądu, co dobrze zorganizowany opis działania programu.

• w niektórych przypadkach znajdziesz dokumentację dostarczoną przez inne osoby, które nie są zaangażowane w proces rozwoju. Oznacza to, że programiści nie brali udziału poza przeglądem dokumentacji. Tego rodzaju wysiłek można pominąć.

Jeśli szukasz alternatywy dla stron podręcznika man, zawsze możesz wypróbować strony bro , które pokazują tylko różne przykłady polecenia, a następnie możesz głosować na liście przykładów przesłanych przez społeczność. Na przykład polecenie bro tarda ci: