As páginas `man` são ótimas; o problema são os leitores de `man`

• É comum criticar as páginas man por “não terem links entre si” ou porque “o texto não é reorganizado quando a janela do terminal é reduzida”, mas na prática o próprio formato man oferece suporte tanto a links quanto à reorganização do texto
• O problema está em as ferramentas usadas para ler páginas man (como o comando man e o less) não implementarem esses recursos corretamente

Estrutura do formato das páginas man

• Os documentos man são escritos principalmente em dois formatos:
  • mdoc(7): formato moderno de marcação semântica
  • man(7): formato antigo usado entre 1979 e 1989
• Exemplo (parte da sintaxe mdoc):

  .Sh NAME  
  .Nm openrc  
  .Nd stops and starts services for the specified runlevel  
  .Sh SYNOPSIS  
  

• .Sh, .Nm e .Nd significam, respectivamente, cabeçalho de seção, nome do comando e descrição
• Para editar diretamente, é necessário consultar a lista de macros do mdoc

O recurso de referências (links) também já vem embutido

• O formato mdoc inclui as seguintes macros de link:
• .Xr: referência cruzada para outra página man
• .Sx: referência a outra seção da mesma página
• Ao converter para HTML, elas são renderizadas como links reais e podem ser clicadas no navegador
• Os cabeçalhos de seção .Sh são tratados como âncoras e podem ser o destino de links .Sx
• Porém, ao visualizar no terminal com o comando man, esse recurso de links não funciona

Conclusão: o problema não é o formato man, e sim o visualizador

• Atualmente, o comando man exibe as páginas redirecionando a saída para o less, e essa abordagem não consegue lidar com links
• A solução é:
• um novo visualizador de páginas que entenda o formato man e ofereça suporte a links
• Também seria melhor implementar junto o recurso de reorganização automática do texto (reflow) quando a largura do terminal mudar

Informações de contexto

• mdoc(7) foi introduzido no 4.4BSD na década de 1990
• man(7) é um formato clássico usado entre 1979 e 1989 e hoje quase não é mais utilizado

[scari]

Eu me identifiquei na hora só de ver a primeira linha na notificação do Slackbot e cliquei. Também concordo 100% com a observação de que o problema é o leitor.

...mas parece que a humanidade moderna não usa nem man, muito menos terminal. rtfm acabou virando um vestígio romântico de outra era.

[winterjung]

Eu deixo isso definido no mac como abaixo e uso como pman ls, para visualizar em PDF.

pman() {  
  mandoc -Tpdf "$(man -w $@)" | open -f -a Preview  
}  

[pcj9024]

Dica incrível... obrigado

[pkj3186]

Nossa, muito obrigado

[bbulbum]

Nossa, me identifiquei demais com isso. man, quando você sabe ler bem, é realmente ótimo, mas é difícil demais aprender a ler direito..

[GN⁺]

Opiniões do Hacker News

• Há a opinião de que, embora se escreva documentação nos formatos mdoc e mandb há muito tempo, dominar essa linguagem é difícil
  • mdoc e mandb são como conjuntos de macros sobre o roff
  • Existe a ideia de propor converter todas as páginas man para Markdown e exibi-las pelo sistema
  • O Markdown tem mais ferramentas, então até usuários não técnicos conseguem escrever documentação com facilidade
  • Porém, o Markdown é menos estruturado e existem dialetos diferentes entre vários programas
• Navegar por páginas info no Emacs é útil, e seria possível fazer algo parecido com páginas man
  • A riqueza das páginas man atuais é uma vantagem que muita gente não percebe
  • Há certo pesar em relação às pessoas que querem migrar para Markdown
  • Ao migrar para Markdown, seria difícil implementar os links e a semântica geral das soluções existentes
  • Ao ver casos de migração de dados para JSON, há tentativas de adicionar recursos complexos
• Usar o ft-man-plugin embutido do Vim como visualizador padrão de páginas man ajuda a resolver o problema
  • Os links funcionam e a indentação é mantida ao quebrar linhas
  • Dá para melhorar a configuração padrão do less, mas é necessário rolagem horizontal
• É uma pena que muitas versões web de páginas man usem fontes monoespaçadas de forma monótona
  • As páginas man online do OpenBSD são excelentes
  • Ler páginas man no terminal também é bom
  • A busca e a rolagem de meia página são os recursos mais usados
• O pinfo é para visualizar páginas GNU Info, mas também consegue mostrar páginas man
  • Ele reconhece referências cruzadas entre páginas e permite navegar por elas
• Há a opinião de que seria bom ter uma função para ir direto à explicação de uma flag específica
  • Atualmente, usa-se expressão regular para encontrar a descrição da flag
• É sugerido considerar o projeto mandoc
  • Ele processa as páginas semanticamente para obter resultados melhores
• Há quem considere que Markdown é uma solução melhor
  • Já se está acostumado a ler documentação na web ou no editor de código, então outras interfaces são desconfortáveis
  • Os desenvolvedores estão familiarizados com Markdown, e a maior parte da documentação também é escrita em Markdown
  • As páginas man são inferiores tanto para quem escreve quanto para quem consome a documentação