.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.
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.
Índice
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ção | Categoria |
|---|---|
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ção | Descriçã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):
| 1 | O Document date e Document title são definidos. |
| 2 | O Section header para a seção NAME é definido. Em seguida, o Name do comando e um Name description de uma linha são definidos. |
| 3 | A seção SYNOPSIS começa. Esta seção descreve as opções de linha de comando e os argumentos que são aceitos. |
| 4 | Name (.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, então isso aparece na página de manual como`--libxo`. |
| 6 | Uma longa lista de flags opcionais de um único caractere é mostrada. |
| 7 | Uma 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. |
| 8 | Um argumento opcional final é definido. Visto que nenhum nome é especificado para o argumento, o padrão de file … é usado. |
| 9 | O 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
.Ddao 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 Organizacional | Uso |
|---|---|
| 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. |
| Cabeçalho da subseção (Subsection header).
Seguido pelo nome da subseção.
Usado para dividir uma seção |
| Comece a lista (Begin list). Inicie uma lista de itens. |
| Terminar lista (End list). |
| Comece a exibição (Begin display). Comece uma área especial do texto, como uma área recuada. |
| Fim da exibição (End display). |
11.3.5.2. Macros Inline
Muitas macros são usadas para marcar texto embutido.
| Macro inline | Uso |
|---|---|
| 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. |
| 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.8Use o textproc/igor para revisar a página do manual:
% igor ./mynewmanpage.8Outra 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 | valetextproc/vale é altamente configurável. É aconselhável ler sua documentação.
Use man(1) para verificar o resultado final de suas alterações:
% man ./mynewmanpage.8Você 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.811.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 Manual | Caminho para o arquivo de origem |
|---|---|
/usr/src/bin/cp/cp.1 | |
/usr/src/share/man/man4/vt.4 | |
/usr/src/usr.sbin/cron/crontab/crontab.5 | |
/usr/src/sbin/geom/class/part/gpart.8 |
Última alteração em: 9 de março de 2024 por Danilo G. Baio