Чому чоловічі сторінки не мають прикладів?


52

Чи є причина, чому більшість чоловічих сторінок не містять декількох поширених прикладів? Зазвичай вони пояснюють усі можливі варіанти, але це робить початківця ще складніше зрозуміти, як це "зазвичай" використовується.


1
Я здогадуюсь, що вони хотіли заощадити цінний простір на диску, як, наприклад, позбутися CR. Ср. Беккетт, Ватт , стор.8: "Багато цінного простору було врятовано [...], уникаючи плеторичного рефлексивного займенника після слова ".
Пітер - Відновіть Моніку

3
Один із спроб вирішити цю проблему - tldr-pages.github.io , хоча я не розумію, чому вони спрощують завантажувати все наперед для доступу в офлайн.
Натан Лонг

man jqмає понад 1000 рядків прикладів (на Ubuntu 16.04)
Motte001

Відповіді:


49

Це залежить від людини сторінок ... Традиційно, вони були включені в розділі з прикладами - але з якоїсь - то причини , що, як правило , відсутні в людино - сторінках під Linux (і я вважаю , інші з допомогою команд GNU - які більшість в ці дні). Що стосується Solaris, з іншого боку, майже кожна людина містить розділ Приклад, часто з кількома прикладами.

Якби я здогадувався, FSF / GNU вже давно не зважає на використання manсторінок і вважає за краще користувачів використовувати інформацію для документації. infoсторінки , як правило, більш всеосяжним , ніж людина сторінок, і , як правило , дійсно включають в себе приклади. infoсторінки також є більш "актуальними" - тобто пов'язані команди (наприклад, команди для пошуку файлів) часто можна зустріти разом.

Іншою причиною може бути те, що GNU та його manсторінки використовуються у багатьох різних операційних системах, які можуть відрізнятися одна від одної (адже між різними Linux-дистрибутивами існує багато відмінностей). Можливо, видання видав приклади, що стосуються конкретної ОС / дистрибутива - що, очевидно, робиться рідко.

Я також додам, що manсторінки ніколи не мали на меті "навчати початківців". UNIX був розроблений комп'ютерними експертами (старий термін "хакери") і призначений для використання комп'ютерними експертами. Сторінки "man" не були створені для навчання новачка, а для швидкої допомоги комп'ютерному експерту, який потребував нагадування про якусь незрозумілу опцію або дивний формат файлу - і це відображається в тому, як розділяється сторінка "man".

man-сторінки призначені як

  • Швидкий довідник для оновлення пам’яті; показує вам, як слід викликати команду, та перелічує доступні параметри.
  • Глибокий і ретельний - і, як правило, дуже технічний - опис усіх аспектів команди. Це написано комп'ютерними експертами, для колег-комп'ютерних експертів.
  • Список змінних середовища та файлів (тобто файлів конфігурації), що використовуються командою.
  • Посилання на іншу документацію (наприклад, книги) та інші manсторінки - наприклад. для формату файлів конфігурації та пов'язаних / подібних команд.

З цього manприводу я дуже згоден з вами, що сторінки повинні мати приклади, оскільки вони можуть пояснити використання краще, ніж переходити через саму сторінку. Занадто погані приклади, як правило, недоступні на manсторінках Linux ...

Зразок частини прикладу сторінки чоловіка Solaris - zfs (1M):

(...)
ПРИКЛАДИ
     Приклад 1 Створення ієрархії файлової системи ZFS

     Наступні команди створюють файлову систему з назвою pool / home
     і файлова система з назвою pool / home / bob. Точка кріплення
     / експорт / додому встановлено для батьківської файлової системи та є
     автоматично успадковується дочірньою файловою системою.

       # zfs створює пул / дім
       # zfs set mountpoint = / експорт / домашній пул / домашній
       # zfs створює пул / дім / bob

     Приклад 2 Створення знімка ZFS

     Наступна команда створює знімок, названий вчора.
     Цей знімок встановлюється на вимогу у .zfs / snapshot
     каталог у корені файлової системи pool / home / bob.

       # zfs Знімок пул / home / bob @ вчора

     Приклад 3 Створення та знищення декількох знімків

     Наступна команда створює знімки, названі вчора
     пул / дім та всі його спадкові файлові системи. Кожен
     Знімок встановлюється на вимогу в каталозі .zfs / snapshot
     в корені його файлової системи. Друга команда знищує
     новостворені знімки.

       # zfs знімок -r басейн / home @ вчора
       # zfs знищити -r басейн / home @ вчора

SunOS 5.11 Остання зміна: 23 липня 2012 року 51

Команди системного адміністрування zfs (1М)

     Приклад 4 Вимкнення та включення стиснення файлової системи

     Наступна команда відключає властивість стиснення для
(...)

Ця конкретна сторінка людини містить 16 (!) Таких прикладів ... Кудос Соляріс!
(І я визнаю, що я в основному дотримувався цих прикладів, замість того, щоб прочитати всю сторінку чоловіка для цієї команди ...)


2
Це останнє речення підкреслює проблему наявності прикладів у посібниках. Можна взяти приклади, які найкраще відповідають потребам, не розуміючи повністю конкретного застосування цього інструменту. І пізніше можна просто сказати «я зробив це так», але не дуже, чому або що це означало.
Кусалаланда

6
@Kusalananda В мій захист, я вже читав про різні варіанти і про суб-команд я на самому ділі необхідні - просто не всі це (поки). Це просто не підходить для мого використання ... Незважаючи на небезпеку зловживання, приклади дійсно мають на меті - і якщо все , що вам потрібно , це тільки найосновніше використання команди, читаючи про все дзвони і свистки навряд чи потрібні.
Баард Копперуд

@Kusalananda Це також може залежати від команд. Більшість утиліт Unix та GNU, які я знаю, добре задокументовані, але вам потрібна документація, щоб зробити щось розумне. Новіші команди Solaris (особливо zfs) розроблені досить природно. Наприклад, zfs destroy pool/filesystemце базове використання та штраф у 90% випадків використання. Короткі варіанти , як -rдля recursiveбільш особливими та потрібна консультація перед використанням, оскільки вони можуть мати небажані побічні ефекти.
користувач121391

26

Я не думаю, що на це є хороша відповідь. Це культурна річ. На деяких сторінках із використанням чоловіків є приклади використання. Напр man rsync. Ви можете спробувати змінити культуру, написавши автору сторінки чоловіка та попросивши його або її додати вибірки або (набагато краще) запропонувати приклади використання зразків самостійно. Якщо ви запропонуєте автору вільного програмного забезпечення патч, зокрема патч документації, це приблизно в десять тисяч разів більше шансів досягти бажаного результату, ніж простий запит.


7

Це залежить:

  • більшість програм, які вам будуть цікавими, розробляються протягом певного періоду, спочатку для вирішення проблеми, а пізніше для вдосконалення рішення. Розробники програм пояснюють те, що, на їхню думку, важливо знати (а документація - це не проблема, яку вони вирішували).
  • для деяких програм розробники вважають за краще надавати зразки програм або сценаріїв, які показують, як використовувати певну програму (або бібліотеку). Знову ж таки, це робиться для вирішення проблеми: полегшує тестування програми.

    Деякі приклади можуть базуватися на звітах про помилки користувачів, і коли короткий знайде місце в посібнику. Довгі приклади рідко подаються в посібниках, а короткі приклади мають проблему, що вони, як правило, тривіальні, повторювані та насправді не дають користувачеві стільки розуміння, як добре організованому опису роботи програми.

  • у деяких випадках ви знайдете документацію, яку надають інші, не залучені до процесу розробки. Тобто розробники не брали участі, окрім перегляду документації. Такі зусилля можна нехтувати.

5
"Такі зусилля можна нехтувати." Я не впевнений, що це означає.
Faheem Mitha

Документація не сприяє нічого корисного, якщо вона не ґрунтується на досвіді.
Томас Дікі

Насправді документація, що не ґрунтується на досвіді, може внести негативний внесок - тобто це просто неправильно.
alephzero

Звичайно - я згадував це, тому що деякі з прикладів, які ОП, безперечно, має на увазі, потрапляють до цієї категорії (я не буду подавати список на цьому форумі).
Томас Дікі

2
@ThomasDickey. Я повністю не згоден з цією оцінкою. Можливість писати утиліту не обов'язково має можливість пояснення API кінцевому користувачеві. T
chiggsy

6

Якщо ви шукаєте альтернативу доріжним сторінкам, ви завжди можете спробувати веб-сторінки , на яких відображаються лише різні приклади команди, за допомогою яких ви зможете проголосувати серед списку поданих спільнотою прикладів. Наприклад, команда bro tarдасть вам:введіть тут опис зображення

Використовуючи наш веб-сайт, ви визнаєте, що прочитали та зрозуміли наші Політику щодо файлів cookie та Політику конфіденційності.
Licensed under cc by-sa 3.0 with attribution required.