página man - man page

A página do manual no man (1) , conforme visto em várias distribuições Linux . Esta versão é do man-db.

A página man (abreviação de página do manual ) é uma forma de documentação de software normalmente encontrados em um Unix ou Unix-like sistema operacional . Os tópicos abordados incluem programas de computador (incluindo bibliotecas e chamadas de sistema ), padrões e convenções formais e até mesmo conceitos abstratos. Um usuário pode invocar uma página de manual emitindo o man comando .

Por padrão, mannormalmente usa um programa de pager de terminal como moreou lesspara exibir sua saída.

As páginas de manual são frequentemente referidas como uma forma on-line ou on - line de documentação de software, embora o mancomando não exija acesso à Internet, que remonta à época em que manuais impressos fora de banda eram a norma.

História

xman , um dos primeiros aplicativos X11 para visualização de páginas de manual
Página de manual de introdução da seção 8 do OpenBSD , exibida em um console de texto

Nos primeiros dois anos da história do Unix , nenhuma documentação existia. O Manual do Programador Unix foi publicado pela primeira vez em 3 de novembro de 1971. As primeiras páginas do manual reais foram escritas por Dennis Ritchie e Ken Thompson por insistência de seu gerente Doug McIlroy em 1971. Além das páginas do manual, o Manual do Programador também acumulou um conjunto de artigos curtos, alguns deles tutoriais (por exemplo, para uso geral do Unix, a linguagem de programação C e ferramentas como Yacc ) e outras descrições mais detalhadas dos recursos do sistema operacional. A versão impressa do manual cabia inicialmente em um único fichário, mas a partir do PWB / UNIX e da 7ª Edição do Research Unix , ele foi dividido em dois volumes com as páginas do manual impressas formando o Volume 1.

Versões posteriores da documentação imitaram a concisão das primeiras páginas de manual. Ritchie adicionou uma seção "Como começar" à introdução da Terceira Edição , e Lorinda Cherry forneceu a referência de bolso "Cartão Roxo" para a Sexta e Sétima Edições. As versões do software foram nomeadas após a revisão do manual; a sétima edição do Unix Programmer's Manual , por exemplo, veio com a 7ª edição ou versão 7 do Unix.

Para a Quarta Edição, as páginas do manual foram formatadas usando o pacote de composição tipográfica troff e seu conjunto de -manmacros (que foram completamente revisados ​​entre a Sexta e a Sétima Edições do Manual , mas desde então não mudaram drasticamente). Na época, a disponibilização da documentação online por meio do sistema de páginas de manual foi considerada um grande avanço. Até hoje, virtualmente todos os aplicativos de linha de comando do Unix vêm com uma página de manual, e muitos usuários de Unix percebem a falta de páginas de manual em um programa como um sinal de baixa qualidade; de fato, alguns projetos, como o Debian , se esforçam para escrever páginas de manual para programas que não possuem uma. Os descendentes modernos do 4.4BSD também distribuem as páginas de manual como uma das formas primárias de documentação do sistema (tendo substituído as -manmacros antigas pelas mais novas -mdoc).

Havia um easter egg oculto na versão man-db do comando man que faria com que o comando retornasse "gimme gimme gimme" quando executado às 00:30 (uma referência à música do ABBA Gimme! Gimme! Gimme! (A Man Depois da meia-noite) . Foi introduzido em 2011, mas primeiro foi restrito e, em seguida, removido em 2017, depois de finalmente ser encontrado.

Formatação

Parte da página de manual do FreeBSD man (1) , editada no formato PDF .

O formato padrão das páginas do manual é troff , com o pacote de macros man (orientado para aparência) ou mdoc (orientado para a semântica). Isso possibilita a composição de uma página de manual em PostScript , PDF e vários outros formatos para visualização ou impressão.

Alguns sistemas Unix possuem um pacote para o comando man2html , que permite aos usuários navegar em suas páginas de manual usando um navegador HTML. Os sistemas com groff e man-db devem usar a saída HTML nativa de alta qualidade ( man --html ). O programa GNU Emacs WoMan (de "WithOut man") permite navegar nas páginas do manual a partir do editor.

Em 2010, o OpenBSD substituiu o troff para formatar páginas de manual em favor do mandoc , um compilador / formatador especializado para páginas de manual com suporte nativo para saída em PostScript , HTML , XHTML e o terminal. Destina-se a suportar apenas um subconjunto de troff usado em páginas de manual, especificamente aqueles que usam macros mdoc.

Serviços online

Muitos sites oferecem acesso online a páginas de manual de vários sistemas do tipo Unix.

Em fevereiro de 2013, a comunidade BSD viu um novo serviço mdoc.su de código aberto lançado, que unificou e encurtou o acesso aos scripts man.cgi dos principais projetos BSD modernos por meio de um serviço exclusivo de encurtamento de URL determinístico baseado em nginx para o * BSD man Páginas.

Para Linux, um serviço man7.org foi configurado para servir manuais específicos para o sistema. Um serviço ManKier oferece uma seleção mais ampla e também integra as páginas TLDR.

Uso de comando

Para ler uma página de manual de um comando Unix, um usuário pode digitar: 

man <command_name>

As páginas são tradicionalmente chamadas de notação "nome (seção)": por exemplo ftp(1),. A seção refere-se às diferentes maneiras pelas quais o tópico pode ser referenciado - por exemplo, como uma chamada de sistema, ou um comando ou pacote shell (linha de comando), ou um arquivo de configuração de pacote, ou como uma construção / cabeçalho de codificação.

O mesmo nome de página pode aparecer em mais de uma seção do manual, como quando os nomes das chamadas do sistema , comandos do usuário ou pacotes de macros coincidem. Os exemplos são man(1)e man(7), ou exit(2)e exit(3). A sintaxe para acessar a seção manual não padrão varia entre as diferentes implementações do man.

No Solaris e no Illumos, por exemplo, a sintaxe para leitura printf(3C)é: 

man -s 3c printf

Em derivados Linux e BSD, a mesma invocação seria: 

man 3 printf

que procura por printf na seção 3 das páginas de manual.

Seções do manual

O manual é geralmente dividido em oito seções numeradas, organizadas da seguinte forma (em Research Unix , BSD , macOS e Linux ):

Seção Descrição
1 Comandos gerais
2 Chamadas de sistema
3 Funções de biblioteca , cobrindo em particular a biblioteca padrão C
4 Arquivos especiais (geralmente dispositivos, aqueles encontrados em / dev) e drivers
5 Formatos de arquivo e convenções
6 Jogos e protetores de tela
7 Diversos
8 Comandos e daemons de administração do sistema

As chamadas do sistema POSIX estão freqüentemente presentes nas seções 2 e 3, onde a seção 2 contém a documentação da chamada do sistema do sistema operacional local e a seção 3 contém a documentação da chamada do sistema do Manual do Programador POSIX.

O Unix System V usa um esquema de numeração semelhante, exceto em uma ordem diferente:

Seção Descrição
1 Comandos gerais
1M Comandos e daemons de administração do sistema
2 Chamadas de sistema
3 Funções da biblioteca C
4 Formatos de arquivo e convenções
5 Miscelânea
6 Jogos e protetores de tela
7 Arquivos especiais (geralmente dispositivos, aqueles encontrados em / dev) e drivers

Em alguns sistemas, algumas das seguintes seções estão disponíveis:

Seção Descrição
0 Arquivos de cabeçalho da biblioteca C (Unix v6)
9 Rotinas de kernel (FreeBSD, SVR4, Linux)
eu Funções da biblioteca LAPACK
n Comandos Tcl / Tk
x O Sistema X Window

Algumas seções são subdivididas por meio de um sufixo; por exemplo, em alguns sistemas, a seção 3C é para chamadas de biblioteca C, 3M é para a biblioteca matemática e assim por diante. Uma consequência disso é que a seção 8 (comandos de administração do sistema) às vezes é relegada à subseção 1M da seção de comandos principais. Alguns sufixos de subseção têm um significado geral nas seções:

Subseção Descrição
p Especificações POSIX
x Documentação do sistema X Window

(A Seção 3 tende a ser a exceção com muitos sufixos para diferentes idiomas.)

Algumas versões do man armazenam em cache as versões formatadas das últimas páginas visualizadas. Um formulário é a página cat , simplesmente canalizada para o pager para exibição.

Layout

Todas as páginas do manual seguem um layout comum que é otimizado para apresentação em uma exibição de texto ASCII simples , possivelmente sem qualquer forma de destaque ou controle de fonte. As seções presentes podem incluir:

NOME
O nome do comando ou função, seguido por uma descrição de uma linha do que ele faz.
SINOPSE
No caso de um comando, uma descrição formal de como executá-lo e quais opções de linha de comando são necessárias. Para funções de programa, uma lista dos parâmetros que a função assume e qual arquivo de cabeçalho contém sua declaração.
DESCRIÇÃO
Uma descrição textual do funcionamento do comando ou função.
EXEMPLOS
Alguns exemplos de uso comum.
VEJA TAMBÉM
Uma lista de comandos ou funções relacionados.

Outras seções podem estar presentes, mas não são bem padronizadas nas páginas do manual. Exemplos comuns incluem: OPÇÕES, STATUS DE SAÍDA, VALOR DE RETORNO, AMBIENTE, BUGS, ARQUIVOS, AUTOR, RELATÓRIO DE BUGS, HISTÓRICO e DIREITOS AUTORAIS.

Autoria

As páginas do manual podem ser escritas nas manmacros antigas , nas novas docmacros ou em uma combinação de ambas ( mandoc). O manconjunto de macros fornece funções de rich text mínimas , com diretivas para a linha de título, cabeçalhos de seção, fontes (negrito, pequeno ou itálico), parágrafos e adição / redução de recuo. A mdoclinguagem mais recente é de natureza mais semântica e contém macros especializadas para a maioria das seções padrão, como nome do programa, sinopse, nomes de função e o nome dos autores. Essas informações podem ser usadas para implementar uma busca semântica de manuais por programas como o Mandoc . Embora também inclua diretivas para controlar diretamente o estilo, espera-se que as macros especializadas abranjam a maioria dos casos de uso. Os projetos mandoc e groff consideram mdoco formato preferido para novos documentos.

Embora as páginas do manual sejam, para falar a verdade, texto disposto usando tipo romano de 10 pontos , essa distinção é geralmente discutível porque as páginas do manual são visualizadas no terminal (TTY) em vez de dispostas no papel. Como resultado, a macro "fonte pequena" raramente é usada. Por outro lado, o texto em negrito e itálico é suportado pelo terminal via ECMA-48 , e o groff os grottyemite conforme solicitado quando detecta um terminal de suporte. O mandoc BSD, entretanto, suporta apenas texto em negrito e sublinhado (como uma substituição para itálico) por meio da sequência backspace-then-overstrike da máquina de escrever, que precisa ser traduzida para ECMA-48 por less.

As páginas do manual são geralmente escritas em inglês, mas traduções para outros idiomas podem estar disponíveis no sistema. O GNU man-dbe o mandoc mansão conhecidos por pesquisar por páginas de manual localizadas em subdiretórios.

Alternativas

Poucas alternativas mangozaram de muita popularidade, com a possível exceção do sistema " " do Projeto GNUinfo , um sistema de hipertexto simples e antigo . Há também um esforço de terceiros conhecido como páginas TLDR ( tldr) que fornece exemplos simples para casos de uso comum, semelhante a um cheatsheet .

Além disso, alguns aplicativos Unix GUI (particularmente aqueles construídos usando os ambientes de desenvolvimento GNOME e KDE ) agora fornecem documentação de usuário final em HTML e incluem visualizadores de HTML embutidos, como yelppara ler a ajuda dentro do aplicativo.

Veja também

Referências

links externos