LXF76:Hardcore Linux2
Yaleks (обсуждение | вклад) (Новая: == Groff Создаем man-страницы == : ''Стоит вам закопаться в Linux поглубже, как вы принимаетесь чудить: например,...) |
Yaleks (обсуждение | вклад) м (викификация) |
||
| Строка 2: | Строка 2: | ||
: ''Стоит вам закопаться в Linux поглубже, как вы принимаетесь чудить: например, писать документацию для проектов с открытым исходным кодом. В этом нет ничего зазорного; '''Пол Хадсон''' очень одобряет такое занятие.'' | : ''Стоит вам закопаться в Linux поглубже, как вы принимаетесь чудить: например, писать документацию для проектов с открытым исходным кодом. В этом нет ничего зазорного; '''Пол Хадсон''' очень одобряет такое занятие.'' | ||
| − | + | Документация — вещь важная. Фактически, вся моя работа | |
посвящена документации и постоянной ее нехватке. | посвящена документации и постоянной ее нехватке. | ||
| − | + | LinuxFormat — тоже вид документации, разбавленный обзорами программного обеспечения и мнениями авторов. Даже бизнес-модель Тима О’Рейли, главы известного в компьютерных кругах | |
издательства O’Reilly, построена на том простом принципе, что документация, поставляемая с компьютерными продуктами, недостаточно | издательства O’Reilly, построена на том простом принципе, что документация, поставляемая с компьютерными продуктами, недостаточно | ||
хороша. | хороша. | ||
| Строка 10: | Строка 10: | ||
Тим в чем-то прав, ведь программисты ненавидят писать документацию. Некоторые даже не вставляют комментарии в свои исходные тексты, потому как выкатить недоступный пониманию код на | Тим в чем-то прав, ведь программисты ненавидят писать документацию. Некоторые даже не вставляют комментарии в свои исходные тексты, потому как выкатить недоступный пониманию код на | ||
малораспространенном языке программирования времен золотого | малораспространенном языке программирования времен золотого | ||
| − | детства Дональда | + | детства Дональда Кнута — разве не весело? Миру коммерческого |
программного обеспечения это жить не мешает: фирмы просто нанимают людей специально для написания документации, оставляя программистам то, что у них получается лучше всего (нет, не чтение | программного обеспечения это жить не мешает: фирмы просто нанимают людей специально для написания документации, оставляя программистам то, что у них получается лучше всего (нет, не чтение | ||
ЛОРа и Slashdot’а, а программирование, конечно). | ЛОРа и Slashdot’а, а программирование, конечно). | ||
Если вы читаете данные строки, значит, вы принадлежите к одному из двух типов людей. Первый тип называется «Программировать | Если вы читаете данные строки, значит, вы принадлежите к одному из двух типов людей. Первый тип называется «Программировать | ||
| − | Не Умею, Но Хочу Чем-нибудь Помочь» (ПНУНХЧП), | + | Не Умею, Но Хочу Чем-нибудь Помочь» (ПНУНХЧП), второй — «Умею |
Программировать, Но Хочу Выпендриваться» (УПНХВ). | Программировать, Но Хочу Выпендриваться» (УПНХВ). | ||
| Строка 26: | Строка 26: | ||
из них, то добро пожаловать! Можете примкнуть к проекту «Missing | из них, то добро пожаловать! Можете примкнуть к проекту «Missing | ||
Man Pages Project» (http://www.netmeister.org/misc/m2p2) [русско-язычным пользователям рекомендуется присоединиться к проекту | Man Pages Project» (http://www.netmeister.org/misc/m2p2) [русско-язычным пользователям рекомендуется присоединиться к проекту | ||
| − | по переводу man-страниц на русский | + | по переводу man-страниц на русский язык — http://alexm.here.ru/manpages-ru/]. |
=== Man-страницы всех времен и народов === | === Man-страницы всех времен и народов === | ||
| Строка 32: | Строка 32: | ||
против течения. Они действительно умеют программировать и даже | против течения. Они действительно умеют программировать и даже | ||
любят писать о своих программах. Это люди опасны. Например, если | любят писать о своих программах. Это люди опасны. Например, если | ||
| − | вы подумываете: «А не завести ли мне собственный open source-проект? Напишу программу не хуже, чем XYZ, да еще приложу кучу документации, и любой новичок в ней сразу | + | вы подумываете: «А не завести ли мне собственный open source-проект? Напишу программу не хуже, чем XYZ, да еще приложу кучу документации, и любой новичок в ней сразу разберется» — тогда, пожалуйста, дальше не читайте, плодить бессмысленные варианты я не намерен. Да, ваш выбор хорош, но лучше бы вы употребили свой писательский зуд на помощь в разработке документации к готовым проектам. |
| − | Если же вы и вправду решили помочь сообществу с документацией, будьте как | + | Если же вы и вправду решили помочь сообществу с документацией, будьте как дома — это руководство для вас. |
=== План === | === План === | ||
| Строка 75: | Строка 75: | ||
Одни пытаются превратить свинец в золото. Другие ищут Святой | Одни пытаются превратить свинец в золото. Другие ищут Святой | ||
Грааль. Мы же озадачимся гибридом этих двух занятий: создадим | Грааль. Мы же озадачимся гибридом этих двух занятий: создадим | ||
| − | man-страницу для классической компьютерной | + | man-страницу для классической компьютерной игры — Qaziqargs Of |
Qargg [исковерканное название «Волшебник страны Оз»]. Скорее | Qargg [исковерканное название «Волшебник страны Оз»]. Скорее | ||
всего эта игрушка у вас не установлена, да и в Google вряд ли найдется информация о ней. Но это не проблема, про все ключи ее | всего эта игрушка у вас не установлена, да и в Google вряд ли найдется информация о ней. Но это не проблема, про все ключи ее | ||
командной строки я вам расскажу. | командной строки я вам расскажу. | ||
| − | Мы не собираемся работать с TeX, HTML, XML или | + | Мы не собираемся работать с TeX, HTML, XML или SGML — данное |
руководство посвящено man-страницам, и не будем отклоняться от темы. | руководство посвящено man-страницам, и не будем отклоняться от темы. | ||
| Строка 92: | Строка 92: | ||
экзотический текстовый формат, намного более древний, чем HTML | экзотический текстовый формат, намного более древний, чем HTML | ||
(бытует мнение, что Unix был придуман потому, что типографиям | (бытует мнение, что Unix был придуман потому, что типографиям | ||
| − | требовалась система для работы с groff, | + | требовалась система для работы с groff, — прим.ред.). На вид он старомоден, имеет странный синтаксис, злоупотребляет препроцессором… короче, он совершенно ужасен, но, надеюсь, вместе мы |
сквозь него продеремся. | сквозь него продеремся. | ||
=== Гроффмейстер === | === Гроффмейстер === | ||
| − | + | groff — это последняя модификация программы, ранее называвшейся | |
ronoff (в которой были доступны лишь базовые средства форматирования). Затем был nroff (новый roff), потом troff, и наконец ditroff (устройство-независимый troff). С 1991-го года GNU-реализация ditroff | ronoff (в которой были доступны лишь базовые средства форматирования). Затем был nroff (новый roff), потом troff, и наконец ditroff (устройство-независимый troff). С 1991-го года GNU-реализация ditroff | ||
стала стабильной и получила название groff. | стала стабильной и получила название groff. | ||
| − | Такова семейная сага groff. Ее можно и не знать; | + | Такова семейная сага groff. Ее можно и не знать; главное — помнить, |
что man-страницы пишутся в формате groff, который преобразовывается на лету для отображения на терминале. Полученные читабельные | что man-страницы пишутся в формате groff, который преобразовывается на лету для отображения на терминале. Полученные читабельные | ||
страницы автоматически кэшируются в расчете на дальнейшее использование. Но мы-то будем иметь дело с внутренним форматом. | страницы автоматически кэшируются в расчете на дальнейшее использование. Но мы-то будем иметь дело с внутренним форматом. | ||
| Строка 116: | Строка 116: | ||
# Описание X-Window | # Описание X-Window | ||
Есть еще несколько разделов, но они уже устарели и вряд ли вам | Есть еще несколько разделов, но они уже устарели и вряд ли вам | ||
| − | понадобятся. Полезно было бы запомнить эти номера, чтобы понимать различия между man 1 passwd и man 5 passwd. Первая загружает справку о команде passwd, а | + | понадобятся. Полезно было бы запомнить эти номера, чтобы понимать различия между man 1 passwd и man 5 passwd. Первая загружает справку о команде passwd, а вторая — информацию о формате |
файла /etc/passwd. | файла /etc/passwd. | ||
Все man-страницы в директории /usr/share/man отсортированы | Все man-страницы в директории /usr/share/man отсортированы | ||
по категориям: например, справка о команде passwd находится в | по категориям: например, справка о команде passwd находится в | ||
| − | файле /usr/share/man/man1/passwd.1.gz, а информация о /etc/ | + | файле /usr/share/man/man1/passwd.1.gz, а информация о /etc/passwd — в /usr/share/man/man5/passwd.5.gz. Теперь давайте |
посмотрим, на что похожа man-страница изнутри: zcat /usr/share/man/man5/passwd.5.gz. Да перестаньте брызгать слюной, скоро | посмотрим, на что похожа man-страница изнутри: zcat /usr/share/man/man5/passwd.5.gz. Да перестаньте брызгать слюной, скоро | ||
вы все поймете. | вы все поймете. | ||
=== Простейшая man-страница === | === Простейшая man-страница === | ||
| − | [[Изображение:Img 76 106 1.png|thumb|groff: до | + | [[Изображение:Img 76 106 1.png|thumb|groff: до …]] |
| − | [[Изображение:Img 76 106 2.png|thumb| | + | [[Изображение:Img 76 106 2.png|thumb|…и после. Как говорится, почувствуйте разницу!]] |
| − | Мы здесь не на почасовой | + | Мы здесь не на почасовой оплате — не будем тянуть время, запустим |
| − | Emacs. Скорейший способ изучить | + | Emacs. Скорейший способ изучить groff — использовать ту же тактику, |
что и при изучении HTML: хотя макросов устрашающе много, большинство из них, вероятнее всего, вам не понадобится. | что и при изучении HTML: хотя макросов устрашающе много, большинство из них, вероятнее всего, вам не понадобится. | ||
Вот наша первая попытка создать man-страницу; сохраните ее | Вот наша первая попытка создать man-страницу; сохраните ее | ||
| − | файл под именем qaziqargs.6.1 (в данном случае . | + | файл под именем qaziqargs.6.1 (в данном случае .1 — это номер |
версии вашей страницы): | версии вашей страницы): | ||
<source lang="text">.TH QAZIQARGS 1 «February 2006» «qaziqargs-1.0.556» «Qaziqargs of Qargg!» | <source lang="text">.TH QAZIQARGS 1 «February 2006» «qaziqargs-1.0.556» «Qaziqargs of Qargg!» | ||
| Строка 171: | Строка 171: | ||
колонтитула; текст, отображаемый слева от нижнего колонтитула и | колонтитула; текст, отображаемый слева от нижнего колонтитула и | ||
текст, отображаемый в центре заголовка. Здесь они заданы так: текст | текст, отображаемый в центре заголовка. Здесь они заданы так: текст | ||
| − | в середине нижнего | + | в середине нижнего колонтитула — это дата последнего обновления |
| − | документации, | + | документации, слева — номер версии, а текст в середине заголовка - |
название программы (это не имя исполняемого файла). Если в параметре содержится пробел, такой параметр нужно заключить в двойные кавычки. | название программы (это не имя исполняемого файла). Если в параметре содержится пробел, такой параметр нужно заключить в двойные кавычки. | ||
| − | Стандартный макрос .SH отвечает за заголовок секции. Во-первых, заголовок должен быть написан заглавными | + | Стандартный макрос .SH отвечает за заголовок секции. Во-первых, заголовок должен быть написан заглавными буквами — ИМЯ, |
| − | СИНТА КСИС, ОПИСАНИЕ, | + | СИНТА КСИС, ОПИСАНИЕ, и т. д. Во-вторых, вы обязаны включать в |
свои man-страницы секцию NAME (ИМЯ) программы и ее краткое | свои man-страницы секцию NAME (ИМЯ) программы и ее краткое | ||
(желательно однострочное) описание. Эта секция используется утилитами whatis и apropos (их тоже надо знать). | (желательно однострочное) описание. Эта секция используется утилитами whatis и apropos (их тоже надо знать). | ||
В man-страницы также входят секции: | В man-страницы также входят секции: | ||
| − | * AVAILABILITY (ДОСТУПНОСТЬ ) | + | * AVAILABILITY (ДОСТУПНОСТЬ) — ваша программа совместима только с Linux и FreeBSD или работает на всех Unix-системах? |
| − | * EXAMPLES (ПРИМЕРЫ) | + | * EXAMPLES (ПРИМЕРЫ) — примеры использования вашей программы |
| − | * HISTORY (ИСТОРИЯ) | + | * HISTORY (ИСТОРИЯ) — включайте, если только она интересна или важна |
| − | * FILES (ФАЙЛЫ) | + | * FILES (ФАЙЛЫ) — какие файлы (и директории) использует ваша программа |
| − | * BUGS (ОШИБКИ ) | + | * BUGS (ОШИБКИ) — опишите известные вам грешки, чтобы люди зря не рвали на себе волосы |
| − | * CAVEATS (ОСОБЕННОСТИ) | + | * CAVEATS (ОСОБЕННОСТИ) — многие могут принять их за ошибки, но на самом деле все так и задумано |
| − | * SEE ALSO ( СМ. ТА КЖЕ ) | + | * SEE ALSO (СМ. ТА КЖЕ) — список man-страниц, которые могут помочь при чтении вашей документации |
Макросы .B и .I преобразуют шрифт текста, следующий за ними, | Макросы .B и .I преобразуют шрифт текста, следующий за ними, | ||
в полужирный и курсив соответственно, однако на большинстве терминалов курсив отображается как подчеркивание. .B используется в | в полужирный и курсив соответственно, однако на большинстве терминалов курсив отображается как подчеркивание. .B используется в | ||
| − | man-страницах для именованных параметров (например, -x или --help), а . | + | man-страницах для именованных параметров (например, -x или --help), а .I — для задаваемых пользователем (допустим, имен файлов). В приведенном коде присутствуют оба варианта. |
Макрос .TP означает «термин/параграф» и используется для | Макрос .TP означает «термин/параграф» и используется для | ||
| Строка 205: | Строка 205: | ||
Теперь посмотрим, что у нас получилось. Выполните команду | Теперь посмотрим, что у нас получилось. Выполните команду | ||
| − | man -l qaziqargs.6.1 ( | + | man -l qaziqargs.6.1 (посередке — это строчное L). Ну что, ощущаете законную гордость? Или, наоборот, раздосадованы, что гора |
родила мышь? Ответ пришлите открыткой. | родила мышь? Ответ пришлите открыткой. | ||
| Строка 224: | Строка 224: | ||
|Ширина=400px}} | |Ширина=400px}} | ||
Вы наверняка подумали «Хм, при написании man-страниц придется | Вы наверняка подумали «Хм, при написании man-страниц придется | ||
| − | соблюдать больше правил, чем при вождении машины». Честно говоря, вы правы, и мой | + | соблюдать больше правил, чем при вождении машины». Честно говоря, вы правы, и мой ответ — «не нравится, не ешь». Если вы не уважаете правил, значит, создание man-страниц не для вас. Правила |
обеспечивают унификацию документации и отлично работают вот уже | обеспечивают унификацию документации и отлично работают вот уже | ||
два десятилетия. | два десятилетия. | ||
| Строка 230: | Строка 230: | ||
Прежде чем умчаться готовить свои man-страницы, разберитесь | Прежде чем умчаться готовить свои man-страницы, разберитесь | ||
еще с двумя специфическими макросами. Специфика их в том, что | еще с двумя специфическими макросами. Специфика их в том, что | ||
| − | они не занимаются форматированием. | + | они не занимаются форматированием. Первый — .\", означающий |
начало комментария. Комментарии в groff имеют такой же смысл, как | начало комментария. Комментарии в groff имеют такой же смысл, как | ||
в С или LaTeX: groff их игнорирует. | в С или LaTeX: groff их игнорирует. | ||
| − | Включение комментариев в groff- | + | Включение комментариев в groff-исходник — весьма тонкий ход, |
он позволяет отклонить пользовательские громы и молнии в пустоту: | он позволяет отклонить пользовательские громы и молнии в пустоту: | ||
чистосердечно сознайтесь в своих ошибках, и вас никто не обидит. | чистосердечно сознайтесь в своих ошибках, и вас никто не обидит. | ||
Например: | Например: | ||
.\» Не уверен, что эта штука --baz вообще заработает. | .\» Не уверен, что эта штука --baz вообще заработает. | ||
| − | Второй | + | Второй макрос — .so (строчными буквами). Это способ перебросить groff на другой файл, аналогично HTTP-перенаправлению. |
Например, команда qaziqargs имеет параметр --create-server, а у | Например, команда qaziqargs имеет параметр --create-server, а у | ||
вас есть скрипт qaziqargs-create-server, который как раз вызывает | вас есть скрипт qaziqargs-create-server, который как раз вызывает | ||
| Строка 246: | Строка 246: | ||
Вам, естественно, неохота держать две man-страницы для этих | Вам, естественно, неохота держать две man-страницы для этих | ||
| − | + | команд — лучше обойтись ссылкой. Создайте основную страницу | |
qaziqargs.6, а в странице qaziqargs-create-server.6 пропишите | qaziqargs.6, а в странице qaziqargs-create-server.6 пропишите | ||
всего одну строку: | всего одну строку: | ||
| Строка 254: | Строка 254: | ||
Сам я предпочитаю хранить man-страницы внутри домашнего | Сам я предпочитаю хранить man-страницы внутри домашнего | ||
| − | каталога, пока вожусь с отладкой, а для их загрузки набираю команду man | + | каталога, пока вожусь с отладкой, а для их загрузки набираю команду man -l. Как только качество страницы меня удовлетворяет, я сжимаю ее при помощи gzip (и вам советую), а потом уж устанавливаю в |
/usr/share/man. | /usr/share/man. | ||
| Строка 260: | Строка 260: | ||
код невелик, он иллюстрирует все необходимые макросы, с которыми man-страницы писать легко. | код невелик, он иллюстрирует все необходимые макросы, с которыми man-страницы писать легко. | ||
| − | Конечно, создание документации предполагает не только написание man- | + | Конечно, создание документации предполагает не только написание man-страниц — есть множество других форматов, например, info, |
со своими собственными правилами. Однако man-страницы являются в | со своими собственными правилами. Однако man-страницы являются в | ||
| − | Linux стандартом де-факто, а в некоторых дистрибутивах, скажем, Arch Linux и Crux, вся прочая документация из пакетов специально удаляется. Итак, за | + | Linux стандартом де-факто, а в некоторых дистрибутивах, скажем, Arch Linux и Crux, вся прочая документация из пакетов специально удаляется. Итак, за дело — документации никогда не бывает много. |
{{Врезка|center| | {{Врезка|center| | ||
Текущая версия на 16:29, 1 февраля 2009
|
|
|
Содержание |
[править] Groff Создаем man-страницы
- Стоит вам закопаться в Linux поглубже, как вы принимаетесь чудить: например, писать документацию для проектов с открытым исходным кодом. В этом нет ничего зазорного; Пол Хадсон очень одобряет такое занятие.
Документация — вещь важная. Фактически, вся моя работа посвящена документации и постоянной ее нехватке. LinuxFormat — тоже вид документации, разбавленный обзорами программного обеспечения и мнениями авторов. Даже бизнес-модель Тима О’Рейли, главы известного в компьютерных кругах издательства O’Reilly, построена на том простом принципе, что документация, поставляемая с компьютерными продуктами, недостаточно хороша.
Тим в чем-то прав, ведь программисты ненавидят писать документацию. Некоторые даже не вставляют комментарии в свои исходные тексты, потому как выкатить недоступный пониманию код на малораспространенном языке программирования времен золотого детства Дональда Кнута — разве не весело? Миру коммерческого программного обеспечения это жить не мешает: фирмы просто нанимают людей специально для написания документации, оставляя программистам то, что у них получается лучше всего (нет, не чтение ЛОРа и Slashdot’а, а программирование, конечно).
Если вы читаете данные строки, значит, вы принадлежите к одному из двух типов людей. Первый тип называется «Программировать Не Умею, Но Хочу Чем-нибудь Помочь» (ПНУНХЧП), второй — «Умею Программировать, Но Хочу Выпендриваться» (УПНХВ).
Тип ПНУНХЧП сейчас составляет большую часть сообщества Open Source. Еще несколько лет назад соотношение программистов и пользователей в Linux было гораздо больше в пользу первых. Кое-кто даже любил сравнивать его с отношением сигнал/шум (пользователи, разумеется, считались «шумом»). Программы разрабатывались быстро, ошибки отлавливались сразу, жалобами практически не донимали. Теперь же на Linux работают и те, кто не умеет писать коды. Эти люди могут помочь созданием графики, содействием новичкам и, конечно же, разработкой документации. Если вы один из них, то добро пожаловать! Можете примкнуть к проекту «Missing Man Pages Project» (http://www.netmeister.org/misc/m2p2) [русско-язычным пользователям рекомендуется присоединиться к проекту по переводу man-страниц на русский язык — http://alexm.here.ru/manpages-ru/].
[править] Man-страницы всех времен и народов
С другой стороны, мы имеем лиц типа УПНХВ, которые желают плыть против течения. Они действительно умеют программировать и даже любят писать о своих программах. Это люди опасны. Например, если вы подумываете: «А не завести ли мне собственный open source-проект? Напишу программу не хуже, чем XYZ, да еще приложу кучу документации, и любой новичок в ней сразу разберется» — тогда, пожалуйста, дальше не читайте, плодить бессмысленные варианты я не намерен. Да, ваш выбор хорош, но лучше бы вы употребили свой писательский зуд на помощь в разработке документации к готовым проектам.
Если же вы и вправду решили помочь сообществу с документацией, будьте как дома — это руководство для вас.
[править] План
- Метамодернизм в позднем творчестве В.Г. Сорокина
- ЛитРПГ - последняя отрыжка постмодерна
- "Ричард III и семиотика"
- 3D-визуализация обложки Ridero создаем обложку книги при работе над самиздатом.
- Архитектура метамодерна - говоря о современном искусстве, невозможно не поговорить об архитектуре. В данной статье будет отмечено несколько интересных принципов, характерных для построек "новой волны", столь притягательных и скандальных.
- Литература
- Метамодерн
- Рокер-Прометей против изначального зла в «Песне про советскую милицию» Вени Дркина, Автор: Нина Ищенко, к.ф.н, член Союза Писателей ЛНР - перепубликация из журнала "Топос".
- Как избавиться от комаров? Лучшие типы ловушек.
- Что делать если роблокс вылетает на windows
- Что делать, если ребенок смотрит порно?
- Почему собака прыгает на людей при встрече?
- Какое масло лить в Задний дифференциал (мост) Visco diff 38434AA050
- О чем может рассказать хвост вашей кошки?
- Верветки
- Отчетность бюджетных учреждений при закупках по Закону № 223-ФЗ
- Срок исковой давности как правильно рассчитать
- Дмитрий Патрушев минсельхоз будет ли преемником Путина
- Кто такой Владислав Поздняков? Что такое "Мужское Государство" и почему его признали экстремистским в России?
- Как правильно выбрать машинное масло в Димитровграде?
- Как стать богатым и знаменитым в России?
- Почему фильм "Пипец" (Kick-Ass) стал популярен по всему миру?
- Как стать мудрецом?
- Как правильно установить FreeBSD
- Как стать таким как Путин?
- Где лучше жить - в Димитровграде или в Ульяновске?
- Почему город Димитровград так называется?
- Что такое метамодерн?
- ВАЖНО! Временное ограничение движения автотранспортных средств в Димитровграде
- Тарифы на электроэнергию для майнеров предложено повысить
Одни пытаются превратить свинец в золото. Другие ищут Святой Грааль. Мы же озадачимся гибридом этих двух занятий: создадим man-страницу для классической компьютерной игры — Qaziqargs Of Qargg [исковерканное название «Волшебник страны Оз»]. Скорее всего эта игрушка у вас не установлена, да и в Google вряд ли найдется информация о ней. Но это не проблема, про все ключи ее командной строки я вам расскажу.
Мы не собираемся работать с TeX, HTML, XML или SGML — данное руководство посвящено man-страницам, и не будем отклоняться от темы.
Для создания man-страницы вам понадобится: Linux (да, а что?!),
утилиты man и groff и немного терпения. Скорее всего, три компонента у вас уже есть:
а) в руках вы держите LinuxFormat;
б) без команды man не обходится ни один дистрибутив;
в) а если работает man, значит, groff тоже установлен.
Не хватить может только терпения, поскольку groff использует экзотический текстовый формат, намного более древний, чем HTML (бытует мнение, что Unix был придуман потому, что типографиям требовалась система для работы с groff, — прим.ред.). На вид он старомоден, имеет странный синтаксис, злоупотребляет препроцессором… короче, он совершенно ужасен, но, надеюсь, вместе мы сквозь него продеремся.
[править] Гроффмейстер
groff — это последняя модификация программы, ранее называвшейся ronoff (в которой были доступны лишь базовые средства форматирования). Затем был nroff (новый roff), потом troff, и наконец ditroff (устройство-независимый troff). С 1991-го года GNU-реализация ditroff стала стабильной и получила название groff.
Такова семейная сага groff. Ее можно и не знать; главное — помнить, что man-страницы пишутся в формате groff, который преобразовывается на лету для отображения на терминале. Полученные читабельные страницы автоматически кэшируются в расчете на дальнейшее использование. Но мы-то будем иметь дело с внутренним форматом.
Man-страницы в Linux хранятся в виде groff-файлов, ради экономии места сжатых архиватором gzip. Например, в SUSE их директория /usr/share/man. Естественно, все они рассортированы по языкам и разделам. Нумерация разделов может показаться немного нелогичной:
- Команды, доступные пользователю
- Системные вызовы ядра
- Библиотечные функции
- Файлы устройств и сетевые интерфейсы в /dev
- Форматы файлов и их описания
- Игры
- Макросы, окружения и другие куски информации
- Команды системного администрирования для использования пользователем root
- Описание X-Window
Есть еще несколько разделов, но они уже устарели и вряд ли вам понадобятся. Полезно было бы запомнить эти номера, чтобы понимать различия между man 1 passwd и man 5 passwd. Первая загружает справку о команде passwd, а вторая — информацию о формате файла /etc/passwd.
Все man-страницы в директории /usr/share/man отсортированы по категориям: например, справка о команде passwd находится в файле /usr/share/man/man1/passwd.1.gz, а информация о /etc/passwd — в /usr/share/man/man5/passwd.5.gz. Теперь давайте посмотрим, на что похожа man-страница изнутри: zcat /usr/share/man/man5/passwd.5.gz. Да перестаньте брызгать слюной, скоро вы все поймете.
[править] Простейшая man-страница
Мы здесь не на почасовой оплате — не будем тянуть время, запустим Emacs. Скорейший способ изучить groff — использовать ту же тактику, что и при изучении HTML: хотя макросов устрашающе много, большинство из них, вероятнее всего, вам не понадобится.
Вот наша первая попытка создать man-страницу; сохраните ее файл под именем qaziqargs.6.1 (в данном случае .1 — это номер версии вашей страницы):
.TH QAZIQARGS 1 «February 2006» «qaziqargs-1.0.556» «Qaziqargs of Qargg!» .SH ИМЯ qaziqargs – запустить игру Qaziqargs of Qargg .SH КРАТ КОЕ СОДЕР ЖАНИЕ .B qaziqargs [ .B –cheat .I mode ] .I savegame .SH ОПИСАНИЕ Qaziqarggs of Qargg – ролевая игра для больших кровожадных детишек. .SH ОПЦИИ .TP .B --cheat Здесь включается режим Бога: .I режим может быть равен 1 для неисчерпаемых боеприпасов, 2 для бессмертия или 3 для полного беспредела. .TP .I сохраненная_игра Загрузка сохраненной игры из директории .I $HOME/.qaziqargs .SH АВТ ОР Лестное для вас фото / имя (Вася Пингвинов, например)
Здесь около 25 строк кода, man-страница и не должна быть больше, чтобы помещаться на экране. Есть несколько способов написания groff-файлов, и мы выбрали простейший: каждый макрос («тэг») действует на текст, который следует за ним, закрывать макросы не требуется. В данном куске кода мы использовали всего пять разных макросов: .TH, .SH, .B, .I и .TP. Макросов, конечно, намного больше, однако для создания man-страниц этих хватит.
Макрос .TH задает заголовок страницы. Как и во многих других макросах, вы можете задавать параметры, разделяя их пробелами. У .TH параметры специфические: название исполняемого файла программы; раздел man; текст, отображаемый в середине нижнего колонтитула; текст, отображаемый слева от нижнего колонтитула и текст, отображаемый в центре заголовка. Здесь они заданы так: текст в середине нижнего колонтитула — это дата последнего обновления документации, слева — номер версии, а текст в середине заголовка - название программы (это не имя исполняемого файла). Если в параметре содержится пробел, такой параметр нужно заключить в двойные кавычки.
Стандартный макрос .SH отвечает за заголовок секции. Во-первых, заголовок должен быть написан заглавными буквами — ИМЯ, СИНТА КСИС, ОПИСАНИЕ, и т. д. Во-вторых, вы обязаны включать в свои man-страницы секцию NAME (ИМЯ) программы и ее краткое (желательно однострочное) описание. Эта секция используется утилитами whatis и apropos (их тоже надо знать).
В man-страницы также входят секции:
- AVAILABILITY (ДОСТУПНОСТЬ) — ваша программа совместима только с Linux и FreeBSD или работает на всех Unix-системах?
- EXAMPLES (ПРИМЕРЫ) — примеры использования вашей программы
- HISTORY (ИСТОРИЯ) — включайте, если только она интересна или важна
- FILES (ФАЙЛЫ) — какие файлы (и директории) использует ваша программа
- BUGS (ОШИБКИ) — опишите известные вам грешки, чтобы люди зря не рвали на себе волосы
- CAVEATS (ОСОБЕННОСТИ) — многие могут принять их за ошибки, но на самом деле все так и задумано
- SEE ALSO (СМ. ТА КЖЕ) — список man-страниц, которые могут помочь при чтении вашей документации
Макросы .B и .I преобразуют шрифт текста, следующий за ними, в полужирный и курсив соответственно, однако на большинстве терминалов курсив отображается как подчеркивание. .B используется в man-страницах для именованных параметров (например, -x или --help), а .I — для задаваемых пользователем (допустим, имен файлов). В приведенном коде присутствуют оба варианта.
Макрос .TP означает «термин/параграф» и используется для описания опций: в первой строке находится имя опции (.B --cheat), а далее идет ее объяснение.
Тут срабатывает автоматика: если термин (название) короче, чем отступ по умолчанию, то объяснение начнется на той же строке, где и термин. Ширина левого отступа по умолчанию равна семи символам (обратите внимание, что этот отступ действует для всего текста, не входящего в заголовок). Вы можете задать отступ .TP с помощью числового параметра. Например, .TP 0 сотрет грань между параграфом и всем остальным текстом. Одинаковый для всех отступ задается один раз (в первом из .TP), он автоматически распространится на последующие строки.
Теперь посмотрим, что у нас получилось. Выполните команду man -l qaziqargs.6.1 (посередке — это строчное L). Ну что, ощущаете законную гордость? Или, наоборот, раздосадованы, что гора родила мышь? Ответ пришлите открыткой.
[править] Делайте больше!
- Метамодернизм в позднем творчестве В.Г. Сорокина
- ЛитРПГ - последняя отрыжка постмодерна
- "Ричард III и семиотика"
- 3D-визуализация обложки Ridero создаем обложку книги при работе над самиздатом.
- Архитектура метамодерна - говоря о современном искусстве, невозможно не поговорить об архитектуре. В данной статье будет отмечено несколько интересных принципов, характерных для построек "новой волны", столь притягательных и скандальных.
- Литература
- Метамодерн
- Рокер-Прометей против изначального зла в «Песне про советскую милицию» Вени Дркина, Автор: Нина Ищенко, к.ф.н, член Союза Писателей ЛНР - перепубликация из журнала "Топос".
- Как избавиться от комаров? Лучшие типы ловушек.
- Что делать если роблокс вылетает на windows
- Что делать, если ребенок смотрит порно?
- Почему собака прыгает на людей при встрече?
- Какое масло лить в Задний дифференциал (мост) Visco diff 38434AA050
- О чем может рассказать хвост вашей кошки?
- Верветки
- Отчетность бюджетных учреждений при закупках по Закону № 223-ФЗ
- Срок исковой давности как правильно рассчитать
- Дмитрий Патрушев минсельхоз будет ли преемником Путина
- Кто такой Владислав Поздняков? Что такое "Мужское Государство" и почему его признали экстремистским в России?
- Как правильно выбрать машинное масло в Димитровграде?
- Как стать богатым и знаменитым в России?
- Почему фильм "Пипец" (Kick-Ass) стал популярен по всему миру?
- Как стать мудрецом?
- Как правильно установить FreeBSD
- Как стать таким как Путин?
- Где лучше жить - в Димитровграде или в Ульяновске?
- Почему город Димитровград так называется?
- Что такое метамодерн?
- ВАЖНО! Временное ограничение движения автотранспортных средств в Димитровграде
- Тарифы на электроэнергию для майнеров предложено повысить
Вы наверняка подумали «Хм, при написании man-страниц придется соблюдать больше правил, чем при вождении машины». Честно говоря, вы правы, и мой ответ — «не нравится, не ешь». Если вы не уважаете правил, значит, создание man-страниц не для вас. Правила обеспечивают унификацию документации и отлично работают вот уже два десятилетия.
Прежде чем умчаться готовить свои man-страницы, разберитесь еще с двумя специфическими макросами. Специфика их в том, что они не занимаются форматированием. Первый — .\", означающий начало комментария. Комментарии в groff имеют такой же смысл, как в С или LaTeX: groff их игнорирует.
Включение комментариев в groff-исходник — весьма тонкий ход, он позволяет отклонить пользовательские громы и молнии в пустоту: чистосердечно сознайтесь в своих ошибках, и вас никто не обидит. Например:
.\» Не уверен, что эта штука --baz вообще заработает.
Второй макрос — .so (строчными буквами). Это способ перебросить groff на другой файл, аналогично HTTP-перенаправлению. Например, команда qaziqargs имеет параметр --create-server, а у вас есть скрипт qaziqargs-create-server, который как раз вызывает qaziqargs с нужным параметром --create-server. (Такой подход использован, например, в игре Crack Attack.)
Вам, естественно, неохота держать две man-страницы для этих команд — лучше обойтись ссылкой. Создайте основную страницу qaziqargs.6, а в странице qaziqargs-create-server.6 пропишите всего одну строку:
.so man6/qaziqargs.6
Обратите внимание, что файл находится в каталоге с man-страницами, а не у вас под руками в home: переадресация действует только внутри системной директории. По умолчанию это /usr/share/man.
Сам я предпочитаю хранить man-страницы внутри домашнего каталога, пока вожусь с отладкой, а для их загрузки набираю команду man -l. Как только качество страницы меня удовлетворяет, я сжимаю ее при помощи gzip (и вам советую), а потом уж устанавливаю в /usr/share/man.
А теперь радуйтесь: настал конец мучениям! Хотя рассмотренный код невелик, он иллюстрирует все необходимые макросы, с которыми man-страницы писать легко.
Конечно, создание документации предполагает не только написание man-страниц — есть множество других форматов, например, info, со своими собственными правилами. Однако man-страницы являются в Linux стандартом де-факто, а в некоторых дистрибутивах, скажем, Arch Linux и Crux, вся прочая документация из пакетов специально удаляется. Итак, за дело — документации никогда не бывает много.
- Метамодернизм в позднем творчестве В.Г. Сорокина
- ЛитРПГ - последняя отрыжка постмодерна
- "Ричард III и семиотика"
- 3D-визуализация обложки Ridero создаем обложку книги при работе над самиздатом.
- Архитектура метамодерна - говоря о современном искусстве, невозможно не поговорить об архитектуре. В данной статье будет отмечено несколько интересных принципов, характерных для построек "новой волны", столь притягательных и скандальных.
- Литература
- Метамодерн
- Рокер-Прометей против изначального зла в «Песне про советскую милицию» Вени Дркина, Автор: Нина Ищенко, к.ф.н, член Союза Писателей ЛНР - перепубликация из журнала "Топос".
- Как избавиться от комаров? Лучшие типы ловушек.
- Что делать если роблокс вылетает на windows
- Что делать, если ребенок смотрит порно?
- Почему собака прыгает на людей при встрече?
- Какое масло лить в Задний дифференциал (мост) Visco diff 38434AA050
- О чем может рассказать хвост вашей кошки?
- Верветки
- Отчетность бюджетных учреждений при закупках по Закону № 223-ФЗ
- Срок исковой давности как правильно рассчитать
- Дмитрий Патрушев минсельхоз будет ли преемником Путина
- Кто такой Владислав Поздняков? Что такое "Мужское Государство" и почему его признали экстремистским в России?
- Как правильно выбрать машинное масло в Димитровграде?
- Как стать богатым и знаменитым в России?
- Почему фильм "Пипец" (Kick-Ass) стал популярен по всему миру?
- Как стать мудрецом?
- Как правильно установить FreeBSD
- Как стать таким как Путин?
- Где лучше жить - в Димитровграде или в Ульяновске?
- Почему город Димитровград так называется?
- Что такое метамодерн?
- ВАЖНО! Временное ограничение движения автотранспортных средств в Димитровграде
- Тарифы на электроэнергию для майнеров предложено повысить
