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

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.

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 ...)

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.

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.

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á: