PÁGINAS MAN (MANual)

 http://www.cs.mcgill.ca/~guide/help/man.html

Embora eles não seja bem divulgadas, a realmente uma grande variedade de maneiras de conseguir ajuda para o UNIX. A mais importante e mais confiável são as consultas às páginas 'man', que correspondem a manuais online para programas, formatos de arquivos, funções, chamadas do sistema e assim por diante. Poderia-se ter um pergunta UNIX em grupo de discussão para unicamente obter uma resposta RTFMP ( Read The "Fantastic" Man Pages). Se nunca leu uma antes, a melhor maneira de iniciar é digitando 'man man' na linha de comando.

É claro, enquanto páginas man são uma enorme melhoria sobre as documentações online de outros sistemas operacionais, elas sofrem de muitas deficiência:

• Alguma pessoas não gostam de ler textos da tela.
• Não é muito útil a menos que você já saiba o que está procurando.
• Nem sempre acessíveis mesmo quando existem no Linux.
• Nem sempre existem, especialmente no Linux.
• Freqüentemente difícil de ler, como eles tentam ser autoritário (e, portanto, são muitas vezes demasiado técnico para novos usuários).
• Freqüentemente desatualizadas.

Mesmo assim, elas ainda são melhores e mais abrangentes do que as alternativas. Vamos tentar abordar as três primeiras falhas neste documento.

COMO LER PÁGINAS MAN

Páginas Man são as documentações padrões para todo Unix; esteja certo de deparar-se com a referência antes de ir a um formato muito longo:

<command>(N)

Onde N é um número entre 1-9, possivelmente seguido por uma letra. Aqui está um exemplo que tomaremos a sintaxe ( nota: este exemplo não se aplica a todos UNIX's mas deve ser tomada como forma geral ):

[alex@linux]$ % man mkdir

MKDIR(1)    USER COMMANDS       MKDIR(1)

NAME
   mkdir - make a directory

SYNOPSIS
   mkdir [ -p ] dirname...

DESCRIPTION
   mkdir creates directories. Standard entries,`.',for the
   directory itself, and `..' for its parent, are made automat-
   ically.

   The -p flag allows missing parent directories
   to be created as needed.

   With the exception of the set-gid bit, the
   current umask(2V) setting determines the mode in which
   directories are created. The new directory inherits the set-gid
   bit of the parent directory. Modes may be modified after
   creation by using chmod(1V).

   mkdir requires write permission in the parent directory.

SEE ALSO
   chmod(1V), rm(1), mkdir(2v), umask(2V)

Aqui está a sintaxe de nosso exemplo:

MKDIR(1)    USER COMMANDS        MKDIR(1) 

Isto significa que o comando MKDIR é documentado sobre o nome, na seção (1)  exibido dentro dos parenteses. 

Esta seção pode ser necessário em caso em que haja multiplas páginas man para o mesmo nome. No exemplo abaixo há muitas páginas man chamadas 'mkdir' em ambas seções (1) e (2v). Se não especificado, man lhe dará a primeira manpage que encontrar. 
A opção -f mostrará todas as páginas man para um determinado nome. O mesmo efeito pode ser alcançado pelo uso do comando whatis em vez de man

[alex@linux]$ %whatis mkdir

e

[alex@linux]$ %man -f mkdir

são sinônimos.  Você pode conseguir a descrição de cada seção (eles variam de Unix para Unix) digitando:

[alex@linux]$ %man SECTION# intro

%man SECTION# intro

Continuando com a disposição do mkdir da página man.
NAME

 NAME

 mkdir - make a directory

O nome do comando e uma breve descrição.

SYNOPSIS

mkdir [ -p ] dirname...

Isto descreve os vários flags e o formato apropriado que o comando requer. As flags neste caso são representadas por -p é a sintaxe requer um nome de diretório para prosseguir ( nota: a maioria dos flags são opcionais )  

DESCRIPTION

mkdir creates directories. Standard entries,`.', for the directory itself, and `..' for its parent, are made automatically..

Uma descrição completa de tudo que o comando irá fazer incluindo-se todas as flags.

SEE ALSO
chmod(1V), rm(1), mkdir(2v), umask(2V)

Sugestões de outros comandos que estão de alguma maneira relacionados.

ENCONTRAR PÁGINAS MAN

[alex@linux]$ apropos / man -k / man -kr

Uma invocação do man que você gostará que se torne bastante familiar é a opção man -k (keyword). Esta função é também disponível executando apropos (1), isto é man -k e apropos são equivalentes. Isto permitirá que você busque o sumário da base de dados das páginas man para ver as palavras chaves que podem ser mencionadas nelas.

Suponhamos que você esteja buscando por utilitários que manuseiem documentos postscript.  Podemos também executar:

[alex@linux]$ %man -k postscript

ou

[alex@linux]$ %apropos postscript

Isto produzirá uma lista, com sumários, da páginas man que são susceptíveis de serem relacionadas com o seu tópico.  Se você buscar por algo menos específico, por exemplo  programas relacionados com a base de dados, você provavelmente gostará de usar less e/ou grep  para filtra a exibição de saída.

[alex@linux]$ %man -k postscript | less

A saída pode produzir muitas tela de dados.

Perceba que estes comandos busca a base de dados que em muitos casos devem ser construidos pelo administrador do sistema, uma tarefa que algumas vezes são esquecidas. Se você não pode encontrar o que você está procurando e acredita que isto está lá, experimente executar no Linux, seguido de sua pesquisa

[alex@linux]$ %man -u man

ou

[alex@linux]$ %man -F

em Solaris.  SunOS não possui esta opção. Antes de experimentar fazer isto , asegure-se que sua váriavel de MANPATH está configurada corretamente.

MANPATH

Podem haver muitas hierarquias de páginas man, dependendo do sistema. Na maioria dos sistemas, pelo menos os seguintes diretórios existem: /usr/man, /usr/local/man. Além disto, haverá um para os programas X (/usr/X11/man, /usr/local/X11/man, ou /usr/openwin/man) e provavelmente um para SOCS - páginas especificas man (/usr/socs/man). 

man pesquisa o ambiente da variável MANPATH ( uma lista de diretório com dois-pontos como a variavél PATH)  para páginas man. Se você hackear seu arquivo script ou errou a digitação, o MANPATH pode estar errado. O comando whereis pode se capaz de ajudar aqui. whereis localizará o código binário e os arquivos do manual para o comando. Por exemplo: ( nota: neste exemplo específico não pode ser tomado como genérico no Unix mas somente uma ilustração de possíveis resultados )

[alex@linux]$ %whereis man

man: /usr/ucb/man /usr/local/man /usr/man/man1/man.1 /usr/man/man7/man.7 

PESQUISA MANUAL PARA MAN

Alternativamente, você pode simplesmente tentar o método gambiarra de executar grep (1) no diretório man que você acha que pode conter o comando que você procura;  perceba que página man não são armazenadas em formato de texto simples, portanto a exibição pode não ser tão legível. Se você encontrar o conjunto de palavras que está pesquisando no arquivo localizado em MANDIR/man#, execute 

[alex@linux]$ %man -M MANDIR#filename

para a exibição da página man correspondente.

NÃO HÁ PÁGINA MAN PAGE PARA X!

Ok, você tentou as sugestões acima para localizar as páginas do manual, e não encontra o que procura. É bem possível que não haja páginas de manual correspondente ao que você procura - seja porque a ferramenta ou funcionalidade pela qual você busca não está instalada no sistema ou porque não há páginas de manual instaladas (a última é mais comum no Linux que qualquer outra coisa). 

Suponhamos que você está especialmente determinado porque você "sabe" que o comando existe - ele faz algo, apenas não é o que você quer. Ao invés de ficar irado pelo comando não documentado, primeiro certifique-se que na verdade é um programa que merece uma página de manual, aqui está uma abordagem algorítmica para procurar o arquivo de ajuda de um comando.

Se você está executando ksh ou bash (você saberá se estiver), primeiro execute:

[alex@linux]$ %type -t CMD

Para algum outro shell, execute:

[alex@linux]$ %which CMD

Isto lhe dirá que tipo de comando com o qual você está trabalhando. 

Se você diz CMD é um 'builtin', então fazendo 'help CMD' (somente em bash) ou lê suas páginas de manual de shell. ~(Perceba que tcsh - exceto no Linux - não documenta todos os builtins desde que a maioria são idênticos a csh; Sugiro olhar no manual do csh primeiramente se você está em algum lugar além da terra do Linux)~

Se você diz que CMD é um 'alias', então faça:

[alex@linux]$ %alias CMD

e repita o procedimento a partir do início com a primeira palavra que alias retornar. Se você diz que CMD é uma função (não no csh), execute:

[alex@linux]$ %typeset -f CMD

para ver sua definição; daqui para frente você está por si mesmo.

Se você está dando um caminho, então você pode estar justificado por estar irado. Ou talvez a documentação esteja em outro formato; continue lendo

IMPRIMINDO MAN PAGES

Você tem um par de opções aqui, dependendo se você não se importa de desperdiçar uma página inteira de papel para cada página de texto. Recomendamos imprimir as páginas de manual ao menos na metade do tamanho, como é improvável que você retorne a eles um mês depois.

A coisa mais simples e portável a fazer (apesar de existirem alternativas) é 

[alex@linux]$ %man -t MANPAGE > Manpage.ps

( Nota: somente funciona sozinho no Linux )

Isto produzirá um arquivo chamado Manpage.ps no seu diretório atual, no qual você pode então usar psnup (1) no SunOS para imprimir 2- ou 4- páginas para páginas físicas. 

Infelizmente, enquanto o parâmento -t é por si mesmo portátil para virtualmente todas implementações, a saída não é. No Linux, o comando acima funciona bem. No SunOS e Solaris, você tem que fazer algumas preparações primeiro: definir a variável de ambiente TCAT para ser 'cat' e TROFF para ser '/usr/local/bin/groff -man'. Além disto, a variável GROFF_TYPESETTER deve ser configurado para 'ps'.

Se você tem problemas em conseguir que o psnup funcione ou para não se sentir como tolo com isto, você pode a invés disto trabalhar com texto. Isto não é bem um texto, mas contêm negritos, sublimados e assim por diante mas o a2ps(1) entende insto, assim como  o less(1).

[alex@linux]$ %man MANPAGE|a2ps -m >MANPAGE.ps

Você não tem que produzir um arquivo ps se não quiser, é claro - se você estiver confiante que isto irá funcionar na primeira vez, substitua o '>MANPAGE.ps' por '|lpr -Pprinter-name'.

[alex@linux]$ %man MANPAGE|a2ps -m |lpr -Pprinter-name

Pessoalmente recomendo visualizar a saída com ghostview (1) antecipadamente.

VOCÊ REALMENTE QUER O MAN?

Nem toda documentação está localizada nas páginas de manual. As shells alguma vezes possuem ajuda online, assim como fazem outros programas, especialmente aqueles gráficos. Outras principais sistema de ajuda online incluem:

INFO

Info não é realmente complexo o suficiente para merecer ser descrito em detalhes. Rapidamente, você pode ler páginas info no emacs usando 'C-h i' ('info') ou pela linha de comando executando:

[alex@linux]$ % info

Ajuda online e um tutorial no sistema de info são disponíveis em ambas interfaces. Não desmereça páginas de informações, embora eles são usados ​​principalmente por software GNU, isso inclui informações tais páginas extremamente úteis como gdb, gcc, emacs, incompetente, e fazer. Perl e festa também têm páginas de informações, embora a informação está disponível por outros meios, bem como em seus casos.

/usr/doc

Somente disponíveis no Linux, e muitas vezes não é muito interessante, como um pacote de bem-comportado irá fornecer a documentação que pode ser integrado com os principais sistemas de ajuda. Ainda assim, há um monte lá, e deve definitivamente ser considerada se você não consegue encontrar o que está à procura de outro lugar. De particular interesse são os documentos para xv, debian, vim, wget, pqp, pinho, libq + + e HSC.
Os arquivos contidos aqui será geralmente de três tipos: HTML, postscript ou texto simples (ASCII). Nós vamos fazer a suposição de que você sabe como lidar com esses formatos. Use as informações contidas neste documento para ajudar a encontrar e ler sobre lynx(1), ghostview(1), and less(1)

/use/local/pkgs, /usr/local/doc, /usr/share, /usr/local/share

Estas são mais comuns para os servidores, embora possam existir em máquinas Linux também. Os pacotes de software são comumente instalados em:

/usr/local/pkgs/PKGNAME-VER#

e um link para o diretório é criado como:

/usr/local/pkgs/PKGNAME

Algumas vezes há documentação a serem encontradas aqui.  Documentação a qual é localizada em :

 /usr/doc/PKGNAME 

no Linux estão nestes diretórios no servidor, embora eles possam ser lincados ou copiados em outros diretórios mencionados acima ( /usr/local/doc, /usr/share, /usr/local/share )

Perldoc

Muita documentação Perl está inserida nos módulos fontes em si mesmo.  Para acessar você pode comumente executar:

[alex@linux]$ %perldoc MODULENAME

e a página do manual será gerado para você.

CÓDIGO FONTE E ARQUIVOS INCLUÍDOS

Enquanto isto ele provavelmente deve ser um último recurso, a fonte IS é sempre o mais atual e, por vezes, a única documentação disponível para um pacote específico. Esta não é geralmente instalado no sistema, a menos que ele não possa ser compilado: Por exemplo, scripts Perl e fonte Lisp são ambos interpretados, e assim o programa é a fonte. Quer ou não o programa que você está tentando aprender mais sobre ele está escrito em uma linguagem compilada ou interpretada. 

/Usr/include 

e

/usr/local/include 

podem ter arquivos muito úteis para ajudar.