Почему на страницах man нет примеров?
awk '/#Name/{ x=$NF; }; /#End_of_file_header/,/EOD/{ print > x} ' test1
Если строка начинается с #name, x сохраните последнее слово строки.
Затем для всех блоков, разграничённых #End_of_file_header и EOD, я распечатаю строки в файл, имя которого является содержимым x
Этот пропустит заголовок файла, чтобы хранить данные только в файле.
Это зависит от страниц руководства ... Обычно они включают раздел с примерами, но по какой-то причине это обычно отсутствует на страницах руководства под Linux (и я предполагаю, что другие команды, использующие GNU, которые сейчас используются чаще всего). С другой стороны, в Solaris почти на каждой странице руководства есть раздел «Примеры», часто с несколькими примерами.
Если я догадываюсь, FSF / GNU долгое время не одобряли использование страниц man и предпочитали вместо этого использовать информацию для документации. info страницы имеют тенденцию быть более исчерпывающими, чем страницы руководства, и обычно действительно включают примеры. Страницы info также более «актуальны» - то есть связанные команды (например, команды для поиска файлов) часто можно найти вместе.
Другой причиной может быть то, что GNU и его man страницы используются во многих различных операционных системах, которые могут отличаться друг от друга (в конце концов, существует множество различий только между разными дистрибутивами Linux). Возможно, издатель имел намерение добавить примеры, относящиеся к конкретной ОС / дистрибутиву, что, очевидно, делается редко.
Я бы также добавил, что страницы man никогда не предназначались для «обучения новичков».UNIX был разработан компьютерными экспертами (старый термин «хакеры») и предназначен для использования компьютерными экспертами. Таким образом, справочные страницы создавались не для обучения новичков, а для быстрой помощи компьютерному эксперту, которому требовалось напоминание о какой-то непонятной опции или странном формате файла - и это отражается в том, как справочная страница разбита на разделы.
man -страницы, таким образом, предназначены как
- краткий справочник, чтобы освежить вашу память; показывает, как следует вызывать команду, и перечисляет доступные параметры.
- Глубокое и подробное - и обычно очень техническое - описание всех аспектов команды. Он написан компьютерными экспертами для других компьютерных экспертов.
- Список переменных и файлов среды (т. Е. Файлов конфигурации), используемых командой.
- Ссылки на другую документацию (например, книги) и другие
manстраницы - например. для формата файлов конфигурации и связанных / подобных команд.
Тем не менее, я полностью согласен с вами в том, что страницы man должны иметь примеры, поскольку они могут объяснить использование лучше, чем пролезать через саму страницу руководства. Слишком плохие примеры обычно недоступны в Linux man страницы ...
Пример части примера на странице руководства Solaris - zfs (1M):
(...)
EXAMPLES
Example 1 Creating a ZFS File System Hierarchy
The following commands create a filesystem named pool/home
and a filesystem named pool/home/bob. The mount point
/export/home is set for the parent filesystem, and is
automatically inherited by the child filesystem.
# zfs create pool/home
# zfs set mountpoint=/export/home pool/home
# zfs create pool/home/bob
Example 2 Creating a ZFS Snapshot
The following command creates a snapshot named yesterday.
This snapshot is mounted on demand in the .zfs/snapshot
directory at the root of the pool/home/bob file system.
# zfs snapshot pool/home/bob@yesterday
Example 3 Creating and Destroying Multiple Snapshots
The following command creates snapshots named yesterday of
pool/home and all of its descendent file systems. Each
snapshot is mounted on demand in the .zfs/snapshot directory
at the root of its file system. The second command destroys
the newly created snapshots.
# zfs snapshot -r pool/home@yesterday
# zfs destroy -r pool/home@yesterday
SunOS 5.11 Last change: 23 Jul 2012 51
System Administration Commands zfs(1M)
Example 4 Disabling and Enabling File System Compression
The following command disables the compression property for
(...)
Эта конкретная страница руководства содержит 16 (!) такие примеры ... Престижность Соляриса!
(Признаюсь, я сам в основном следовал этим примерам, вместо того, чтобы читать всю страницу руководства по этой команде ...)
Это зависит:
- большинство программ, которые могут вас заинтересовать, разрабатываются в течение определенного периода времени, сначала для решения проблемы, а затем для улучшения решения. Разработчики программ объясняют, что, по их мнению, важно знать (и документация не была проблемой, которую они решали).
для некоторых программ разработчики предпочитают предоставлять образцы программ или сценариев , которые показывают, как использовать данную программу (или библиотеку). Опять же, это сделано для решения проблемы: упрощения тестирования программы.
Некоторые примеры могут быть основаны на отчетах пользователей об ошибках, и когда short находит место в руководстве. В руководствах редко приводятся длинные примеры, а проблема коротких примеров состоит в том, что они обычно тривиальны, повторяются и на самом деле не дают пользователю столько понимания, сколько хорошо организованное описание того, как работает программа.
- в некоторых случаях вы найдете документацию, предоставленную другими , не участвующими в процессе разработки. То есть разработчики кроме ознакомления с документацией не участвовали. Такого рода усилия можно не принимать во внимание.
Если вы ищете альтернативу страницам руководства, вы всегда можете попробовать bro pages , которые показывают только различные примеры для команды, за которую вы затем можете проголосовать из списка представленных сообществом Примеры. Например, команда bro tar даст вам: 
Я не думаю, что на это есть хороший ответ. Это вопрос культуры. На некоторых man-страницах есть примеры использования. Например, man rsync. Вы можете попытаться изменить культуру, написав автору man-страницы и попросив его или ее добавить примеры использования или (что гораздо лучше) предложив примеры использования самостоятельно. Если вы предложите автору свободных программ заплату, особенно заплату для документации, вероятность достижения желаемого результата будет примерно в десять тысяч раз выше, чем при простой просьбе.