path: root/documentation/content/pt-br/books/fdp-primer/manual-pages/_index.adoc

---
description: 'Como trabalhar com as Páginas de Manual do FreeBSD'
next: books/fdp-primer/writing-style
prev: books/fdp-primer/po-translations
tags: ["manual pages", "introduction", "guide", "reference"]
title: 'Capítulo 10. Páginas de Manual'
---

[[manual-pages]]
= Páginas de Manual
:doctype: book
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:source-highlighter: rouge
:experimental:
:skip-front-matter:
:xrefstyle: basic
:relfileprefix: ../
:outfilesuffix:
:sectnumoffset: 10
:toc-title: Índice

toc::[]

[[manual-pages-introduction]]
== 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: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.

[[manual-pages-sections]]
== 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:

[.informaltable]
[cols="1,8", options="header"]
|===
| Section Number
| Category


|1
|General Commands

|2
|System Calls

|3
|Library Functions

|4
|Kernel Interfaces

|5
|File Formats

|6
|Games

|7
|Miscellaneous

|8
|System Manager

|9
|Kernel Developer
|===

[[manual-pages-markup]]
== Marcação

Vários formulários de marcação e programas de renderização foram usados para páginas de manual. O FreeBSD usou man:groff[7] e o mais recente man:mandoc[1]. A maioria das páginas de manual do FreeBSD, e todas as novas, usam o formulário man: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 man: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:man[1].

[[manual-pages-markup-sections]]
=== 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:

[.informaltable]
[cols="2,4", options="header"]
|===
| Section Name
| Description


|NAME
|Name of the command

|SYNOPSIS
|Format of options and arguments

|DESCRIPTION
|Description of purpose and usage

|ENVIRONMENT
|Environment settings that affect operation

|EXIT STATUS
|Error codes returned on exit

|EXAMPLES
|Examples of usage

|COMPATIBILITY
|Compatibility with other implementations

|SEE ALSO
|Cross-reference to related manual pages

|STANDARDS
|Compatibility with standards like POSIX

|HISTORY
|History of implementation

|BUGS
|Known bugs

|AUTHORS
|People who created the command or wrote the manual page.
|===

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.

[[manual-pages-markup-macros]]
=== Macros

A marcação man: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 man:ls[1]:

[.programlisting]
....
.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 _Section header_ para a seção NAME é definido. Em seguida, o _Name_ do comando e um _Name description_ de uma linha são definidos.
<.> A seção SYNOPSIS começa. Esta seção descreve as opções de linha de comando e os argumentos que são aceitos.
<.> _Name_ (`.Nm`) já foi definido, e repeti-lo aqui apenas exibe o valor definido no texto.
<.> 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`.
<.> Uma longa lista de flags opcionais de um único caractere é mostrada.
<.> 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 man:ls[1] o que mostrar e como mostrar. Detalhes sobre a string de formato são fornecidos posteriormente na página do manual.
<.> Um argumento opcional final é definido. Visto que nenhum nome é especificado para o argumento, o padrão de `file ...` é usado.
<.> O _Section header_ para a seção DESCRIPTION é definido.

Quando renderizado com o comando `man ls`, o resultado exibido na tela é semelhante ao seguinte:

[.programlisting]
....
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.

[[manual-pages-markup-guidelines]]
=== Diretrizes de Marcação

A linguagem de marcação man: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 link:{committers-guide}[Guia dos Committer's].

[[manual-pages-markup-tricks]]
=== Truques de Marcação

Adicione um espaço antes da pontuação em uma linha com macros. Exemplo:

[.programlisting]
....
.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,`.

[[manual-pages-markup-important-macros]]
=== Macros Importantes

Algumas macros muito comuns serão mostradas aqui. Para obter mais exemplos de uso, consulte man:mdoc[7], man:groff_mdoc[7], ou procure por uso real no diretório [.filename]#/usr/share/man/man*#. Por exemplo, para procurar exemplos da macro `.Bd` _Begin display_:

[source, shell]
....
% find /usr/share/man/man* | xargs zgrep '.Bd'
....

[[manual-pages-markup-important-macros-organizational]]
==== Macros Organizacionais

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

[.informaltable]
[cols="1,8", options="header"]
|===
| Organizational Macro
| Use


|`.Sh`
|Section header.
Followed by the name of the section, traditionally all upper case.
Think of these as chapter titles.

|`.Ss`
|Subsection header.
Followed by the name of the subsection.
Used to divide a `.Sh` section into subsections.

|`.Bl`
|Begin list. Start a list of items.

|`.El`
|End a list.

|`.Bd`
|Begin display.
Begin a special area of text, like an indented area.

|`.Ed`
|End display.
|===

[[manual-pages-markup-important-macros-inline]]
==== Macros Inline

Muitas macros são usadas para marcar texto embutido.

[.informaltable]
[cols="1,8", options="header"]
|===
| Inline Macro
| Use


|`.Nm`
|Name.
Called with a name as a parameter on the first use, then used later without the parameter to display the name that has already been defined.

|`.Pa`
|Path to a file.
Used to mark up filenames and directory paths.
|===

[[manual-pages-sample-structures]]
== 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.

[[manual-pages-sample-structures-section-1-8]]
=== Seção 1 ou 8 sobre um comando

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

[.programlisting]
....
.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
....

[[manual-pages-sample-structures-section-4]]
=== Seção 4 sobre um Driver de Dispositivo

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

[.programlisting]
....
.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
....

[[manual-pages-sample-structures-section-5]]
=== 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:

[.programlisting]
....
.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
....

[[manual-pages-testing]]
== 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: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 man:mandoc[1] para verificar se há erros:

[source, shell]
....
% mandoc -T lint ./mynewmanpage.8
....

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

[source, shell]
....
% igor ./mynewmanpage.8
....

Use man:man[1] para verificar o resultado final de suas alterações:

[source, shell]
....
% man ./mynewmanpage.8
....

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

[source, shell]
....
% man ./mynewmanpage.8 | col -b | vim -R -
....

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

[source, shell]
....
% aspell check --lang=en --mode=nroff ./mynewmanpage.8
....

[[manual-pages-examples-as-templates]]
== 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.

[.informaltable]
[cols="1,4", options="header"]
|===
| Manual Page
| Path to Source Location


|man:cp[1]
|[.filename]#/usr/src/bin/cp/cp.1#

|man:vt[4]
|[.filename]#/usr/src/share/man/man4/vt.4#

|man:crontab[5]
|[.filename]#/usr/src/usr.sbin/cron/crontab/crontab.5#

|man:gpart[8]
|[.filename]#/usr/src/sbin/geom/class/part/gpart.8#
|===

[[manual-pages-resources]]
== Recursos

Recursos para escritores de páginas manuais:

* man:man[1]
* man:mandoc[1]
* man:groff_mdoc[7]
* http://manpages.bsd.lv/mdoc.html[Practical UNIX Manuals: mdoc]
* http://manpages.bsd.lv/history.html[History of UNIX Manpages]