Notas sobre como esclarecer páginas de manual

Olá! Depois de passar algum tempo trabalhando nas páginas de manual do Git no ano passado, estive pensando um pouco mais sobre o que constitui uma boa página de manual.

Passei muito tempo escrevendo folhas de dicas para ferramentas (tcpdump, git, dig, etc.) que possuem uma página de manual como documentação principal. Isso ocorre porque muitas vezes acho difícil navegar nas páginas de manual para obter as informações que desejo.

Ultimamente tenho me perguntado – a página de manual poderia em si tem uma folha de dicas incrível? O que pode tornar uma página de manual mais fácil de usar? Ainda estou pensando muito cedo sobre isso, mas queria fazer algumas anotações rápidas.

Perguntei a algumas pessoas no Mastodon quais eram suas páginas de manual favoritas e aqui estão alguns exemplos de coisas interessantes que vi nessas páginas de manual.

um RESUMO DE OPÇÕES

Se você leu muitas páginas de manual, provavelmente já viu algo assim no SYNOPSIS: uma vez que você lista quase todo o alfabeto, é difícil

ls (-@ABCFGHILOPRSTUWabcdefghiklmnopqrstuvwxy1%,)

grep (-abcdDEFGHhIiJLlMmnOopqRSsUVvwXxZz)

A página man do rsync tem uma solução que eu nunca vi antes: ela mantém sua SINOPSE muito concisa, assim:

 Local:
     rsync (OPTION...) SRC... (DEST)

e depois tem uma seção “RESUMO DE OPÇÕES” com um resumo de 1 linha de cada opção, como este:

--verbose, -v            increase verbosity
--info=FLAGS             fine-grained informational verbosity
--debug=FLAGS            fine-grained debug verbosity
--stderr=e|a|c           change stderr output mode (default: errors)
--quiet, -q              suppress non-error messages
--no-motd                suppress daemon-mode MOTD

Mais tarde, há a seção OPÇÕES usual com uma descrição completa de cada opção.

uma seção OPÇÕES organizada por categoria

A página de manual do strace organiza suas opções por categoria (como “Geral”, “Inicialização”, “Rastreamento” e “Filtragem”, “Formato de saída”) em vez de em ordem alfabética.

Como experiência, tentei pegar o grep página man e faça uma seção “RESUMO DE OPÇÕES” agrupada por categoria, você pode ver os resultados aqui. Não tenho certeza do que acho dos resultados, mas foi um exercício divertido. Quando eu estava escrevendo isso, pensei em como nunca consigo lembrar o nome do -l opção grep. Sempre levo uma eternidade para encontrá-lo na página de manual e estava tentando pensar em qual estrutura tornaria mais fácil encontrá-lo. Talvez categorias?

uma folha de dicas

Algumas pessoas me indicaram o conjunto de páginas de manual do Perl (perlfunc, perlreetc), e uma coisa que notei foi man perlcheat, que tem seções de dicas como esta:

 SYNTAX
 foreach (LIST) { }     for (a;b;c) { }
 while   (e) { }        until (e)   { }
 if      (e) { } elsif (e) { } else { }
 unless  (e) { } elsif (e) { } else { }
 given   (e) { when (e) {} default {} }

Eu acho isso muito legal e me faz pensar se existem outras maneiras de escrever folhas de dicas ASCII condensadas de 80 caracteres para uso em páginas de manual.

um índice e links entre seções

Esta não é uma propriedade da página de manual em si, mas um problema com as páginas de manual no terminal é que é difícil saber quais seções a página de manual possui.

Ao trabalhar nas páginas de manual do Git, uma coisa que Marie e eu fizemos foi adicionar um índice à barra lateral das versões HTML das páginas de manual hospedadas no site do Git.

Eu também gostaria de adicionar mais hiperlinks para as versões HTML das páginas de manual do Git em algum momento, para que você possa clicar em “OPÇÕES INCOMPATÍVEIS” para acessar essa seção. É muito fácil adicionar links como este no projeto Git, pois as páginas de manual do Git são geradas com AsciiDoc.

Acho que adicionar um índice e adicionar hiperlinks internos é um bom meio-termo onde podemos fazer algumas melhorias no formato da página de manual (pelo menos na versão HTML da página de manual) sem manter uma forma de documentação totalmente diferente. Embora para que isso funcione você precise configurar um conjunto de ferramentas como o sistema AsciiDoc do Git.

exemplos para cada opção

A página de manual curl tem exemplos para cada opção, e também há um índice na versão HTML para que você possa pular mais facilmente para a opção de seu interesse.

Por exemplo o exemplo para --cert torna mais fácil ver que você provavelmente também deseja passar no --key opção, assim:

  curl --cert certfile --key keyfile https://example.com

A maneira como eles implementam isso é que existe (um arquivo para cada opção)(https://github.com/curl/curl/blob/dc08922a61efe546b318daf964514ffbf41583 25/docs/cmdline-opts/append.md) e há um campo “Exemplo” nesse arquivo.

formatando dados em uma tabela

Muitas pessoas disseram que man ascii era sua página de manual favorita, que se parece com isto:

 Oct   Dec   Hex   Char                     
 ───────────────────────────────────────────
 000   0     00    NUL '\0' (null character)
 001   1     01    SOH (start of heading)   
 002   2     02    STX (start of text)      
 003   3     03    ETX (end of text)        
 004   4     04    EOT (end of transmission)
 005   5     05    ENQ (enquiry)            
 006   6     06    ACK (acknowledge)        
 007   7     07    BEL '\a' (bell)          
 010   8     08    BS  '\b' (backspace)     
 011   9     09    HT  '\t' (horizontal tab)
 012   10    0A    LF  '\n' (new line)      

Obviamente man ascii é uma página de manual incomum, mas acho que o que é legal nessa página de manual (além do fato de que é sempre útil ter uma referência ASCII) é que ela é muito fácil de digitalizar para encontrar as informações necessárias devido ao formato da tabela. Isso me faz pensar se há mais oportunidades para exibir informações em uma “tabela” em uma página de manual para facilitar a digitalização.

a abordagem GNU

Quando falo sobre páginas de manual, muitas vezes acontece que as páginas de manual do GNU coreutils (por exemplo, man tail) não possuem exemplos, ao contrário das páginas de manual do OpenBSD, que possuem exemplos.

Não vou entrar muito nisso porque parece um tema bastante político e definitivamente não posso fazer justiça aqui, mas aqui estão algumas coisas que acredito serem verdadeiras:

• O projeto GNU prefere manter a documentação em manuais “info” em vez de páginas de manual. Esta página diz “as páginas de manual não estão mais sendo mantidas”.
• Existem 3 maneiras de ler manuais “info”: sua versão HTML, em Emacs, ou com uma versão autônoma info ferramenta. Ouvi de alguns usuários do Emacs que eles gostam do navegador de informações do Emacs. Acho que nunca conversei com alguém que usa o standalone info ferramenta.
• A entrada do manual de informações para tail está vinculada na parte inferior da página de manual e contém exemplos
• A FSF costumava vender livros impressos dos manuais de software GNU (e talvez ainda o façam às vezes?)

Depois de um certo nível de complexidade, uma página de manual fica realmente difícil de navegar: embora eu nunca tenha usado o manual de informações do coreutils e provavelmente não o usarei, quase certamente preferiria usar o manual de referência do GNU Bash ou o Manual de referência da biblioteca GNU C por meio de sua documentação HTML, em vez de por meio de uma página de manual.

mais algumas coisas adjacentes à página de manual

Aqui estão algumas ferramentas que considero interessantes:

• O fish shell vem com um script Python para gerar automaticamente preenchimentos de guias a partir de páginas de manual
• tldr.sh é um banco de dados de exemplos mantido pela comunidade, por exemplo, você pode executá-lo como tldr grep. Muitas pessoas me disseram que acham isso útil.
• o navegador de documentos Dash Mac possui um bom visualizador de páginas de manual. Eu ainda uso o visualizador de páginas de manual do terminal, mas gosto que ele inclua um índice, parecido com isto:

é interessante pensar em um formato restrito

As páginas de manual têm um formato muito restrito e é divertido pensar no que você pode fazer com opções de formatação tão limitadas. Eu estaria interessado em ouvir sobre outras páginas de manual que você acha que são bem projetadas e o que você gosta nelas.