Vários formulários de marcação e programas de renderização foram usados para páginas de manual. O FreeBSD usou groff(7) e o mais recente mandoc(1). A maioria das páginas de manual do FreeBSD, e todas as novas, usam o formulário mdoc(7) de marcação. Esta é uma marcação simples baseada em linhas que é razoavelmente expressiva. É principalmente semântico: partes do texto são marcadas para o que são, em vez de como devem aparecer quando renderizadas. Existe alguma marcação baseada em aparência que geralmente é melhor evitar.
O código fonte de página de manual geralmente é interpretada e exibido na tela interativamente. Os arquivos fontes podem ser arquivos de texto comuns ou compactados com gzip(1) para economizar espaço.
As páginas de manual também podem ser renderizadas para outros formatos, incluindo PostScript para impressão ou geração de PDF. Veja man(1).
O teste de uma nova página de manual pode ser um desafio quando o arquivo não está localizado no caminho de pesquisa normal da páginas de manual. man(1) também não procura no diretório atual. Se a nova página de manual estiver no diretório atual, prefixe o nome do arquivo com um ./
:
%
man ./mynewmanpage.8
Um caminho absoluto também pode ser usado:
%
man /home/xsmith/mynewmanpage.8
Páginas de manual são compostas por várias seções padrão. Cada seção tem um título em letras maiúsculas e as seções de um determinado tipo de página de manual aparecem em uma ordem específica. Para uma página de manual do Comando Geral da categoria 1, as seções são:
Nome da Seção | Descrição |
---|---|
NAME | Nome do Comando |
SYNOPSIS | Formato das opções e argumentos |
DESCRIPTION | Descrição da finalidade e uso |
ENVIRONMENT | Configurações de ambiente que afetam a operação |
EXIT STATUS | Códigos de erro retornados na saída |
EXAMPLES | Exemplos de uso |
COMPATIBILITY | Compatibilidade com outras implementações |
SEE ALSO | Referência cruzada para páginas de manual relacionadas |
STANDARDS | Compatibilidade com padrões como o POSIX |
HISTORY | História de implementação |
BUGS | Bugs conhecidos |
AUTHORS | Pessoas que criaram o comando ou escreveram a página de manual. |
Algumas seções são opcionais e a combinação de seções para um tipo específico de página manual pode variar. Exemplos dos tipos mais comuns são mostrados mais adiante neste capítulo.
A marcação mdoc(7) é baseada em macros. As linhas que começam com um ponto contêm comandos de macro, com duas ou três letras. Por exemplo, veja esta parte da página de manual do ls(1):
.Dd December 1, 2015.Dt LS 1 .Sh NAME
.Nm ls .Nd list directory contents .Sh SYNOPSIS
.Nm
.Op Fl -libxo
.Op Fl ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,
.Op Fl D Ar format
.Op Ar
.Sh DESCRIPTION
For each operand that names a .Ar file of a type other than directory, .Nm displays its name as well as any requested, associated information. For each operand that names a .Ar file of type directory, .Nm displays the names of files contained within that directory, as well as any requested, associated information.
O Document date e Document title são definidos. | |
O Cabeçalho da Seção para a seção NAME é definido. Em seguida, são definidos o Nome do comando e uma Descrição do Nome de uma linha. | |
A seção SYNOPSIS começa. Esta seção descreve as opções e argumentos de linha de comando que são aceitos. | |
Nome ( | |
Uma Optional Flag chamada | |
Uma longa lista de sinalizadores opcionais de caracteres únicos é apresentada. | |
Uma flag opcional | |
Um argumento opcional final é definido. Como nenhum nome é especificado para o argumento, o padrão | |
O Cabeçalho da Seção para a seção DESCRIPTION é definido. |
Quando renderizado com o comando man ls
, o resultado exibido na tela é semelhante ao seguinte:
LS(1) FreeBSD General Commands Manual LS(1) NAME ls — list directory contents SYNOPSIS ls [--libxo] [-ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,] [-D format] [file ...] DESCRIPTION For each operand that names a file of a type other than directory, ls displays its name as well as any requested, associated information. For each operand that names a file of type directory, ls displays the names of files contained within that directory, as well as any requested, associated information.
Valores opcionais são mostrados entre colchetes.
A linguagem de marcação mdoc(7) não é muito rigorosa. Para maior clareza e consistência, o projeto Documentação do FreeBSD adiciona algumas diretrizes de estilo adicionais:
Sempre use maiúsculas para a primeira letra de uma macro e minúscula para as letras restantes.
Inicie uma nova frase em uma nova linha, não a inicie na mesma linha de uma frase existente.
.Dd
ao fazer alterações não triviais em uma página de manualA Data do documento informa o leitor sobre a última vez que a página de manual foi atualizada. É importante atualizar sempre que alterações não triviais forem feitas nas páginas de manual. Alterações triviais, como correções ortográficas ou de pontuação que não afetam o uso, podem ser feitas sem atualizar .Dd
.
Apresente exemplos ao leitor sempre que possível. Mesmo exemplos triviais são valiosos, porque o que é trivial para o escritor não é necessariamente trivial para o leitor. Três exemplos são um bom objetivo. Um exemplo trivial mostra os requisitos mínimos, um exemplo afundo mostra o uso real e um exemplo detalhado demonstra uma funcionalidade incomum ou não óbvia.
Inclua a licença BSD em novas páginas de manual. A licença preferencial está disponível no Guia dos Committer's.
Adicione um espaço antes da pontuação em uma linha com macros. Exemplo:
.Sh SEE ALSO .Xr geom 4 , .Xr boot0cfg 8 , .Xr geom 8 , .Xr gptboot 8
Observe como as vírgulas no final das linhas .Xr
foram colocadas após um espaço. A macro .Xr
espera dois parâmetros, o nome de uma página de manual externa e um número de seção. O espaço separa a pontuação do número da seção. Sem o espaço, os links externos apontariam incorretamente para a seção 4,
ou 8,
.
Algumas macros muito comuns serão mostradas aqui. Para obter mais exemplos de uso, consulte mdoc(7), groff_mdoc(7), ou procure por uso real no diretório /usr/share/man/man*
. Por exemplo, para procurar exemplos da macro .Bd
Begin display:
%
find /usr/share/man/man* | xargs zgrep '.Bd'
Algumas macros são usadas para definir blocos lógicos de uma página de manual.
Macro Organizacional | Uso |
---|---|
.Sh | Section header (Cabeçalho da seção). Seguido pelo nome da seção, tradicionalmente com os caracteres todos em maiúsculas. Pense neles como títulos de capítulos. |
.Ss | Subsection header (Cabeçalho da subseção). Seguido pelo nome da subseção. Usado para dividir uma seção .Sh em subseções. |
.Bl | Begin list. Comece uma lista de itens. |
.El | End a list (Finalize uma lista). |
.Bd | Begin display (Comece a exibição). Comece em uma área especial de texto, como uma área recuada. |
.Ed | End display (Termine a exibição). |
Muitas macros são usadas para marcar texto embutido.
Macro Inline | Uso |
---|---|
.Nm | Name. Chamado com um nome como parâmetro no primeiro uso, usado depois sem o parâmetro para exibir o nome que já foi definido. |
.Pa | Path to a file (Caminho para um arquivo). Usado para marcar nomes de arquivos e caminhos de diretório. |
All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/
Questions that are not answered by the
documentation may be
sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.