Capítulo 11. Páginas de Manual

Esta tradução pode estar desatualizada. Para ajudar com as traduções, acesse a ferramenta de traduções do FreeBSD.

11.1. Introdução

Páginas de manual, geralmente abreviadas como man pages, foram concebidas como lembretes prontamente disponíveis para sintaxe de comandos, detalhes de drivers de dispositivos ou formatos de arquivos de configuração. Elas se tornaram uma referência rápida extremamente valiosa de linha de comando para usuários, administradores de sistema e programadores.

Embora tenham sido planejados como material de referência em vez de tutoriais, as seções EXEMPLOS das páginas de manual geralmente fornecem casos de uso detalhados.

Páginas de manual são geralmente mostradas interativamente pelo comando man(1). Quando o usuário digita man ls, uma pesquisa é executada para uma página de manual que corresponde a ls. O primeiro resultado correspondente é exibido.

11.2. Seções

As páginas de manual são agrupadas em seções. Cada seção contém páginas de manual para uma categoria específica de documentação:

Número da SeçãoCategoria

1

Comandos Gerais

2

Chamadas de Sistema

3

Funções de Biblioteca

4

Interfaces do Kernel

5

Formatos de Arquivo

6

Jogos

7

Diversos

8

Gerenciamento do Sistema

9

Desenvolvedor do Kernel

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

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

NAME

Nome do comando

SYNOPSIS

Formato de 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 POSIX

HISTORY

Histórico de implementação

BUGS

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

11.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.
1O Document date e Document title são definidos.
2O Section header para a seção NAME é definido. Em seguida, o Name do comando e um Name description de uma linha são definidos.
3A seção SYNOPSIS começa. Esta seção descreve as opções de linha de comando e os argumentos que são aceitos.
4Name (.Nm) já foi definido, e repeti-lo aqui apenas exibe o valor definido no texto.
5Uma Optional Flag chamada -libxo é mostrada. A macro Fl adiciona um traço ao início das flags, então isso aparece na página de manual como`--libxo`.
6Uma longa lista de flags opcionais de um único caractere é mostrada.
7Uma flag opcional -D é definida. Se a flag -D for fornecida, ele deve ser seguido por um Argument. O argumento é um format, uma string que diz ao ls(1) o que mostrar e como mostrar. Detalhes sobre a string de formato são fornecidos posteriormente na página do manual.
8Um argumento opcional final é definido. Visto que nenhum nome é especificado para o argumento, o padrão de file …​ é usado.
9O Section header 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.

11.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 de 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.

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

11.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'

11.3.5.1. Macros Organizacionais

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

Macro OrganizacionalUso

.Sh

Cabeçalho da seção (Section header). Seguido do nome da seção, tradicionalmente toda em caixa alta. Pense nisso como títulos de capítulos.

.Ss

Cabeçalho da subseção (Subsection header). Seguido pelo nome da subseção. Usado para dividir uma seção .Sh em subseções.

.Bl

Comece a lista (Begin list). Inicie uma lista de itens.

.El

Terminar lista (End list).

.Bd

Comece a exibição (Begin display). Comece uma área especial do texto, como uma área recuada.

.Ed

Fim da exibição (End display).

11.3.5.2. Macros Inline

Muitas macros são usadas para marcar texto embutido.

Macro inlineUso

.Nm

Nome. Chamado com um nome como parâmetro no primeiro uso, depois usado sem o parâmetro para exibir o nome que já foi definido.

.Pa

Caminho para um arquivo (Path to a file). Usado para marcar nomes de arquivos e caminhos de diretório.

11.4. Exemplo de Estruturas de Página de Manual

Esta seção mostra o conteúdo mínimo desejável para um página de manual para várias categorias comuns de páginas de manual.

11.4.1. Seção 1 ou 8 sobre um comando

A estrutura básica preferida para uma seção 1 ou 8 sobre um comando:

.Dd August 25, 2017
.Dt EXAMPLECMD 8
.Os
.Sh NAME
.Nm examplecmd
.Nd "command to demonstrate section 1 and 8 man pages"
.Sh SYNOPSIS
.Nm
.Op Fl v
.Sh DESCRIPTION
The
.Nm
utility does nothing except demonstrate a trivial but complete
manual page for a section 1 or 8 command.
.Sh SEE ALSO
.Xr exampleconf 5
.Sh AUTHORS
.An Firstname Lastname Aq Mt flastname@example.com

11.4.2. Seção 4 sobre um Driver de Dispositivo

A estrutura básica preferida para a seção 4 sobre um driver de dispositivo:

.Dd August 25, 2017
.Dt EXAMPLEDRIVER 4
.Os
.Sh NAME
.Nm exampledriver
.Nd "driver to demonstrate section 4 man pages"
.Sh SYNOPSIS
To compile this driver into the kernel, add this line to the
kernel configuration file:
.Bd -ragged -offset indent
.Cd "device exampledriver"
.Ed
.Pp
To load the driver as a module at boot, add this line to
.Xr loader.conf 5 :
.Bd -literal -offset indent
exampledriver_load="YES"
.Ed
.Sh DESCRIPTION
The
.Nm
driver provides an opportunity to show a skeleton or template
file for section 4 manual pages.
.Sh HARDWARE
The
.Nm
driver supports these cards from the aptly-named Nonexistent
Technologies:
.Pp
.Bl -bullet -compact
.It
NT X149.2 (single and dual port)
.It
NT X149.8 (single port)
.El
.Sh DIAGNOSTICS
.Bl -diag
.It "flashing green light"
Something bad happened.
.It "flashing red light"
Something really bad happened.
.It "solid black light"
Power cord is unplugged.
.El
.Sh SEE ALSO
.Xr example 8
.Sh HISTORY
The
.Nm
device driver first appeared in
.Fx 49.2 .
.Sh AUTHORS
.An Firstname Lastname Aq Mt flastname@example.com

11.4.3. Seção 5 sobre um Arquivo de Configuração

A estrutura básica preferida para a seção 5 sobre um arquivo de configuração:

.Dd August 25, 2017
.Dt EXAMPLECONF 5
.Os
.Sh NAME
.Nm example.conf
.Nd "config file to demonstrate section 5 man pages"
.Sh DESCRIPTION
.Nm
is an example configuration file.
.Sh SEE ALSO
.Xr example 8
.Sh AUTHORS
.An Firstname Lastname Aq Mt flastname@example.com

11.5. Testando

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

Use o linter de mandoc(1) para verificar se há erros:

% mandoc -T lint ./mynewmanpage.8

Use o textproc/igor para revisar a página do manual:

% igor ./mynewmanpage.8

Outra ferramenta útil é o textproc/vale. Ele não suporta a sintaxe mdoc(7), mas a página de manual renderizada pode ser lida e analisada a partir da entrada padrão:

% man ls | vale

textproc/vale é altamente configurável. É aconselhável ler sua documentação.

Use man(1) para verificar o resultado final de suas alterações:

% man ./mynewmanpage.8

Você pode usar col(1) para filtrar a saída de man(1) e se livrar dos caracteres backspace antes de carregar o resultado em seu editor favorito para verificação ortográfica:

% man ./mynewmanpage.8 | col -b | vim -R -

A verificação ortográfica com dicionários completos é incentivada e pode ser realizada usando textproc/hunspell ou textproc/aspell combinado com textproc/en-hunspell ou textproc/en-aspell, respectivamente. Por exemplo:

% aspell check --lang=en --mode=nroff ./mynewmanpage.8

11.6. Exemplos de páginas de manuais para usar como modelos

Algumas destas páginas de manual são adequadas para serem usadas como exemplos detalhados.

Página de ManualCaminho para o arquivo de origem

cp(1)

/usr/src/bin/cp/cp.1

vt(4)

/usr/src/share/man/man4/vt.4

crontab(5)

/usr/src/usr.sbin/cron/crontab/crontab.5

gpart(8)

/usr/src/sbin/geom/class/part/gpart.8

11.7. Recursos


Última alteração em: 9 de março de 2024 por Danilo G. Baio