Недавно заинтересовался тем, как же писать 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 <[email protected]>
достаточно написать такой код:
You can mail author at <\[email protected]\fR>Как видите, всё очень просто, не нужно даже делать лишних переносов строк.
Наконец, последний момент — это ссылки на другие ман-страницы (секция SEE ALSO). Тут просто даю кусок кода:
.SH SEE ALSOНадеюсь, этот пост и труд Christopher Vickery сослужит хорошую службу тем, кто хочет написать man-страничку к своему проекту, но не знает, как.
.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
.
Источник статьи