Les pages man sont excellentes, le problème, ce sont les lecteurs de man

• On critique souvent les pages man en disant qu’« il n’y a pas de liens entre elles » ou que « le texte ne se réorganise pas quand on redimensionne la fenêtre du terminal », mais en réalité le format man lui-même prend en charge les liens et le réagencement du texte
• Le vrai problème, c’est que les outils qui lisent les pages man (man, less, etc.) n’implémentent pas correctement ces fonctionnalités

Structure du format des pages man

• Les documents man sont principalement écrits dans deux formats :
  • mdoc(7) : un format de balisage moderne, fondé sur la sémantique
  • man(7) : un ancien format utilisé entre 1979 et 1989
• Exemple (une partie de la syntaxe mdoc) :

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

• .Sh, .Nm et .Nd désignent respectivement un en-tête de section, le nom de la commande et sa description
• Pour éditer directement ce format, il faut se référer à la liste des macros mdoc

La fonction de référence (liens) est également intégrée

• Le format mdoc inclut les macros de lien suivantes :
• .Xr : une référence croisée vers une autre page man
• .Sx : une référence vers une autre section de la même page
• Lors d’une conversion en HTML, elles sont rendues comme de vrais liens, cliquables dans le navigateur
• Les en-têtes de section .Sh sont traités comme des ancres et peuvent servir de destination aux liens .Sx
• En revanche, lorsque l’on consulte la page dans le terminal avec la commande man, cette fonctionnalité de lien ne fonctionne pas

Conclusion : le problème, ce n’est pas le format man, mais le visualiseur

• Aujourd’hui, la commande man affiche les pages en les envoyant à less, et cette approche ne permet pas de gérer les liens
• La solution serait :
• un nouveau visualiseur de pages capable de comprendre le format man et de prendre en charge les liens
• Ce serait encore mieux s’il implémentait aussi le réagencement automatique du texte (reflow) lors d’un changement de largeur du terminal

Informations de contexte

• mdoc(7) est un format introduit dans 4.4BSD dans les années 1990
• man(7) est un format historique utilisé entre 1979 et 1989, aujourd’hui presque plus employé

[scari]

J’ai cliqué après avoir vu seulement la première ligne dans la notification du bot Slack, tant j’étais immédiatement d’accord. Moi aussi, je suis d’accord à 100 % avec l’idée que le vrai problème, c’est le lecteur.

...Cela dit, on dirait bien que les humains modernes n’utilisent ni man, ni même le terminal. rtfm est devenu un vestige romantique d’une autre époque.

[winterjung]

Sur macOS, je définis ceci comme ci-dessous et je l'utilise avec pman ls, par exemple, afin de les consulter en PDF.

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

[pcj9024]

Super astuce... merci

[pkj3186]

Merci beaucoup, c’est génial.

[bbulbum]

Waouh, je ressens tellement la même chose. man, c’est vraiment excellent quand on sait bien le lire, mais c’est tellement difficile à bien lire...

[GN⁺]

Avis Hacker News

• Certains estiment qu’ils rédigent depuis longtemps de la documentation aux formats mdoc et mandb, mais qu’il reste difficile d’en maîtriser le langage
  • mdoc et mandb ressemblent à des jeux de macros au-dessus de roff
  • L’idée serait de convertir toutes les pages man en Markdown pour les afficher dans le système
  • Markdown dispose de davantage d’outils, ce qui permet même aux utilisateurs non techniques de rédiger facilement de la documentation
  • Mais Markdown est moins formalisé, et il existe donc différents dialectes selon les programmes
• Parcourir les pages info dans Emacs est utile, et on peut faire quelque chose de similaire avec les pages man
  • La richesse des pages man existantes est un avantage que beaucoup de gens ne perçoivent pas
  • Il y a un certain regret face à ceux qui veulent tout basculer vers Markdown
  • Passer à Markdown compliquerait l’implémentation des liens et de la sémantique générale des solutions existantes
  • Quand on regarde les cas où les données ont été déplacées vers JSON, on voit des tentatives d’ajouter des fonctionnalités complexes
• Utiliser le ft-man-plugin intégré de Vim comme lecteur man par défaut peut aider à résoudre le problème
  • Les liens fonctionnent et l’indentation est conservée lors des retours à la ligne
  • Les réglages par défaut de less pourraient être améliorés, mais cela nécessite un défilement horizontal
• Beaucoup de versions web des pages man utilisent une police monospace un peu triste, ce qui est regrettable
  • Les pages man en ligne d’OpenBSD sont excellentes
  • Lire les pages man dans le terminal est aussi agréable
  • Les fonctions de recherche et le défilement d’une demi-page sont les usages principaux
• pinfo est conçu pour consulter les pages GNU Info, mais il peut aussi afficher des pages man
  • Il reconnaît les références croisées entre pages et permet de naviguer entre elles
• Certains aimeraient une fonction permettant d’aller directement à l’explication d’un drapeau précis
  • Pour l’instant, ils utilisent des expressions régulières pour retrouver la description du drapeau
• Il est suggéré d’envisager le projet mandoc
  • En traitant les pages de manière sémantique, on peut obtenir de meilleurs résultats
• Certains estiment que Markdown est une meilleure solution
  • Ils sont habitués à lire la documentation sur le web ou dans un éditeur de code, et les autres interfaces leur semblent peu pratiques
  • Les développeurs sont familiers de Markdown, et la plupart de la documentation est déjà écrite dans ce format
  • Les pages man sont jugées inférieures, tant pour les auteurs de documentation que pour les lecteurs