Referência de uso do comando interativo: você geralmente tem isso no Unix?

Question

A questão de por que alguns comandos dependem de manpages , enquanto outros dependem de algo como --help flag para fornecer referência de uso de comandos não é novo . Geralmente há uma diferença no escopo entre documentação para um comando e uma sinopse de uso do comando . Este último é frequentemente um subconjunto do primeiro. Mas mesmo quando a maioria dos comandos e utilitários tem páginas de manual, por exemplo, existem diferenças na formatação da seção de sinopses que têm implicações muito práticas ao tentar extrair tal informação. Em outros casos, é possível encontrar pistas com o utilitário strings quando um comando aparentemente não possui documentação.

Eu estava interessado nos comandos que tenho nessa plataforma QNX e descobri o use comando ¹ para exibir informações de uso. Conforme explicado em usemsg , a estrutura envolve a configuração de um registro de uso padrão na fonte de utilitários e, uma vez compilado, isso pode ser acessado com o comando use e também é possível envolver a funcionalidade nativa etc. É bastante conveniente,

use -d dir >>file

em /base e /proc/boot para extrair todo o uso de todos os comandos no sistema, basicamente.

Então eu olhei brevemente a fonte para GNU coreutils ls e FreeBSD ls para ver se eles fizeram algo assim e o primeiro coloca informações de uso em algum uso chamado função (por --help eu acho) enquanto o último não parece colocá-lo em qualquer lugar (?).

• Esse tipo de solução ( use ) é típico do que você encontra com o Unix comercial para apresentar a referência de uso do comando interativamente?
• O POSIX / SUS recomenda ou sugere alguma coisa sobre a apresentação / implementação de referência de uso de comandos em comandos (em oposição à especificação de notação para utilitários de shell )?

^{1. use comando:}

use
Print a usage message (QNX Neutrino)

Syntax:
use [-aeis] [-d directory] [-f filelist] files

Options:
-a
    Extract all usage information from the load module in its source form, suitable for piping into usemsg. 
-d directory
    Recursively display information for all files under directory. 
-e
    Include only ELF files. 
-f filelist
    Read a list of files, one per line, from the specified filelist file, and display information for each. 
-i
    Display build properties about a load module. 
-s
    Display the version numbers of the source used in the executable. 
files
    One or more executable load modules or shell scripts that contain usage messages. 

    

Answer 1

Uniões comerciais geralmente apresentam informações de uso apenas em páginas man. Ter o próprio comando exibir informações de uso não é um recurso tradicional do Unix (exceto para exibir a lista de opções suportadas, mas sem nenhuma explicação, sobre um erro de uso). POSIX e seus parentes não falam sobre nada disso.

Ter uma opção --help que exibe um resumo de uso (normalmente, uma lista de opções, uma por linha, com uma descrição máxima de ~ 60 caracteres para cada opção) é uma padrão GNU . Tanto quanto eu sei, esta convenção foi iniciada pelo projeto GNU, como parte da convenção de dois passos para nomes de opção com várias letras. Existem outros utilitários, como os utilitários X11, que usam nomes de opções com várias letras com um único traço e suportam -help ; Eu não sei qual veio primeiro.

O comando use é uma coisa QNX.

    

Answer 2

Você se refere às ferramentas GNU em seu exemplo. Eles estão disponíveis no Linux e em muitas outras plataformas e são um pouco incomuns em termos de documentação.

As ferramentas GNU, na verdade, parecem ter três níveis de referência interativa cada vez mais detalhada:

--help como uma opção de comando comum - um resumo de uso curto ,% man - as páginas man clássicas, uma "referência rápida" e
info - um manual mais detalhado, GNU-speciffic - a documentação oficial completa e .

Muitas vezes, um usa apenas a página man como a documentação defauls - mesmo sabendo que "eles dizem" a documentação do GNU info é mais detalhada e oficial.

Será varry um pouco com base nas preferências, mas acho que o seguinte padrão de uso é bastante comum:

• usando man foo por padrão ,
  • com uma explicação de todas as opções
  • às vezes parece um pouco superficial, mas bom o suficiente
• use foo --help às vezes, para perguntas pequenas , como não tendo certeza sobre o nome de uma opção,
  • com um breve resumo no layout compacto
• e use info foo ... quase nunca .
  • que provavelmente forneceria mais alguns detalhes de contexto e links para outros comandos
  • mas ninguém pode usar a interface de usuário do navegador de informações no estilo emacs, por isso não descobriremos exatamente.
• e, caso contrário, documentação baseada em rede,
  • como se a página man fosse muito concisa.

Existe, no entanto, um problema:

Para os comandos usados com mais frequência, do pacote coreutils , como ls , cp , mkdir , csplit e muitos mais,

a página de manual man foo contém exatamente as mesmas informações que foo --help . ⁽¹⁾

Isso significa a 'documentação real' , na verdade, não nas man pages - como pensávamos ...
Na verdade, estão nos arquivos GNU info que não lemos !

Agora, olhando para as páginas man e (parte inferior de) --help , é difícil perceber que o conteúdo é o mesmo, porque a página man parece tão "mais detalhada". É porque a diferença na densidade do layout de texto é muito grande entre as duas variantes. Extremamente comprimido em --help , comparado ao espaçamento extremamente relaxado em man .

Compare por si mesmo, é impressionante:

ls --help | less

man ls | less

info --subnodes ls | less

(A opção --subnodes renderiza a página linearmente, para comparação. Em si, info mostra hipertexto, vinculado entre documentos semelhantes a HTML. O comando man inclui less para forçar a saída sem cor para facilitar comparação.)

Algumas sugestões relacionadas:

Existem alternativas mais confortáveis para o visualizador de informações padrão info , como - para o terminal - pinfo ou - para a GUI - konqueror . Exemplo de uso como este:
pinfo ls ou konqueror info:ls ou usando info:ls na barra de URL de konqueror .

Como um caso especial , a documentação dos comandos internos do GNU bash ,
que são chamados shell builtins , podem ser acessados com o comando help .
Por exemplo, na linha de comando de bash , tente help cd

_{1) Felizmente, @ PádraigBrady apontou isso em sua resposta}

    

Answer 3

Note que as páginas man do GNU coreutils são geradas a partir de $ cmd --help

Observe também que bash builtins, pelo menos, não suportam --help. Lá você precisa usar help umask por exemplo. Agora o POSIX permite, e o ksh usa pelo menos umask --help . Foi proposto recentemente que o bash também poderia aceitar essa sintaxe