Пишем 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.

Comments (migrated from Blogger)