man’ы — это просто!
мы знаем, что для каждой программы должна быть документация. для графических программ — это online help, для консольных инструментов (тот самый cli aka command line interface, который не любят те, кто не в теме) — это man (от manual).
надо сказать, что современные тенденции развития пользовательских приложений, например, для планшетов и смартфонов, отчётливо дают понять, что руководство по эксплуатации никто читать не будет и поэтому online help как бы уже и не нужен. интерфейс у большинства устройств такого рода сейчас, что называется, интуитивно понятный. ну, и доступ в интернет есть практически везде. то есть, руководство пользователя можно скачать в любой момент. ладно, допустим.
а что делать системному администратору, настраивающему маршрутизатор или коммутатор в режиме удалённой консоли? можно, в общем-то, открыть на ноутбуке, с которого заходишь в настройки прибора, интернет и смотреть руководство по эксплуатации. просмотрщик pdf с системой поиска и всё такое. это да. но часто хочется получить быструю подсказку и не перерывать документ из сотен, а иногда и тысяч страниц. в этом случае на помощь приходит или ключ --help или man.
вот про то, как мы теперь делаем man’ы, я попробую рассказать в этой заметке из серии «жизнь и инструменты разработчиков» в unix-подобных системах.
если коротко, то недавно мы решили использовать для редактирования man-страниц формат markdown. простой и очень удобный язык разметки для небольших и минимально структурированных документов, одной из разновидностей которых являются man-страницы.
markdown, видимо, назван в противовес html, который markup.
чем он хорош?
во-первых, это plain-текст. обычный текст, то есть.
во-вторых, структура документа видна без дополнительных инструментов, чем бы вы не пользовались для просмотра.
в-третьих, есть множество инструментов для преобразования из формата markdown в html и roff (обычный формат man-страниц).
да что тут рассказывать? смотрите сами.
вот пример исходного текста для man-страницы:
program(1) -- some program with arbitrary description ====================================================== SYNOPSIS -------- `program` [options]DESCRIPTION ----------- The `program` is a simple example for demonstrating some great features. Please use options and flags with `program`: * `-a`: option 'a'. Try to guess what is it. * `-b`: option 'b'. I do not know idea what does it mean. * `flag1`: required parameter. SEE ALSO -------- man(1), COPYLEFT -------- No copyrights, please.
собственно, всё. то, что «подчёркнуто» двойной линией — заголовок первого уровня (название man-страницы), одинарной — заголовок второго уровня (раздел руководства), со знака * начинается элемент списка. и этого достаточно для создания полноценного документа!
теперь можно использовать программу для преобразования в формат html или man (например, ronn и получать удовольствие от простоты и удобства использования. вот что получилось: ссылка на результат.
и ещё: этот формат давно используется, например, на github’е. простой текст, а насколько проще стало документировать программы. тэги и какая-то сверх-сложная специальная разметка больше не нужны. ура. да здравствует принцип k.i.s.s!