вторник, 19 января 2010 г.

Пишем man-страницы

Привет!

Недавно заинтересовался тем, как же писать man-страницы — всё-таки, EasyPK уже перерос в небольшую утилиту, которую хорошо бы документировать не только ключами -h, но и чем-то посолиднее. Как оказалось, начать писать маны очень просто — достаточно только просмотреть вот этот документик, и вы уже знакомы с основами. Должен предупредить, что в указанной статье дан очень минималистский набор опций, так что вот пара трюков, которые я хотел бы добавить.

Первым моментом, который не освещён в статье, являются абзацы с тегами. С помощью такой заумно названной штуки очень удобно организовывать, скажем, списки опций: абзацем будет описание, а тегом — сама опция. Отображается это дело вполне корректно. Список опций строится достаточно просто:
.SH OPTIONS
.TP
.B \-h
Display a short help
.TP
.B tar, tbz, tbz2, tgz, bz2, gz, 7z, zip, rar
Resulting archive format
.TP
.B \-d
Delete input files after adding them to archive
.TP
.BI \-o " outfile"
Use
.I
outfile
as output file
Теги я выделил полужирным — так красивее.

Вышеприведённый код содержит в себе второй трюк — последняя опция отобразится вот так:

-o outfile
     Use outfile as output file.

Почему не сделать так:
.B \-o
.I outfile
? А вот не знаю :) Не работает, и всё. Зато .BI с радостью сделает то, что требуется, так что запомним этот финт и пойдём дальше.

Третье — e-mail'ы. Для того, чтобы они выглядели так:

You can mail author at <author@companyname.com>

достаточно написать такой код:
You can mail author at <\fIauthor@companyname.com\fR>
Как видите, всё очень просто, не нужно даже делать лишних переносов строк.

Наконец, последний момент — это ссылки на другие ман-страницы (секция SEE ALSO). Тут просто даю кусок кода:
.SH SEE ALSO
.BR unpk (1),
.BR atool (1),
.BR bzip2 (1),
.BR gzip (1),
.BR pv (1),
.BR rar (1),
.BR tar (1),
.BR 7z (1)
Надеюсь, этот пост и труд Christopher Vickery сослужит хорошую службу тем, кто хочет написать man-страничку к своему проекту, но не знает, как.

P.S. Кстати, в Linux правила форматирования описаны в man 7 man.

Копируете статью — поставьте ссылку!

4 комментария:

muhas комментирует...

просто-то просто, но жудко неудобно. я вот txt2man заюзал для этих целей - очень рад

Minoru комментирует...

txt2man, конечно, хорошо (хоть я его и не юзал), но формат man-страниц не так уж страшен — можно и руками писать, пусть это и не сильно удобно.

Sergey комментирует...

А ещё можно маны в разметке markdown писать. Вот так. По-моему гораздо читаемее. Компилируется в groff-разметку командой

pandoc -s -w man pandoc.1.md -o pandoc.1

Minoru комментирует...

2 Сергей:

А ещё можно маны в разметке markdown писать.
А вот это уже интересно! Пример впечатлил, markdown прост и понятен. Надо будет попробовать на досуге. Спасибо!

Отправить комментарий

Примечание. Отправлять комментарии могут только участники этого блога.

 
Blogger logo Debian logo Creative Commons License FeedBurner Subscribers Counter