Недавно заинтересовался тем, как же писать 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)
P.S. Кстати, в Linux правила форматирования описаны в
man 7 man
.
Копируете статью — поставьте ссылку!
4 комментария:
просто-то просто, но жудко неудобно. я вот txt2man заюзал для этих целей - очень рад
txt2man, конечно, хорошо (хоть я его и не юзал), но формат man-страниц не так уж страшен — можно и руками писать, пусть это и не сильно удобно.
А ещё можно маны в разметке markdown писать. Вот так. По-моему гораздо читаемее. Компилируется в groff-разметку командой
pandoc -s -w man pandoc.1.md -o pandoc.1
2 Сергей:
А ещё можно маны в разметке markdown писать.
А вот это уже интересно! Пример впечатлил, markdown прост и понятен. Надо будет попробовать на досуге. Спасибо!
Отправить комментарий
Примечание. Отправлять комментарии могут только участники этого блога.