Meu problema é que, depois que um projeto está prestes a ser concluído, é hora de focar em coisas como documentação, uma das quais é a man page.
Agora, as pessoas podem ou não gostar de páginas de manual, mas é muito comum receber uma ferramenta para Linux.
Meu problema é, no entanto, encontrar informações sobre como exatamente estruturar e escrever um.
Eu sei que existem algumas diretrizes aproximadas, quais seções devem sempre ser incluídas, etc., mas eu confio principalmente em páginas de manual já escritas para coisas como groff , ssh e base64 para ter uma idéia de como (corretamente) escreva um.
O problema é que eles diferem imensamente em seu estilo.
A página man de base64 usa os comandos regulares como .SH e .TP , mas não usa o comando .OP normalmente usado para as tabelas de opções. no entanto, ele usa as sequências de escape semelhantes a troffs:
.TP
\fB\-d\fR, \fB\-\-decode\fR
decode data
É bastante simplista, por assim dizer.
A página man de groff é uma história totalmente diferente. Ele usa coisas como .SY e o comando .OP para switches na sinopse:
.SH SYNOPSIS
.\" --------------------------------------------------------------------
.
.SY groff
.OP \-abcegijklpstzCEGNRSUVXZ
.OP \-d cs
.OP \-D arg
.OP \-f fam
...
Ele usa muito menos seqüências de escape, em vez disso, o texto é estruturas como esta:
.TP
.B \-j
Preprocess with
.BR chem .
.
Implies
.BR \-p .
i.e. usando comandos troff em vez de seqüências de escape.
Existem outros exemplos semelhantes a estes, qualquer pessoa que escreveu uma página man, está ciente dos diversos estilos, etc.
Neste ponto, estou bastante confuso sobre qual estilo devo seguir. Pelo menos algum guia de referência seria bom, e basicamente possivelmente uma cartilha ou algo sobre como isso deve ser abordado. (por exemplo, eu não descobri o que o comando .SY faz, etc.)
Estas páginas foram um começo útil, mas eu rapidamente esgotou sua utilidade:
EDIT: Mais algumas informações em man pages
Obrigado, Stephen Harris.
A diferença entre as duas versões é devida a diferentes conjuntos de macros; o original man set e o mais recente mdoc set. Você pode ver quais comandos cada um tem com
man 7 man
man 7 mdoc
Então, coisas como .Op são válidas apenas usando mdoc
Qualquer versão deve estar bem em sistemas modernos; Eu provavelmente consideraria o formato mdoc .
Tags documentation man