Por que as páginas de manual não têm exemplos?

52

Existe uma razão pela qual a maioria das páginas de manual não inclui alguns exemplos comuns? Eles geralmente explicam todas as opções possíveis, mas isso torna ainda mais difícil para um iniciante entender como é "geralmente" usado.

Deepak Joy
fonte
11
Meu palpite é que eles queriam economizar espaço em disco valioso, como se livrar do CR. Cf. Beckett, Watt , p.8: "Muito espaço valioso foi economizado [...] por evitar o pronome reflexivo pletórico depois de dizer ".
Peter - Restabelece Monica
3
Uma tentativa de solução alternativa para esse problema é o tldr-pages.github.io , embora não perceba por que eles facilitam o download de tudo antecipadamente para acesso offline.
Nathan Long
man jqtem mais de 1000 linhas de exemplos (no Ubuntu 16.04)
Motte001 7/16

Respostas:

49

Isso depende das páginas man ... Tradicionalmente, eles têm incluído uma seção com exemplos -, mas por algum motivo que normalmente é ausente das páginas do homem no Linux (e presumo que outros usando comandos GNU - que são mais estes dias). No Solaris, por outro lado, quase todas as páginas de manual incluem a seção Exemplo, geralmente com vários exemplos.

Se eu fosse adivinhar, o FSF / GNU há muito tempo desencorajou o uso de manpáginas e prefere que os usuários usem informações para documentação. infopáginas tendem a ser mais abrangente do que páginas do homem, e normalmente não incluem exemplos. infoas páginas também são mais "tópicas" - isto é, comandos relacionados (por exemplo, comandos para localizar arquivos) geralmente podem ser encontrados juntos.

Outra razão pode ser que o GNU e suas manpáginas sejam usadas em muitos sistemas operacionais diferentes, que podem diferir um do outro (existem muitas diferenças apenas entre diferentes distribuições Linux). A intenção pode ter sido que o editor tenha adicionado exemplos relevantes para a OS / distribuição específica - o que obviamente raramente é feito.

Eu também acrescentaria que as manpáginas nunca foram destinadas a "ensinar iniciantes". O UNIX foi desenvolvido por especialistas em computadores (antigo termo "hackers") e destinado a ser usado por especialistas em computadores. As páginas de manual, portanto, não foram feitas para ensinar um iniciante, mas para ajudar rapidamente um especialista em computadores que precisava de um lembrete para alguma opção obscura ou formato de arquivo estranho - e isso se reflete na maneira como uma página de manual é seccionada.

man-páginas são assim

  • Uma referência rápida para refrescar sua memória; mostrando como o comando deve ser chamado e listando as opções disponíveis.
  • Uma descrição profunda e completa - e geralmente muito técnica - de todos os aspectos do comando. Foi escrito por especialistas em computação, para outros especialistas em computação.
  • Lista de variáveis ​​e arquivos de ambiente (ou seja, arquivos de configuração) usados ​​pelo comando.
  • Referência a outra documentação (por exemplo, livros) e outras manpáginas - por exemplo. para o formato dos arquivos de configuração e comandos relacionados / similares.

Dito isto, concordo muito com você que as manpáginas devem ter exemplos, pois podem explicar melhor o uso do que percorrer a própria página de manual. Exemplos muito ruins geralmente não estão disponíveis nas manpáginas do Linux ...

Amostra da parte Exemplo de uma página do manual Solaris - zfs (1M):

(...)
EXEMPLOS
     Exemplo 1 Criando uma hierarquia do sistema de arquivos ZFS

     Os comandos a seguir criam um sistema de arquivos chamado pool / home
     e um sistema de arquivos chamado pool / home / bob. O ponto de montagem
     / export / home está definido para o sistema de arquivos pai e é
     herdado automaticamente pelo sistema de arquivos filho.

       # zfs create pool / home
       # zfs set mountpoint = / export / home pool / home
       # zfs create pool / home / bob

     Exemplo 2 Criando um instantâneo do ZFS

     O comando a seguir cria um instantâneo chamado ontem.
     Esse instantâneo é montado sob demanda no arquivo .zfs / snapshot
     diretório na raiz do sistema de arquivos pool / home / bob.

       # zfs snapshot pool / home / bob @ ontem

     Exemplo 3 Criando e destruindo vários instantâneos

     O comando a seguir cria instantâneos nomeados ontem de
     pool / home e todos os seus sistemas de arquivos descendentes. Cada
     A captura instantânea é montada sob demanda no diretório .zfs / snapshot
     na raiz do seu sistema de arquivos. O segundo comando destrói
     os instantâneos criados recentemente.

       # zfs snapshot -r pool / home @ ontem
       # zfs destroy -r pool / home @ ontem

SunOS 5.11 Última alteração: 23 Jul 2012 51

Comandos de administração do sistema zfs (1M)

     Exemplo 4 Desabilitando e habilitando a compactação do sistema de arquivos

     O comando a seguir desabilita a propriedade de compactação para
(...)

Esta página de manual em particular vem com 16 (!) Exemplos ... Parabéns ao Solaris!
(E eu admito que eu mesmo segui esses exemplos, em vez de ler a página do manual inteira para esse comando ...)

Baard Kopperud
fonte
2
Essa última frase destaca um problema em ter exemplos em manuais. Toma-se os exemplos que melhor atendem às suas necessidades, sem entender completamente as implicações da aplicação específica da ferramenta. E mais tarde, pode-se dizer "eu fiz assim", mas não realmente o porquê ou o que isso significava.
Kusalananda
6
@Kusalananda Em minha defesa, eu tenho lido sobre as várias opções e sobre os sub-comandos Eu realmente necessários - apenas não a coisa toda (ainda). Não é simplesmente relevantes para o meu uso ... Apesar do perigo de mau uso, exemplos que servem a um propósito - e se tudo que você precisa é apenas o uso mais básico de um comando, ler sobre todos os sinos e assobios são dificilmente necessário.
Baard Kopperud 29/08/16
@Kusalananda Também pode depender dos comandos. A maioria dos utilitários Unix e GNU que conheço estão bem documentados, mas você precisa da documentação para fazer qualquer coisa sensata. Os comandos mais recentes do Solaris (especialmente zfs) são projetados com bastante naturalidade. Por exemplo, zfs destroy pool/filesystemé de uso básico e adequado para 90% dos casos de uso. Opções curtas como -rfor recursivesão mais especiais e precisam ser consultadas antes do uso, pois podem ter efeitos colaterais indesejados.
user121391
26

Eu não acho que haja uma boa resposta para isso. É uma coisa de cultura. Algumas páginas de manual têm exemplo de uso. Por exemplo man rsync. Você pode tentar mudar a cultura escrevendo para o autor da página de manual e solicitando que ele adicione algum uso de amostra ou (muito melhor) oferecendo alguns exemplos de uso de amostra. Se você oferece um patch para um autor de software livre, particularmente um patch de documentação, é aproximadamente dez mil vezes mais provável que o resultado desejado seja alcançado do que uma simples solicitação.

Faheem Mitha
fonte
7

Depende:

  • a maioria dos programas que você acha interessantes são desenvolvidos ao longo de um período de tempo, inicialmente para resolver um problema e posteriormente para melhorar a solução. Os desenvolvedores dos programas explicam o que eles achavam importante saber (e a documentação não era o problema que estavam resolvendo).
  • para alguns programas, os desenvolvedores preferem fornecer exemplos de programas ou scripts que mostram como usar um determinado programa (ou biblioteca). Novamente, isso é feito para resolver um problema: tornar o programa mais fácil de testar.

    Alguns dos exemplos podem ser baseados em relatórios de erros dos usuários e, quando curtos, encontram um lugar no manual. Exemplos longos raramente são fornecidos em manuais, e exemplos curtos têm o problema de que eles tendem a ser triviais, repetitivos e realmente não fornecem ao usuário tantas informações quanto uma descrição bem organizada da maneira como um programa funciona.

  • em alguns casos, você encontrará documentação fornecida por outras pessoas que não estão envolvidas no processo de desenvolvimento. Ou seja, os desenvolvedores não participaram, exceto para revisar a documentação. Esse tipo de esforço pode ser desconsiderado.
Thomas Dickey
fonte
5
"Esse tipo de esforço pode ser desconsiderado." Não tenho certeza do que isso significa.
Faheem Mitha
A documentação não contribui com nada útil quando não é baseada na experiência.
Thomas Dickey
De fato, a documentação não baseada na experiência pode dar uma contribuição negativa - isto é, está completamente errada.
alephzero
Claro - mencionei porque alguns dos exemplos que o OP, sem dúvida, tem em mente se enquadram nessa categoria (evitarei fornecer uma lista neste fórum).
Thomas Dickey
2
@ThomasDickey. Discordo completamente desta avaliação. A capacidade de escrever um utilitário não vem necessariamente com a capacidade de explicar a API para um usuário final. T
chiggsy
6

Se você está procurando uma alternativa para as páginas de manual, pode sempre tentar as páginas de bro , que mostram apenas vários exemplos de um comando, no qual você pode votar em uma lista de exemplos enviados pela comunidade. Por exemplo, o comando bro tarfornecerá:insira a descrição da imagem aqui

BandW2011
fonte