Эталонный пример документации для CLI утилиты

Маны, не?

Маны тоже довольно разные. И большинство из них вызывают тоску и желание загуглить конкретный ответ в интернете, а не читать эту портянку.

И большинство из них вызывают тоску и желание загуглить конкретный ответ в интернете, а не читать эту портянку.

Это потому, что сами утилиты перегружены флагами, подфлагами и всякими конвейерами

Какие доки у нас принято считать примером для подражания?

systemd

bash

find

остальные coreutils / util-linux (только надо смотреть, чтобы ман к конкретной утилите не был заглушкой по сравнению с info)

…которые при всем при этом не подвержены какому-то внятному сквозному именованию и для каждой утилиты изучение мана начинается по новой. А потом это великолепие грузит одно ядро и тормозит.

p.s. По сабжу: что понимается под «формальной» документацией? Что-то типа help’a, man’a, статьи? В общем случае открой любую рандомную статью на redhat access’e.

Лично мне нравится документация GNU Parallel, в основном, потому, что она есть на любой вкус. От целой книги (в которой можно искать по тексту) через man page (правда, длинную), в которой есть секция EXAMPLES, тоже очень информативная, до cheat sheet на одну страницу.

что понимается под «формальной» документацией? Что-то типа help’a, man’a, статьи?

Да, man/help. А то я как-то оглянулся и не вспомнил вообще никакой документации (к программам, для языков программирования бывает приятная), которой мне приятно было пользоваться.

… большинство из них вызывают тоску

Ну так сам можешь создать man-страницу. И выбросить что не нравится. В сети полно рецептов как это сделать

Ну так и ориентируйся на какой-нибудь годно заполненный Readme.md с гитхаба.

Вспомнил! grub4DOS

Ваш вопрос - очередной из серии «надо то, не знаю что». У вас есть начальство? У вас есть заказчик? Обычно либо те, либо другие имеют свои определенные требования и пожелания и гадать помимо них смысла никакого. Если же вы сотворили нечто исключительно свое - пишите что угодно, пользуясь здравым смыслом, когда будут вопросы - откорректируете. Все равно примеров для подражания быть не может, все очень сильно различается в зависимости от того, к чему дока.

Я еще понимаю, если бы вы хоть что-нибудь написали и тут попросили заценить и покритиковать

Открой для себя info, скажем того же make.

Говорят, маны в OpenBSD круче любой документации. Смотри их.

Поэтому в некоторых манах в конце есть раздел examples и иногда достаточно большой.

Присоединяюсь к вопросу. От себя могу вспомнить man-страницы MacOS, например tmutil(8).

man tldr

Почитай маны в опенбсд. Ничего лучше я ещё не видел.

Если вы опишите каждую CLI команду с примерами этого будет достаточно.

Количество таких манов исключающе мало.

Документация на OpenSIPs вполне достойная.

В некоторых. Большинство манов без примеров, что я считаю большим минусом.

Ну давайте маны превращать в howto и другие faq. Вам для чего примеры нужны?

Действительно, для чего могут быть нужны примеры использования? О, придумал: для использования!

Сферично.

man без примеров, всё равно что букварь без слов, а только с буквами.

Примеры нужны для примера.

Вы, видимо, из тех, кто учит языки программрования по их reference.

man без примеров, всё равно что букварь без слов, а только с буквами.

Хипстер детектед. Кстати стало интересно, вы в курсе что кроме манов существует другая документация?

Примеры нужны для примера.

И понимания глубины наших глубин.

Кстати стало интересно, вы в курсе что кроме манов существует другая документация?

А ты в курсе что man это сокращение от manual? Руководство. Не справочник, а руководство.
Если тебе удобней краткое описание параметров без объяснений, то придумай себе другое название. Руководством это называть нельзя.

https://ru.wikipedia.org/wiki/%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE_%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F

Видите, «сокращённое» вот и получайте сокращённый мануал

Ясно. В высшем учебном заведении дают высшее образование, а в ВУЗе – только диплом.

Забей. Он троллит.