Wikilivros

Linux Essencial/Lição Documentação do Linux

< Linux Essencial
  • Objetivo(s): Oferecer informações sobre como é feita a documentação do Linux.
  • Direitos autorais e licença: Veja notas de direitos autorais e licença no final da lição.

Introdução

editar

Uma das características que contribuiu para o sucesso do GNU/Linux é a sua vasta documentação, possuindo processos de criação e manutenção diferentes dos sistemas proprietários, e que contam com as seguintes características:

  • comunidade colaborativa além da documentação desenvolvida pelas equipes responsáveis pelos inúmeros aplicativos GNU, existe uma enorme comunidade dedicada à documentação. Nesse sentido, foi criado o projeto LDP - Linux Documentation Project [LDPa]- que além de apoiar o controle dos vários documentos, também congrega e ajuda a organizar as equipes de voluntários que se dedicam a documentar e a traduzir documentos. Nacionalmente existe um esforço, baseado em voluntários, denominado LDP-BR [LDPb], que faz a tradução dos vários documentos LDP.
  • dinamicidade geralmente os documentos ficam sob sistemas de controle de versão (VCS), no qual permite que o autor possa receber conteúdos adicionais e correções de outros colaboradores. Assim, o documento evolui continuamente acompanhando as mudanças de software e as necessidade dos usuários.
  • documentação padronizada apesar da variedade de programas e pessoas, os documentos são razoavelmente padronizados, utilizando geralmente formatos e ferramentas padrões.

Onde encontrar documentação

editar

Existem várias fontes de documentação em formato eletrônico no próprio sistema e na internet. Esta última, iremos tratar em uma seção seguinte, inclusive com indicação de sites. No próprio sistema, contamos com: a documentação própria disponível geralmente em /usr/doc (localização antiga) e /usr/share/doc (localização padrão); ajuda on-line do próprio aplicativo; utilitários de ajuda man e info;

Localize a documentação fornecida pelo aplicativo dpkg: 

# cd /usr/share/doc
ls -l| grep dpkg
drwxr-xr-x  2 root root 4096 2008-07-02 07:16 dpkg
drwxr-xr-x  2 root root 4096 2009-07-24 17:33 dpkg-dev
#  cd dpkg
 # ls
 AUTHORS              changelog.gz  README.api                       THANKS.gz
 changelog.Debian.gz  copyright     README.feature-removal-schedule  usertags.gz

Formatos mais utilizados

editar

Segue informações sobre os formatos de arquivos mais utilizados para documentação no GNU/Linux:

  • texto puro - texto em caracteres ASCII - gerais (README, LEIAME ou TXT); - instalação (INSTALL, TXT) e licenciamento (TXT, TXT).
  • HTML - HiperText Markup Language - é o formato codificado em caracteres ASCII, bastante popular, compatível com os navegadores e utilizado em páginas da internet.
  • SGML - é um formato codificado em ASCII, semelhante ao HTML (na verdade, HTML é um sub-tipo de SGML), porém é bastante flexível e permite fácil conversão para outros formatos. Não possui um visualizador padrão.
  • XML - eXtensible Markup Language - formato também parecido com o HTML. É um sub-tipo de SGML, e permite também uma fácil conversão para outros formatos. O subtipo XHTML já pode ser visualizado nas versões de navegadores mais recentes. Outro sub-tipo, denominado docbook, está também sendo muito utilizado para escrever documentação e deve tornar-se o formato padrão de documentos.
  • PDF - Portable Data Format - é um formato criado pela empresa Adobe, que tem a principal vantagem de utilizar suas próprias fontes de caracteres, mantendo sempre uma visualização idêntica em qualquer plataforma, computador ou sistema. Um documento neste formato pode ser visualizado através de aplicativos como o xpdf ou o evince no Linux, através do programa “Acrobat Reader” da própria Adobe ou através de plugins apropriados de seu navegador. Geralmente esse formato não é utilizado para ser editável, mas sim para ser visualizado; ou seja, edita-se nos outros formatos XML, SGML, etc, e gera-se o arquivo equivalente em PDF.
  • PS - postscript - é um formato também criado pela empresa Adobe, com a finalidade de reproduzir documentos em impressoras de alta qualidade gráfica, com suporte a postscript através de um interpretador. Assim como o PDF, esse formato não é utilizado para edição, mas sim para publicação de documentos, podendo ser visualizados com o utilitárioghostview. (http://www.adobe.com/products/postscript/?promoid=DTEHF - link visitado em 24/01/2011)
  • man - páginas de manual - são documentos em formato troff (veja a seção de links indicados) e visualizados através do comando man.
  • info - ou também chamado de texinfo, é um formato de páginas de ajuda, semelhante ao man, porém possui navegação por tópicos. Veremos mais adiante sobre o comando info.

Classificação de documentos

editar

Na comunidade GNU/Linux é comum utilizar alguns termos para classificar os documentos, baseando-se em seu objetivo:

  • How-to – ou, como fazer - como o próprio nome diz, é utilizado para instruir a fazer um determinado projeto ou tarefa. É mais voltado para objetivos didáticos, geralmente fornecendo procedimentos passo-a-passo, podendo também ser chamado de tutorial. Não importa seu tamanho, pois alguns chegam a centenas de páginas; porém alguns mais curtos, são chamados de mini-how-tos.
  • Manual ou guia - é mais específico que um how-to, e tem como objetivo principal ser uma fonte de referência sobre um tópico, sem muitos objetivos didáticos, fornecendo uma forma completa e fácil de encontrar toda a informação sobre determinado assunto.
  • FAQ - é um acrónimo de Frequently Asked Questions - ou perguntas frequentes - é um documento baseado em perguntas e respostas dos usuários.
  • man - ou páginas de manual - é o manual do comando ou arquivo disponibilizado através do comando man. Geralmente acompanha um pacote de software. Iremos tratar sobre oman mais a frente.

Páginas de manual e o comando man

editar

O man é um utilitário presente em todos os sistemas Unix e é utilizado principalmente para documentar sintaxe de comandos, arquivos de configuração e funções de programas. Esse comando apresenta informações em páginas armazenadas em arquivos de páginas de manual.

Instalação

editar

Por padrão, o utilitário man é instalado e os arquivos de páginas de manual são opcionalmente instalados, uma vez que ocupam espaço em disco. Você pode verificar se o programa e seus arquivos de página de manual foram instalados.

Verifique se o aplicativo e as páginas de manual foram instalados. 

#dpkg --get-selections |grep man

Verifique se os seguintes pacotes estão instalados:

  • man-db - é o pacote do utilitário man.
  • man-pages - é o pacote dos arquivos de páginas de manual.
  • man-pages-pt_BR - é o pacote dos arquivos das páginas de manual traduzidas em português do Brasil.

Utilização básica

editar

A forma de uso mais simples segue a seguinte sintaxe: 

man [objeto]

Quando citamos [objeto], estamos fazendo referência a um comando, função ou arquivo de configuração.

Por exemplo, execute: 

# man gzip
GZIP(1)                    GZIP(1)

NOME

       gzip, gunzip, zcat - compacta ou expande arquivos

SINOPSE

       gzip [ -acdfhlLnNrtvV19 ] [-S sufixo] [ nome ...]

       gunzip [ -acfhlLnNrtvV ] [-S sufixo] [ nome ...]

       zcat [ -fhLV ] [ nome ...  ]


DESCRIÇÃO

       O  gzip reduz o tamanho dos arquivos usando um código Lem-
       pel-Ziv (LZ77). Sempre que possível cada arquivo  é  sub-
       stituído    por  outro  com a extensão .gz, mantendo o dono,
       permissões e datas de modificação.  (A extensão   padrão é
       -gz  para  VMS,   z para MSDOS, FAT OS/2 , FAT Windows NT e
       Atari.) ...

...

OPÇÕES

       -a -ascii

         Modo  texto  ASCII: converte finais de linha usando
         conversões locais. Essa opção é  suportada  somente
         por  sistemas  não Unix. ->resumido<-

       -c --stdout --to-stdout
         Grava o resultado na saída padrão; mantém o arquivo
         original inalterado.  ->resumido<-

...

VEJA TAMBÉM

       znew(1), zcmp(1), zmore(1), zforce(1),  gzexe(1),  zip(1),

       unzip(1), compress(1), pack(1), compact(1)

...

TRADUÇÃO E REVISÃO PARA A LÍNGUA PORTUGUESA

       Sandro Nunes Henrique <sandro@conectiva.com.br> (tradução)

       Rodrigo Stulzer Lopes <rodrigo@conectiva.com.br> (revisão)

Foram acrescentados reticências (...) para indicar que parte do texto original foi extraído, com o intuito de apresentar para o leitor somente o que é de relevante interesse.

Como o man utiliza o comando less em segundo plano, para paginar (forma de visualizar o texto em etapas. Ex: resultado de um mecanismo de busca na internet como o Google, Yahoo e Bing) e controlar a informação em tela, você pode navegar por uma página de manual da mesma forma que se navega com o comando less:

h mostra um texto de ajuda.
q sai do texto.
/padrao procura dentro do texto todas as ocorrências de padrão especificado.
n repete a busca, indicando a próxima ocorrência do padrão encontrado.
N repete a busca, porém no sentido do fim para início do texto.

Além desses comandos, as teclas de PgUp, PgDown funcionam normalmente.

As páginas de manual são divididas em tópicos. Alguns tópicos são mais frequentes, tais como:

NOME indica a sua breve descrição, geralmente só em uma frase. Pode citar outros objetos (comandos) equivalentes ou bastante semelhantes. Por exemplo, várias funções do gzip são encontradas nos comandos gunzip e zcat.
SINOPSE quando o objeto é um comando, geralmente ele indica a sua sintaxe de uso. Essa parte é uma das mais importantes, podendo ser um pouco complexa em alguns casos. Saber interpretá-la é essencial para poder extrair o máximo de um comando. Uma seção dedicada a esse assunto foi criada e será apresentada mais à frente
DESCRIÇÃO é onde são fornecidas informações mais detalhadas sobre o objeto como seu uso, suas exceções, etc.
OPÇÕES é onde se documentam as opções do objeto, quando o objeto é um comando.
VEJA TAMBÉM é a seção utilizada para indicar outros objetos (comandos) afins ou semelhantes.
TRADUÇÃO E REVISÃO PARA A LÍNGUA PORTUGUESA é a seção utilizada para registrar os méritos da tradução e revisão da língua. Em alguns manuais também é mostrada a seção AUTHOR, que indica o autor do comando ou objeto.

Sintaxe de comandos

editar

Cada comando pode seguir sua própria sintaxe, mas em geral os seguintes símbolos padrões são utilizados:

hífen “-” ou dois hífens seguidos “- -” são utilizados para indicar uma opção. Por exemplo: “ls -l” e “ls --full-time”
colchetes “[]” são geralmente utilizados para indicar uma opção não-obrigatória. Por exemplo, a sintaxe do comando ls é indicada assim: ls [opções] [arquivo...]. Isso indica que você pode executar o comando isoladamente, com ou sem especificação de opções e arquivo.
chaves “{}” são geralmente utilizados para agrupar uma opção necessária. Por exemplo, a sintaxe do comando ls com a opção --sort é apresentada assim: [--sort={none, time, size, extension}]. Isso significa que uma vez utilizada a opção --sort, você deve necessariamente especificar o critério de ordenação (nenhum, tempo, tamanho ou extensão). Por exemplo, “ls -l --sort=size”, “ls -l --sort=time”
barra vertical “|” é utilizada para denotar opções excludentes entre si. Por exemplo, o comando tar possui a obrigatoriedade de utilizar uma das letras (ou palavra longa): A, c, d, r, t, u, x, conforme pode ser visto na especificação de sua sintaxe: tar [ - ] A --catenate --concatenete | c --create | d --diff --compare | r --append | t --list | u --update | x --extract --get ...
objeto sublinhado indica o argumento do comando. Por exemplo, note que o comando gzip sublinha a palavra nome, para denotar que nome é o argumento do comando. Veja a sintaxe: gzip [ -acdfhlLnNrtvV19 ] [-S sufixo] [ nome ...]
reticências sublinhadas “...” indica que o comando suporta vários objetos como argumento. Por exemplo, veja a especificação da sintaxe do comando mkdir: 'mkdir [opções] diretório... '. Isso indica que você pode executar: “mkdir dir1 dir2 dir3”. Esse comando irá criar os diretórios dir1, dir2 e dir3 em uma única linha de comando.

Seções

editar

Como foi dito, o man é utilizado geralmente para documentar comandos, mas também é possível documentar arquivos de configuração, funções de linguagem, etc. Para organizar essa variedade de objetos é que foram criadas as seções, cada uma com sua numeração específica.

Assim, a forma mais completa de se invocar o man é através da sintaxe: 

# man [seção] comando...

Por exemplo, verifique o manual do kill, seções 1 e 2: 

# man 1 kill

e 

# man 2 kill

Note que o primeiro comando lista o manual do comando kill e o segundo lista a função da linguagem C, kill ; pertencentes às primeira e segunda seções respectivamente. Quando não se especifica uma seção, por exemplo, man kill, a seção de menor número é apresentada primeiro.

Dessa forma foram padronizadas as seguintes seções:

Seção Descrição Exemplos
1 Comandos man 1 ls, man 1 gzip, etc.
2 Chamadas de sistema (funções fornecidas pelo kernel). man 2 fork, man 2 gettid, etc.
3 Chamadas de bibliotecas (funções fornecidas pelas bibliotecas do sistema). man 3 fgetc, man 3 malloc, etc.
4 Arquivos especiais (encontrados em /dev). man 4 fd, man 4 mouse, etc.
5 Arquivos de configuração. man 5 inittab, man 5 lilo.conf, etc.
6 Jogos. man 6 gnuchess, man 6 xboard, etc.
7 Protocolos, códigos de caracteres e outros. man 7 man, man 7 samba, etc.
8 Comandos de administração do sistema (comandos que somente root pode executar). man 8 mount, man 8 killall, etc.
9 Funções internas do kernel (desatualizadas) - procurou-se documentar o kernel nesta seção, porém essas páginas de manual ficaram desatualizadas e não são mais utilizadas.  

Essas informações podem ser obtidas no manual do próprio comando.

 

Arquivos man

editar

Os arquivos man são armazenados em diretórios específicos, definidos pela variável de ambiente MANPATH ou através do arquivo /etc/manpath.config.

Visualize o valor da variável MANPATH: 

#echo $MANPATH
/usr/lib/qt2/man:/usr/lib/kde3/man:/usr/local/man

Veja nesse exemplo, que os três diretórios listados, separados por dois-pontos (:) listam os três diretórios possíveis para se ter arquivos man.

O arquivo /etc/manpath.config indica a localização dos arquivos man através de chamadas à varável MANPATH. Veja o exemplo:

Visualize o conteúdo do arquivo /etc/manpath.config: 

#less /etc/manpath.config
...
MANPATH /usr/share/man
MANPATH /usr/man
MANPATH /usr/local/man
MANPATH /usr/X11R6/man
MANPATH /usr/lib/perl5/man 
...

Atualmente o diretório padrão onde são instalados os arquivos man é o diretório /usr/share/man.

Liste o diretório padrão dos arquivos do man: 

# ls /usr/share/man
es man man1 man2 man3 man4 man5 man6 man7 man8 man9 manl mann pt_BR whatis

Nesse exemplo, podemos notar:

  • diretórios de arquivos de manual: os diretórios man1, man2, man3, man4, man5, man6, man7, man8 e man9 são, respectivamente, arquivos man para as seções 1, 2, 3, 4, 5, 6, 7, 8 e 9.
  • diretórios de arquivos de manual de seções especiais: além das seções padrões de 1 a 9, podem existir seções especiais, neste exemplo, “l” e “n”. Nada impede que um pacote de software utilize uma seção particular. Por exemplo, a linguagem TCL geralmente utiliza a seção “n”; a execução de “man n exec” apresenta a descrição da função "exec" da linguagem TCL.
  • diretórios de arquivos de manual traduzidos: es e pt_BR - são respectivamente os arquivos de manual traduzidos para espanhol e português do Brasil. O man utiliza esses diretórios automaticamente através da variável LANG (veja o valor dessa variável através do comando “echo $LANG”). Por exemplo, caso essa variável tenha o valor “pt_BR”, então o diretório pt_BR será preferencial, ou seja, o man irá buscar pelo tópico procurado dentro do diretório pt_BR primeiro, para depois buscar no diretório pai /usr/share/man. Note que o sub-diretório pt_BR possui uma estrutura similar ao seu diretório pai; para verificar isso, execute “ls /usr/share/man/pt_BR”.
  • arquivo whatis: é o banco de dados do comando whatis. Veremos mais à frente o uso desse comando.

Os arquivos man ficam no diretório correspondente à sua seção, e em geral são compactados.

Liste o diretório padrão dos arquivos da seção 1 do man: 

# ls /usr/share/man/pt_BR/man1

A página de manual do comando gzip, é armazenada em /usr/share/man/pt_BR/man1/gzip.1.gz. Não há nenhum problema descompactar um arquivo man, pois o utilitário do comando pode utilizá-lo normalmente tanto compactado quanto descompactado.

Descompacte a página de manual do gzip e verifique se o man ainda consegue processá-lo: 

# man 1 gzip
# cd /usr/share/man/pt_BR/man1
 # gunzip gzip.1.gz
 # man 1 gzip

Esses arquivos são armazenados no formato troff ou groff (groff é a versão GNU do troff - veja mais sobre a história do troff na seção de links indicados).

Visualize o conteúdo do arquivo descompactado: 

# less /usr/share/man/pt_BR/man1/gzip.1

O groff é um pré-processador de texto que gera uma apresentação apropriada de um texto para ser mostrada em tela. Por exemplo, para transformar um arquivo em formato groffpara texto puro, você pode executar: 

# cd /usr/share/man/pt_BR/man1
# groff -mandoc -Tlatin1 gzip.1.

ou, utilizando em conjunto com o less: 

# groff -mandoc -Tlatin1 gzip.1 | less

A sua saída é semelhante à saída do comando man. O estudo do comando groff não será detalhado neste material, para maiores informações veja o site do groff nos links indicados.

Realizando buscas

editar

Você pode fazer uma busca em todo o banco de dados de páginas de manual por uma palavra-chave, através da opção -K. Porém esta opção é muito lenta quando a seção não é especificada.

Faça a busca pela palavra-chave hd, dentro da seção 4 (arquivos especiais): 

$ man 4 -K hd
/usr/share/man/pt_BR/man4/sd.4.gz? [ynq] n
/usr/share/man/pt_BR/man4/initrd.4.gz? [ynq] n
/usr/share/man/pt_BR/man4/hd.4.gz? [ynq] y
/usr/share/man/pt_BR/man4/console_ioctl.4.gz? [ynq] n
/usr/share/man/man4/console_ioctls.4.gz? [ynq] n
/usr/share/man/man4/unix.4.gz? [ynq] q

O man apresenta cada arquivo onde foi encontrada a palavra-chave, de forma interativa ('y' para abrir; 'n' para não abrir; e 'q' para sair).

Outra forma de pesquisar informações com resposta mais rápida - porém mais superficial - é através dos comandos whatis e apropos, que buscam informações nas descrições resumidas das páginas de manual, aquelas que são marcadas com o título “NOME”.

Execute o man para os comandos find e tar e identifique suas descrições resumidas, marcadas pelo título NOME: 

$ man find
...
NOME
       find - pesquisa arquivos em uma hierarquia de diretórios
...
$ man tar
...
NOME
       tar - a versão GNU do utilitário de arquivamento GNU
...

O banco de dados é gerado a partir do comando makewhatis, realizado de forma mais apropriada com a opção -w, que força a busca nos caminhos (paths) indicados pelo comando man. Caso seja executado simplesmente o comando sem parâmetros, será utilizada a variável MANPATH, que geralmente é uma listagem menos completa que os caminhos fornecidos pelo man. Em distribuições como Debian e Ubuntu esse comando não vem instalado tampouco pode ser instalado via repositório, no entanto o tarball pode ser baixado, compilado e instalado. Nessas distribuições o comando similar é mandb que faz o mesmo papel, porém com sintaxe diferente.

Execute o man para saber os caminhos das páginas de manual e em seguida, atualize o banco de dados whatis: 

# man manpath
/usr/local/man:/usr/man/pt_BR:/usr/man:/usr/X11R6/man/pt_BR:/usr/X11R6/man:...
# mandb

O processo de atualização do banco de dados whatis pode ser muito demorado.

Esse comando cria arquivos em formato texto (com nome whatis) espalhados por todos os caminhos indicados pelo man, que juntos, formam o seu banco de dados.

Liste algum caminho indicado pelo man e visualize o seu arquivo whatis: 

#ls -l /usr/man/share
...
-rw-r--r--    1 root     root      1452450 Jun 27 01:46 whatis
...
#less /usr/man/share/whatis
 *_unlocked [unlocked_stdio] (3)  - non-locking stdio functions
. [:]                (1)  - bash built-in commands, see bash(1)
. [alias]            (1)  - bash built-in commands, see bash(1)
...

Para fazer a busca no banco de dados whatis, deve ser usado o comando whatis ou apropos. O comando whatis exige o fornecimento no nome exato do objeto. De forma mais flexível e abrangente, o comando apropos procura por ocorrência parcial no nome do objeto ou na descrição resumida.

Execute o comando whatis para as palavras-chave copy e cp: 

$ whatis copy
copy: nothing appropriate
$ whatis cp
cp                   (1)  - copia arquivos e diretórios
cp                   (1)  - copy files and directories

Note que o comando copy não existe, por isso o retorno da mensagem “copy: nothing appropriate”. No entanto, o fornecimento exato da palavra-chave cp retornou prontamente as descrições resumidas em português e inglês do comando cp.

Execute o comando apropos para a palavra-chave copy: 

# apropos copy
...
glCopyPixels         (3x)  - copy pixels in the frame buffer
glCopyTexImage1D     (3x)  - copy pixels into a 1D texture image
glCopyTexImage2D     (3x)  - copy pixels into a 2D texture image
glCopyTexSubImage1D  (3x)  - copy a one-dimensional texture subimage
...

Note que o comando apropos atua de forma diferente do comando whatis, retornando várias descrições resumidas de comandos, pois ele encontra várias ocorrências (parciais ou não) da palavra-chave copy, tanto no nome do objeto (comando) quanto nas descrições resumidas.

Ajuda on-line de comandos

editar

A chamada da ajuda on-line pode variar de um comando para outro, dependendo apenas do seu criador, sendo que a forma mais comum de uso é: 

nome_comando --help

ou 

nome_comando -h

Invoque a ajuda on-line do comando dpkg: 

# dpkg --help

O comando acima retorna uma ajuda rápida e resumida. Para rolagem da tela deverão ser usadas as teclas shift+Page-up (para subir a tela) ou shift+Page-down (para descer a tela). Caso você queira, é possível utilizar um paginador como o less, que permite melhor controle do resultado.

Invoque a ajuda on-line do comando dpkg, com o paginador less: 

# dpkg --help | less
Uso: dpkg [<opção> ...] <comando>

Commands:
  -i|--install       <.deb file name> ... | -R|--recursive <directory> ...
  --unpack           <.deb file name> ... | -R|--recursive <directory> ...
  -A|--record-avail  <.deb file name> ... | -R|--recursive <directory> ...
  --configure|--triggers-only <package> ... | -a|--pending
  -r|--remove        <package> ... | -a|--pending
  -P|--purge         <package> ... | -a|--pending
  --get-selections [<pattern> ...] Get list of selections to stdout
  --set-selections                 Set package selections from stdin
  --clear-selections               Deselect every non-essential package
  --update-avail <Packages-file>   Replace available packages info
  --merge-avail <Packages-file>    Merge with info from file
  --clear-avail                    Erase existing available info
  ...

Quando o comando não implementa as opções -h ou --help, geralmente ele mostra uma mensagem de erro, seguido da forma de uso.

Invoque a ajuda on-line do comando shutdown, com opções '-h'ou '--help': 

# shutdown -h

less ou 

# shutdown --help

shutdown: invalid option -- -

Usage:     shutdown [-akrhfnc] [-t secs] time [warning message]
        -a:      use /etc/shutdown.allow
        -k:      don't really shutdown, only warn.
        -r:      reboot after shutdown.
        -h:      halt after shutdown.
        -f:      do a 'fast' reboot (skip fsck).
...

Info

editar

Outra forma de se obter ajuda para um programa ou arquivo é o outro sistema de documentação denominado info ou texinfo. O info é mais vantajoso para conteúdos de ajuda de maior tamanho, pois ele possui várias funcionalidades de navegação como: atalho para a página anterior ou seguinte, referências cruzadas e índice. Além disso, ele é também licenciado sob a GPL e é o sistema de documentação padrão do projeto Gnu.

Os arquivos de leitura do info se encontram dentro do diretório /usr/share/info. Assim como os arquivos do man, seus arquivos também são compactados, visando economia de espaço em disco. Para saber se a ferramenta está instalada, execute o seguinte comando: ' dpkg --get-selections | grep info'. Se não estiver, será necessário a instalação desse pacote info. Os arquivos no formato info, diferentemente do man, são instalados por pacotes específicos de cada aplicativo.

Invoque o info: 

$ info

Note que o info apresenta todos os seus tópicos, diferentemente do man que não possui esta listagem. Para sair, você deve clicar 'Q' de quit (sair). Também é possível executar o comando, abrindo diretamente o tópico desejado.

Invoque o info para o comando cpio: 

$ info cpio

File: cpio.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)

Note que a primeira linha mostrada é o menu do info, que indica o arquivo info (File: cpio.info), o nó atual (Node: Top), a página seguinte (Next: Introduction), a página anterior (Prev: (dir)) e o nó pai (Up: (dir)).

Note que ele também abre a página de manual (man) correspondente a um tópico solicitado, quando a página no formato texinfo não existe.

Abra alguma página de manual com o info e com o man: 

$ info bash
$ man bash

 

Note no menu do info, que a página atual está no formato man (File: manpages).

 

Para aqueles que conhecem o editor de texto emacs, irão perceber as suas semelhanças com os comandos do info. Em geral, os comandos não possuem diferenciação de maiúsculas e minúsculas. O quadro abaixo apresenta alguns dos comandos básicos utilizados:

Tecla Funcao
<CTRL>+h Abre uma nova tela de help de todos os comandos do info. A tecla 
<CTRL>+x 0 Fecha a janela de ajuda. 0 é o número da janela adicional de ajuda.
d ou t Vai direto para a página inicial. É o equivalente ao “home” de seu navegador. D vem de Dir e T vem de Top.
n Página seguinte (Next). Note a semelhança da navegação tipo livro.
p Página anterior (Prev). Note a semelhança da navegação tipo livro.
u Vai para o nó pai (Up). É o equivalente ao “voltar” ou “back” de seu navegador.
/ Faz a busca por uma palavra na página atual. É semelhante ao comando de busca do vi. Infelizmente não existe uma busca em todo o banco de dados info.
<CTRL>+x n Continua a busca. É semelhante ao comando 'n' do vi.

Você pode acessar uma referência cruzada (nó) quando a linha inicia com um asterisco (*).

Execute o info e acesse a referência cruzada '* File utilities: (fileutils)': 

$ info
...
* File utilities: (fileutils).  GNU file utilities.
...

Tente também testar os comandos de navegação: u, p, n e d.

Documentação na Internet

editar

A Internet fornece uma grande variedade de documentação, de várias formas e meios: históricos de listas de discussão, histórico de news, fóruns on-line, FAQs, dicas, mini-how--tos, artigos, how-tos, guias, livros completos , etc.

Geralmente o maior desafio não é a falta de documentação, mas filtrar e selecionar a melhor informação. Portanto, para realizar uma busca eficiente, é importante você conhecer as melhores fontes de informação, além de saber executar uma boa pesquisa em mecanismos de busca. Seguem aqui algumas dicas:

  • 1. Documentação traduzida em português: caso você tenha problemas em compreender textos em inglês, é importante que você conheça e já colecione endereços de seus sites favoritos. Há muita fonte de informação em português, alguns sugeridos: Linux Brasil [LIBa], LDP-BR [LDPb], Debian-BR [DDBb], Dicas-L [DILa] e RAU-TU Linux [RAUa].
  • 2. Assunto específico da distribuição: em alguns momentos, você poderá necessitar de informações específicas da sua distribuição. As distribuições em geral também fornecem documentação específica, principalmente aspectos de instalação e administração. Veja alguns dos sugeridos: Conectiva [DCNa], Debian [DDBa], Red Hat [DRHa] e Slackware [DSLa].
  • 3. Projeto de Documentação do Linux: caso seu assunto seja mais genérico, você pode procurar por mini-how-tos, FAQs, How-tos e guias no site do Projeto de Documentação do Linux - _Linux Documentation Project_- , ou simplesmente LDP [LDPa].
  • 4. Sites de busca: existem vários sites de busca muito bons, nos quais você sempre terá de especificar um bom critério de busca para que não sejam retornados muitos resultados desnecessários. Quando for procurar por alguma solução para um problema que o sistema reportou, tente especificar também a frase de erro, por exemplo, ao invés de buscar utilizando as palavras warning, using, insecure, memory, tente utilizar a frase de erro entre aspas “warning: using insecure memory” ; isso geralmente melhora a qualidade dos resultados. Procure também utilizar diretórios específicos [GOLa] para que o retorno seja específico, ou que sua busca fique restrita a grupos de news [GOLb].
  • 5. Site oficial: Geralmente os sites oficiais do aplicativo fornecem documentações adicionais. Para encontrar o site oficial de um aplicativo, o melhor procedimento é utilizar um mecanismo de busca de aplicativos, tal como o Freshmeat [FREa].
  • 6. Sites gerais de notícias: Vários sites se dedicam a fornecer notícias atualizadas de Linux. Alguns dos mais populares brasileiros são: Linux Brasil [LIBa], Linux Security Brasil [LSBa] e O Linux [OLIa]. Alguns dos mais populares em inglês são: Linux Gazette [LIGa], LWN.net [LWNa], Linux World [LIWa] e Linux Focus [LIFa].

Perguntas frequentes

editar
  • 1. É possível transformar páginas de manual em texto puro?
    • Se você desejar salvar uma página de manual em arquivo texto puro, o ideal é executar o comando: “groff -mandoc -Tlatin1 gzip.1 | col -b > /tmp/gzip.txt”. Nesse exemplo, estamos utilizando o comando col para filtrar os vários tipos de caracteres especiais utilizados na paginação da tela (cores, negrito, espaçamentos especiais, etc).
  • 2. É possível transformar páginas de manual em formato HTML?
    • Você pode converter suas páginas de manual em formato HTML através do utilitário man2html. Ele foi criado por Earl Hood e pode ser baixado emhttp://www.oac.uci.edu/indiv/ehood/man2html.html. Para instalá-lo você pode executar o aplicativo de instalação install.me fornecido com o pacote: perl install.me ou via pacotes caso esteja disponível no repositório. Para utilizá-lo, você tem que executar: 'gzip -dc $(man -w gzip) | man2html > gzip.html'. Esse comando irá gerar as páginas de manual do comando gzip armazenando o arquivo /tmp/gzip.html.
  • 3. Como criar uma página de manual?
    • Você pode conhecer melhor a sintaxe das páginas de manual, podendo até criar as suas próprias, através da documentação fornecida pelo man. Para conhecer mais sobre o formato do man, execute “man 7 man”.
  • 4. Como exportar arquivos info em outros formatos?
    • O comando makeinfo permite transformar arquivos-fonte texinfo (geralmente extensão .texi) para os formatos info (geralmente extensão .info, utilizado pelo aplicativo info), texto puro, html, xml-docbook e xml-texinfoml. Portanto, a melhor maneira de transformar um arquivo info em outro formato é obter primeiramente o seu arquivo-fonte info. Depois você pode executar o comando makeinfo, para transformá-lo no formato desejado. Por exemplo, para transformar o arquivo cpio.texi em cpio.html, basta executar: 'makeinfo --html cpio.texi'. Execute 'man makeinfo' ou 'info makeinfo' para saber mais detalhes.
  • 5. Como criar um documento info?
    • O próprio info possui uma documentação completa do formato de seu arquivo, para acessar execute 'info texinfo'.
  • 6. Como contribuir com a LDP-BR?
    • O site da LDP-BR criou uma página de instruções para participar como voluntário [LDBc].
editar
  • [LDP] - LDP - Linux Documentation Project
  • [LDP-BR] Projeto de Documentação do Linux - Brasil
  • [DDB] - Documentação da distribuição Debian
  • [DIL] - Dicas-l - Site de dicas de Linux da Unicamp
    • a. http://www.dicas-l.com.br/
    • É um site originado de uma lista de discussão bem sucedida e ainda em atividade. É baseado em dicas, classificadas por assuntos. Também disponibiliza indicações de links, artigos e cursos.
  • [DRH] - Documentação da distribuição Red Hat
  • [DSL] - Documentação da distribuição Slackware
  • [FRE] - Freshmeat - Catálogo de projetos e aplicativos
  • [GOL] - Google Linux - diretório específico para assuntos relacionados à Linux
    • a. http://www.google.com/linux
    • b. http://groups.google.com
    • O site Google é um dos mais bem sucedidos mecanismos de busca. Ele possui um diretório específico para linux (a) e também busca em grupos de news (b), que geralmente retorna informações mais técnicas.
  • [INF] - Texinfo - o sistema de documentação GNU
    • a. http://www.gnu.org/software/texinfo
    • Este é o site oficial do sistema de documentação /. Além de oferecer as documentações oficiais e tutoriais, também fornece indicação de conversores para outros formatos.
  • [LDP] - Linux Documentation Project - Projeto de Documentação do Linux
    • a. http://www.tldp.org
    • b. http://linux-br.conectiva.com.br/mailman/listinfo/ldp-br
    • É o projeto mais bem sucedido de documentação do Linux, mantido por voluntários. Possui uma miscelânea de mini-howtos, FAQs, how-tos e até livros completos, na maioria licenciados como documentos livres. O link (a) é a versão internacional e o (b) é a versão brasileira com vários documentos traduzidos.
  • [LIB] - Linux in Brazil - Site de Augusto Campos
    • a. http://linux.trix.net
    • É um site mantido por Augusto Campos, colunista da Revista Do Linux. Sempre possui notícias atualizadas, possui uma coluna de dicas e indicação de artigos bastante interessantes.
  • [LIFa] - Linux Focus - Site de notícias em inglês
    • a. http://www.linuxfocus.org
    • É um site mantido por vários voluntários, com projeto interessante de tradução em português que está em andamento.
  • [LIG] - Linux Gazette - Site de notícias em inglês
    • a. http://www.linuxgazette.com
    • É um site de notícias não comercial, livremente disponível. Permite baixar com facilidade as edições anteriores. Suas notícias são de bom nível e originais.
  • [LIW] - Linux World - Site de notícias em inglês
    • a.http://www.linuxworld.com
    • Seu conteúdo é disponibilizado publicamente. Tem objetivo comercial e os seus artigos são bem escritos e de bom nível técnico.
  • [LWN] - LWN.net - Site de notícias em inglês
    • a. http://lwn.net
    • Seu conteúdo é livre, mas algumas notícias são obtidas por meio de assinatura de recebimento semanal de notícias.
  • [LSB] - Linux Security Brasil - Site brasileiro voltado para segurança em Linux
  • [OLI] - O Linux - Site brasileiro voltado para Linux em geral
    • a. http://www.olinux.com.br
    • Tem um leyoute bem funcional que permite uma ótima navegabilidade. O destaque vai para as entrevistas, artigos e material para cursos.
  • [TRO] - Troff - Processador de texto utilizado nas páginas de manual
    • a. http://www.troff.org
    • Quando um tipógrafo (typesetter) monta um conjunto de tipos (peças de letras em metal) para montar uma página para ser impressa, ele realiza um serviço análogo ao aplicativo troff, que adequa um texto em uma página de tamanho variável - consistindo na hifenização, quebra de linhas - no sentido de aproveitar o máximo possível do espaço disponível. Daí vem o seu nome typesetter run off.
  • [RAU] - RAU-TU Linux - Site com sistema tira-dúvidas
    • a. http://www.rau-tu.unicamp.br/linux
    • Sistema Web mantido pela Unicamp que permite postar dúvidas em tópicos específicos de Linux, com aviso automático para os colaboradores, controle de qualidade da resposta, aviso de resposta para o solicitante e busca para dúvidas já postadas.

Termos utilizados

editar
Banco de dados man
é o conjunto de arquivos no formato apropriado para o aplicativo man.
Banco de dados whatis
é o conjunto de arquivos whatis, gerado pelo utilitário makewhatis e utilizado pelo comando whatis.
FAQ
ou Frequently Asked Questions - perguntas frequentes - são documentos organizados por perguntas e respostas.
How-to
ou como-fazer, são documentos que descrevem detalhadamente como realizar determinada operação. Geralmente são práticos, como o próprio nome diz. Página de manual: oumanpage, é uma página gerada pelo man. Esse termo também é utilizado para denominar um arquivo do banco de dados man.
PDF
é o formato de documentos criado pela empresa Adobe, assim como o postscript. Também possui independência de plataforma.
Postscript
é um formato de documentos independentes de plataforma, ou seja, sem variações de estilos ou tamanhos de fontes em S.O.s diferentes, não perdendo a diagramação original do documento.
Seção do man
são classificações das páginas de manual por assunto.
SGML
é um formato de documento em texto puro baseado em tags, que inclusive originou o HTML. A sua principal vantagem é a facilidade de compilação para outros formatos como ps, HTML, rtf, etc. [http://pt.wikipedia.org/wiki/SGML]
Sistema de Controle de Versão (VCS)
é um sistema de controle de versões de documentos - originalmente utilizada para código-fonte de programas, que permite organizar o trabalho de edição colaborativa, controlando as modificações entre versões diferentes.
Texinfo
ou info , é um utilitário de documentação, assim como o man.
XML
é também outro formato originado do SGML que pode definir seu próprio conjunto de tags, sendo uma delas o docbook, que é bastante completo e tende a ser o padrão mais utilizado para documentos.

Exercícios de Revisão

editar

1. Como visualizar os documentos em formato PDF e postscript?

2. O que é how-to? E FAQ?

3. Quais são as seções do man?

4. Cite três diferenças entre o man e o info.

5. Qual é a função da opção “--help” para comandos? Ele funciona para todos os comandos?

6. Qual é a utilidade do comando whatis? Qual é a sua diferença com apropos?

7. Localize nas páginas de manual, a seção e o comando necessários para obter informação sobre:

a) hd (dispositivo de bloco)

b) o próprio man

c) arquivos fstab, lilo.conf e inittab

d) programação bash

8. Localize no info informações sobre cada um dos comandos abaixo e verifique também se existe documentação equivalente nas páginas de manual:

a) diff

b) mtools

c) find

d) wget

9. Localize na Internet os endereços de dois How-tos sobre o kernel.

10. Localize na Internet um FAQ de Linux em geral.

Obtido em "https://pt.wikibooks.org/w/index.php?title=Linux_Essencial/Lição_Documentação_do_Linux&oldid=288174"