Opções gerais¶

-C arquivo, --config-file=arquivo

Usa esse arquivo de configuração de usuário em vez do padrão ~/.manpath.

-d, --debug

Emite mensagens de depuração.

-D, --default

Essa opção normalmente é chamada como a primeira opção e redefine o comportamento do man para seu padrão. Seu uso é para redefinir aquelas opções que podem ter sido definidas no $MANOPT. Quaisquer opções que venham após -D terão seu efeito comum.

--warnings[=avisos]

Habilita avisos do groff. Isso pode ser usado para realizar verificações de sanidade no texto fonte de páginas de manual. avisos é uma lista separada por vírgulas de nomes de avisos; se ela não for fornecida, o padrão é "mac". Veja o nó “Warnings” em info groff para uma lista de nomes de avisos disponíveis.

Modos principais de operação¶

-f, --whatis

Equivalente a whatis. Exibe uma descrição curta da página de manual, se disponível. Veja whatis(1) para detalhes.

-k, --apropos

Equivalente a apropos. Pesquisa as descrições curtas de página de manual para palavras-chave e exibe quaisquer correspondências. Veja apropos(1) para detalhes.

-K, --global-apropos

Pesquisa por texto em todas as páginas de manual. Essa é uma pesquisa de força bruta, e é provável que leve algum tempo; se possível, você deveria especificar uma seção para reduzir o número de páginas que precisam ser pesquisadas. Termos de pesquisa podem ser textos simples (o padrão) ou expressões regulares se a opção --regex for usada.

Note que isso pesquisa os fontes das páginas de manual, não o texto renderizado e, portanto, pode incluir falso positivos em razão de coisas como comentários nos arquivos-fontes. Pesquisar o texto renderizado seria ainda mais lento.

-l, --local-file

Ativa o modo "local". Formata e exibe arquivos locais de manual em vez de pesquisar na coleção de manuais do sistema. Cada argumento de página de manual será interpretado como um arquivo-fonte nroff no formato correto. Nenhum arquivo cat é produzido. Se "-" é listado como um dos argumentos, a entrada será obtida de stdin (entrada padrão). Quando essa opção não é usada, e o man falha em localizar a página solicitada, antes de exibir a mensagem de erro, ele tenta agir como se essa opção tivesse sido fornecida, usando o nome como um nome de arquivo e procurando por uma correspondência exata.

-w, --where, --path, --location

Não exatamente exibe as páginas de manual, mas imprime o local dos arquivos-fonte nroff que seriam exibidos. Se -a também for especificado, imprime os locais de todos os arquivos-fonte que correspondem aos critérios de pesquisa.

-W, --where-cat, --location-cat

Não exatamente exibe as páginas de manual, mas imprime o local dos arquivos cat pré-formatados que seriam exibidos. Se -a também for especificado, imprime os locais de todos os arquivos-fonte que correspondem aos critérios de pesquisa.

Se -w e -W forem ambos usados, imprime o arquivo-fonte e o aquivo cat separados por um espaço. Se todos os -w, -W e -a forem usados, faz isso para cada correspondência possível.

-c, --catman

Essa opção não é para uso geral e deve ser usado apenas pelo programa catman.

-R codificação, --recode=codificação

Em vez de formatar a página de manual na forma normal, emite seu fonte convertido para a codificação especificada. Se você já sabe a codificação do arquivo-fonte, você também pode usar manconv(1) diretamente. Porém, essa opção permite que você converta várias páginas de manual para uma única codificação sem ter que declarar explicitamente a codificação de cada uma, desde que elas já tenham sido instaladas em uma estrutura similar a uma hierarquia de página de manual.

Considere usar man-recode(1) para converter várias páginas de manual, pois ele possui uma interface projetada para conversão em massa e, portanto, pode ser muito mais rápido.

Localizando as páginas de manual¶

-L localidade, --locale=localidade

man geralmente vai determinar sua localidade atual por uma chamada à função C setlocale(3), a qual pergunta a várias variáveis de ambiente, possibilitando incluir $LC_MESSAGES e $LANG. Para temporariamente substituir o valor determinado, use essa opção para fornecer uma localidade diretamente para man. Note que isso não surtirá efeito até que a pesquisa por páginas seja iniciada. Saída como a mensagem de ajuda sempre será exibida na localidade inicialmente determinada.

-m sistema[,...], --systems=sistema[,...]

If this system has access to other operating systems' manual pages, they can be accessed using this option. To search for a manual page from NewOS's manual page collection, use the option -m NewOS.

O sistema especificado pode ser uma combinação de nomes de sistemas operacionais delimitados por vírgula. Para incluir uma pesquisa às páginas de manual do sistema operacional nativo, inclua man como nome do sistema no texto do argumento. Essa opção vai sobrescrever a variável de ambiente $SYSTEM.

-M caminho, --manpath=caminho

Especifica um caminho man a ser usado. Por padrão, man usa um código derivado de manpath para determinar o caminho a ser pesquisado. Essa opção sobrescreve a variável de ambiente $MANPATH e faz com que a opção -m a ser ignorada.

O caminho especificado como um caminho man deve ser a raiz de uma hierarquia estruturada de páginas de manual para as seções conforme descrito no manual de man-db (sob "The manual page system"). Para visualizar páginas de manual fora de tais hierarquias, veja a opção -l.

-S lista, -s lista, --sections=lista

A lista dada é uma lista separada por caractere de vírgula ou de dois pontos com seções, usada para determinar quais seções para pesquisar e em qual ordem. Essa opção sobrescreve a variável de ambiente $MANSECT. (A escrita de -s é para compatibilidade com System V.)

-e subextensão, --extension=subextensão

Alguns sistemas incorporam pacotes grandes de páginas de manual, como aquelas que acompanham o pacote Tcl, à hierarquia principal de páginas de manual. Para contornar o problema de ter duas páginas de manual com o mesmo nome como exit(3), as páginas Tcl geralmente eram atribuídas à seção l. Como isso não é uma boa ideia, agora é possível colocar as páginas na seção correta, e atribuir uma "extensão" específica a elas (ex.: exit(3tcl). Sob operação normal, man exibirá exit(3) como preferência em relação a exit(3tcl). Para negociar essa situação e para evitar de ter que saber em qual seção de página você deseja está, agora é possível fornecer ao man um texto subextensão indicando a qual pacote a página deve pertencer. Usando o exemplo acima, fornecer a opção -e tcl para man vai restringir a pesquisa a páginas tendo uma extensão de *tcl.

-i, --ignore-case

Ignora diferença maiúsculo/minúsculo para páginas de manual. Esse é o padrão.

-I, --match-case

Pesquisa por páginas de manual diferenciando maiúsculo/minúsculo.

--regex

Mostra todas as páginas com qualquer parte de seus nomes ou suas descrições correspondendo a cada argumento de página como uma expressão regular, como ocorre com apropos(1). Já que geralmente não há uma forma razoável de pegar a "melhor" página ao pesquisar por uma expressão regular, essa opção resulta em -a.

--wildcard

Mostra todas as páginas com qualquer parte de seus nomes ou suas descrições correspondendo a cada argumento de página usando caracteres curingas do tipo shell, como ocorre com a opção --wildcard de apropos(1). O argumento de página deve corresponder ao nome completo ou descrição completa, ou corresponder a limites de uma palavra na descrição. Já que geralmente não há uma forma razoável de pegar a "melhor" página ao pesquisar por um curinga, essa opção resulta em -a.

--names-only

Se a opção --regex ou --wildcard for usada, corresponde apenas a nomes de páginas, e não a descrições de páginas, como ocorre com whatis(1). Do contrário, nenhum efeito.

-a, --all

Por padrão, man sairá após exibir a página de manual encontrada que seja mais adequada. Usar essa opção força man a exibir todas as páginas de manual com nomes que correspondam aos critérios de pesquisa.

-u, --update

Essa opção faz com que man atualize os caches de seus banco de dados das páginas de manual instaladas. Isso é necessário apenas em situações raras e, normalmente, é melhor executar mandb(8).

--no-subpages

Por padrão, man tentará interpretar pares de nomes de página de manual fornecidos na linha de comando como equivalentes a um único nome de página de manual contendo um hífen ou sublinhado. Isso oferece suporte ao padrão comum de programas que implementam uma gama de subcomandos, permitindo-lhes fornecer páginas de manual para cada um que possam ser acessadas usando sintaxe similar ao que seria usado para invocar os próprios subcomandos. Por exemplo:

  $ man -aw git diff
  /usr/share/man/man1/git-diff.1.gz

Para desabilitar esse comportamento, use a opção --no-subpages.

  $ man -aw --no-subpages git diff
  /usr/share/man/man1/git.1.gz
  /usr/share/man/man3/Git.3pm.gz
  /usr/share/man/man1/diff.1.gz

Controlando saída formatada¶

-P paginador, --pager=paginador

Especifica qual paginador de saída deve ser usado. Por padrão, man usa pager, usando subsidiariamente o cat se o pager não for localizado ou não for um executável. Essa opção sobrescreve a variável de ambiente $MANPAGER, a qual, por sua vez, sobrescreve a variável de ambiente $PAGER. Ela não é usada em conjunto com -f ou -k.

Esse valor pode ser um único nome de comando ou um comando com argumentos, e pode usar barra invertida, aspas simples ou aspas duplas, como no shell. Ele não pode usar "pipes" para conectar múltiplos comandos; se você precisar disso, use um script "wrapper", que pode levar o arquivo e exibir como um argumento ou na entrada padrão.

-r prompt, --prompt=prompt

Se uma versão recente do less for usada como paginador, man tentará definir seu prompt e algumas opções sensíveis. O prompt padrão se parece com

Manual pagel nome(seção) line x

sendo que nome denota o nome da página de manual, seção denota a seção sob a qual foi encontrada e x é o número da linha atual. Isso é alcançado usando a variável de ambiente $LESS.

Fornecer -r com um texto sobrescreverá esse padrão. O texto pode conter $MAN_PN que será expandido para o nome da página manual atual e o nome de sua seção envolto por "(" e ")". O texto usado para produzir o padrão poderia se expressado com

\ Manual\ page\ \$MAN_PN\ ?ltline\ %lt?L/%L.:
byte\ %bB?s/%s..?\ (END):?pB\ %pB\\%..
(press h for help or q to quit)

Ele é quebrado aqui em três linhas apenas para melhor legibilidade. Para seu significado, veja a página de manual do less(1). O texto do prompt é primeiro avaliado pelo shell. Todas as ocorrências de aspa dupla, acento grave e barra invertida no prompt devem ser escapadas por uma barra invertida. O texto do prompt pode terminar em um $ escapado, o qual pode ser seguido por outras opções para o less. Por padrão man define as opções -ix8.

A variável de ambiente $MANLESS descrita abaixo pode ser usada para definir um texto padrão de prompt se nenhuma for fornecida na linha de comando.

-7, --ascii

Ao visualizar uma página de manual em ascii(7) puro em um terminal de 7 bits ou emulador de terminal, alguns caracteres podem não ser exibidos corretamente quando se usa a descrição de dispositivo com latin1(7) com GNU nroff. Essa opção permite que páginas de manual em ascii puro seja exibidas em ascii com o dispositivo latin1. Nenhum texto em latin1 será traduzido. A tabela a seguir mostra as traduções realizadas: algumas partes dela só podem ser exibidas adequadamente usando um dispositivo latin1(7) do GNU nroff.

Descrição	Octal	latin1	ascii
hífen de continuação	255	‐	-
ponto lista (ponto no meio)	267	•	o
acento agudo	264	´	'
sinal de multiplicação	327	×	x

Se a coluna em latin1 é exibida corretamente, seu terminal pode estar configurado para caracteres latin1 e essa opção não é necessária. Se as colunas latin1 e ascii são idênticas, você está lendo essa página usando essa opção ou man não formatou essa página usando uma descrição de dispositivo latin1. Se a coluna latin1 estiver faltando ou corrompida, você pode precisar ver as páginas de manual com essa opção.

Essa opção é ignorada ao usar as opções -t, -H, -T ou -Z e pode ser inútil para nroff que não seja do GNU.

-E codificação, --encoding=codificação

Gera a saída para uma codificação de caracteres diversa do padrão. Para compatibilidade reversa, codificação pode ser um dispositivo nroff tal como ascii, latin1 ou utf8 assim como uma codificação de caracteres de verdade, como UTF-8.

--no-hyphenation, --nh

Normalmente, nroff vai hifenizar automaticamente o texto na quebra de linha mesmo em palavras que não contêm hífenes, se isso for necessário para manter palavras em uma linha sem espaçamento excessivo. Essa opção desabilita hifenização automática, de forma que as palavras serão hifenizadas somente se elas já contiverem hífenes.

Se você está escrevendo uma página de manual e só deseja evitar que nroff hifenize uma palavra em um ponto inapropriado, não use essa opção; em vez disso, consulte a documentação do nroff. Por exemplo, você pode colocar "\%" dentro de uma palavra para indicar que ela pode ser hifenizada naquele ponto ou colocar "\%" no começo de uma palavra para evitar que ela seja hifenizada.

--no-justification, --nj

Normalmente, nroff justificará automaticamente um texto em ambas margens. Essa opção desabilita toda justificação, deixando como justificada apenas a margem esquerda, o que é chamado de texto "ragged-right" em inglês.

Se você está escrevendo uma página de manual e só deseja evitar que nroff justifique certos parágrafos, não use essa opção; em vez disso, consulte a documentação do nroff. Por exemplo, você pode usar as requisições ".na", ".nf", ".fi" e ".ad" para temporariamente desabilitar ajuste de preenchimento.

-p texti, --preprocessor=texto

Especifica a sequência de pré-processadores a serem executados antes de nroff ou troff/groff. Nem todas instalações terão um conjunto completo de pré-processadores. Alguns dos pré-processadores e das letras usadas para designá-los são: eqn (e), grap (g), pic (p), tbl (t), vgrind (v), refer (r). Essa opção sobrescreve a variável de ambiente $MANROFFSEQ. zsoelim é sempre executado como o primeiro pré-processador.

-t, --troff

Usa groff -mandoc para formatar a página manual para stdout (saída padrão). Essa opção não é necessária em conjunto com -H, -T ou -Z.

-T[dispositivo], --troff-device[=dispositivo]

Essa opção é usada para alterar a saída do groff (ou, possivelmente, troff) para ser adequado para um dispositivo diferente do padrão. Essa opção resulta em -t. Exemplos (com Groff-1.17) incluem dvi, latin1, ps, utf8, X75 e X100.

-H[navegador], --html[=navegador]

Essa opção fará com que groff produza uma saída HTML e exiba-a em um navegador web. A escolha do navegador é determinada pelo argumento opcional navegador, caso este seja fornecido, obtido pela variável de ambiente $BROWSER ou por um padrão em tempo de compilação, se a primeira alternativa não estiver definida (geralmente lynx). Essa opção resulta em -t e funcionará apenas com o GNU troff.

-X[dpi], --gxditview[=dpi]

Essa opção exibe a saída de groff em uma janela gráfica usando o programa gxditview. O dpi (pontos por polegada ou, em inglês, "dots per inch") pode ser 75, 75-12, 100 ou 100-12, tendo como padrão o 75; as variantes -12 usam uma fonte de base de 12 pontos. Essa opção resulta em -T com o dispositivo X75, X75-12, X100 ou X100-12, respectivamente.

-Z, --ditroff

groff executará troff e, então, usará um pós-processador adequado para produzir uma saída adequada para o dispositivo escolhido. Se groff -mandoc for groff, essa opção é passada para groff e suprimirá o uso de um pós-processador. Ela resulta em -t.

Obtendo ajuda¶

-?, --help

Imprime uma mensagem de ajuda e sai.

--usage

Imprime uma mensagem curta e sai.

-V, --version

Exibe informação da versão.