13.3. Marcação

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).

Dica:

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

13.3.1. Seções de Página de Manual

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çãoDescrição
NAMENome do Comando
SYNOPSISFormato das opções e argumentos
DESCRIPTIONDescrição da finalidade e uso
ENVIRONMENTConfigurações de ambiente que afetam a operação
EXIT STATUSCódigos de erro retornados na saída
EXAMPLESExemplos de uso
COMPATIBILITYCompatibilidade com outras implementações
SEE ALSOReferência cruzada para páginas de manual relacionadas
STANDARDSCompatibilidade com padrões como o POSIX
HISTORYHistória de implementação
BUGSBugs conhecidos
AUTHORSPessoas 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.

13.3.2. Macros

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  1
.Dt LS 1
.Sh NAME  2
.Nm ls
.Nd list directory contents
.Sh SYNOPSIS  3
.Nm  4
.Op Fl -libxo  5
.Op Fl ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,  6
.Op Fl D Ar format  7
.Op Ar  8
.Sh DESCRIPTION  9
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.

1

O Document date e Document title são definidos.

2

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.

3

A seção SYNOPSIS começa. Esta seção descreve as opções e argumentos de linha de comando que são aceitos.

4

Nome (.Nm) já foi definido, e repeti-lo aqui apenas exibe o valor definido no texto.

5

Uma Optional Flag chamada -libxo é mostrada. A macro Fl adiciona um traço ao início das flags, portanto, isso aparece na página de manual como --libxo.

6

Uma longa lista de sinalizadores opcionais de caracteres únicos é apresentada.

7

Uma flag opcional -D é definida. Se a flag -D for informada, ela deve ser seguida por um Argumento. O argumento é um format, uma string que diz ls(1) o que exibir e como exibi-lo. Detalhes sobre a string de formato são fornecidos posteriormente na página de manual.

8

Um argumento opcional final é definido. Como nenhum nome é especificado para o argumento, o padrão file ... é usado.

9

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.

13.3.3. Diretrizes de Marcação

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:

Apenas a primeira letra das macros é maiúscula

Sempre use maiúsculas para a primeira letra de uma macro e minúscula para as letras restantes.

Comece novas frases em novas linhas

Inicie uma nova frase em uma nova linha, não a inicie na mesma linha de uma frase existente.

Atualizar .Dd ao fazer alterações não triviais em uma página de manual

A 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.

Apresentando exemplos

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

Inclua a licença BSD em novas páginas de manual. A licença preferencial está disponível no Guia dos Committer's.

13.3.4. Truques de Marcação

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,.

13.3.5. Macros Importantes

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'

13.3.5.1. Macros Organizacionais

Algumas macros são usadas para definir blocos lógicos de uma página de manual.

Macro OrganizacionalUso
.ShSection 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.
.SsSubsection header (Cabeçalho da subseção). Seguido pelo nome da subseção. Usado para dividir uma seção .Sh em subseções.
.BlBegin list. Comece uma lista de itens.
.ElEnd a list (Finalize uma lista).
.BdBegin display (Comece a exibição). Comece em uma área especial de texto, como uma área recuada.
.EdEnd display (Termine a exibição).

13.3.5.2. Macros Inline

Muitas macros são usadas para marcar texto embutido.

Macro InlineUso
.NmName. Chamado com um nome como parâmetro no primeiro uso, usado depois sem o parâmetro para exibir o nome que já foi definido.
.PaPath 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>.