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

52

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.

Deepak Joy
źródło
1
Domyślam się, że chcieli zaoszczędzić cenne miejsce na dysku, na przykład pozbywając się CR. Por. Beckett, Watt , s. 8: „Dużo cennej przestrzeni zostało uratowanych [...] przez unikanie mnogiego zaimka zwrotnego po powiedzeniu .”
Peter - Przywróć Monikę
3
Jedną próbą obejścia tego problemu jest tldr-pages.github.io , chociaż nie rozumiem, dlaczego ułatwiają pobieranie wszystkiego z góry w celu uzyskania dostępu offline.
Nathan Long
man jqma ponad 1000 linii przykładów (na Ubuntu 16.04)
Motte001

Odpowiedzi:

49

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 ...)

Baard Kopperud
źródło
2
Ostatnie zdanie podkreśla problem z umieszczaniem przykładów w instrukcjach. Weźmy przykłady, które najlepiej pasują do twoich potrzeb, nie w pełni rozumiejąc implikacje konkretnego zastosowania narzędzia. A później można po prostu powiedzieć „Zrobiłem to w ten sposób”, ale nie do końca dlaczego i co to znaczyło.
Kusalananda
6
@Kusalananda W mojej obronie, ja już przeczytać o różnych opcji oraz o podkomendy ja rzeczywiście potrzebne - po prostu nie cała rzecz (jeszcze). To nie jest po prostu odpowiednie dla mojego użytku ... Mimo niebezpieczeństwa niewłaściwego użycia, przykłady mają służyć jakiemuś celowi - i jeśli wszystko czego potrzebujesz to tylko najbardziej podstawowe użycie polecenia, czytanie o wszystkich wodotryski są wcale konieczne.
Baard Kopperud,
@Kusalananda Może to również zależeć od poleceń. Większość narzędzi Uniksa i GNU, które znam, są dobrze udokumentowane, ale potrzebujesz dokumentacji, aby zrobić coś sensownego. Nowsze polecenia Solaris (zwłaszcza zfs) są zaprojektowane całkiem naturalnie. Na przykład zfs destroy pool/filesystemjest to podstawowe użycie i grzywna w przypadku 90% przypadków użycia. Krótkie opcje jak -rdla recursivesą bardziej specjalne i wymagają konsultacji przed użyciem, ponieważ mogą mieć niezamierzone skutki uboczne.
user121391,
26

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.

Faheem Mitha
źródło
7

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ąć.
Thomas Dickey
źródło
5
„Tego rodzaju wysiłek można pominąć”. Nie jestem pewien, co to znaczy.
Faheem Mitha
Dokumentacja nie wnosi nic przydatnego, jeśli nie jest oparta na doświadczeniu.
Thomas Dickey,
W rzeczywistości dokumentacja nieoparta na doświadczeniu może mieć negatywny wpływ - tzn. Jest po prostu błędna.
alephzero
Jasne - wspomniałem o tym, ponieważ niektóre przykłady, które OP ma niewątpliwie na myśli, należą do tej kategorii (powstrzymam się od podawania listy na tym forum).
Thomas Dickey,
2
@ThomasDickey. Całkowicie nie zgadzam się z tą oceną. Możliwość napisania narzędzia niekoniecznie wiąże się z możliwością wyjaśnienia interfejsu API użytkownikowi końcowemu. T
chiggsy
6

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:wprowadź opis zdjęcia tutaj

BandW2011
źródło