Las páginas man son excelentes; el problema son los lectores de man

• Es común criticar a las páginas man porque “no tienen enlaces entre sí” o porque “el texto no se reajusta al reducir la ventana de la terminal”, pero en realidad el propio formato man sí soporta enlaces y reflujo de texto
• El problema está en que las herramientas para leer páginas man (como el comando man y less) no implementan bien estas funciones

Estructura del formato de las páginas man

• Los documentos man se escriben principalmente en dos formatos:
  • mdoc(7): un formato moderno de marcado basado en semántica
  • man(7): un formato antiguo usado entre 1979 y 1989
• Ejemplo (parte de la sintaxis de mdoc):

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

• .Sh, .Nm y .Nd significan respectivamente encabezado de sección, nombre del comando y descripción
• Para editarlo directamente, hace falta consultar la lista de macros de mdoc

La función de referencias (enlaces) también está integrada

• El formato mdoc incluye macros de enlace como las siguientes:
• .Xr: referencia cruzada a otra página man
• .Sx: referencia a otra sección dentro de la misma página
• Al convertirlo a HTML, se renderizan como enlaces reales y se pueden hacer clic en el navegador
• Los encabezados de sección .Sh se tratan como anclas y pueden ser destino de enlaces .Sx
• Sin embargo, al verlo en la terminal con el comando man, esta función de enlaces no funciona

Conclusión: el problema no es el formato man, sino el visor

• Actualmente, el comando man muestra las páginas enviándolas por tubería a less, y este enfoque no puede manejar enlaces
• La solución sería:
• un nuevo visor de páginas que entienda el formato man y soporte enlaces
• También sería mejor implementar reflujo automático del texto (reflow) cuando cambie el ancho de la terminal

Información de contexto

• mdoc(7) es un formato introducido en 4.4BSD en la década de 1990
• man(7) es un formato clásico usado entre 1979 y 1989, y hoy casi no se utiliza

[scari]

Vi y me identifiqué al instante apenas leí la primera línea en la alerta del bot de Slack, así que hice clic. Yo también estoy 100% de acuerdo con que el problema es el lector.

...Pero parece que la humanidad moderna no usa ni man, mucho menos la terminal. rtfm ya se volvió una reliquia romántica de otra época.

[winterjung]

Yo tengo esto definido en mi Mac y lo uso como pman ls para verlo en PDF.

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

[pcj9024]

Qué gran tip... gracias

[pkj3186]

Increíble, muchas gracias

[bbulbum]

Vaya, me identifico muchísimo con esto. man es realmente bueno si lo lees bien, pero leerlo bien es demasiado difícil...

[GN⁺]

Opiniones en Hacker News

• Hay quienes opinan que, aunque han escrito documentación en formatos mdoc y mandb durante mucho tiempo, dominar ese lenguaje sigue siendo difícil
  • mdoc y mandb son como conjuntos de macros sobre roff
  • Se plantea la idea de convertir todas las páginas man a Markdown para que el sistema las muestre así
  • Markdown tiene más herramientas y permite que incluso usuarios no técnicos escriban documentación con facilidad
  • Sin embargo, Markdown está menos estructurado y existen distintos dialectos entre varios programas
• Navegar páginas info en Emacs es útil, y algo similar podría hacerse con las páginas man
  • La riqueza de las páginas man actuales es una ventaja que mucha gente no reconoce
  • Hay cierta decepción con quienes quieren migrar a Markdown
  • Si se cambia a Markdown, será difícil implementar los enlaces y la semántica general de las soluciones existentes
  • Al ver casos donde los datos se movieron a JSON, se nota que intentan añadir funciones complejas
• Usar el ft-man-plugin integrado de Vim como visor predeterminado de páginas man ayuda a resolver el problema
  • Los enlaces funcionan y se mantiene la sangría al hacer saltos de línea
  • Se podría mejorar la configuración predeterminada de less, pero hace falta desplazamiento horizontal
• Es una lástima que muchas versiones web de las páginas man usen una tipografía monoespaciada y monótona
  • Las páginas man en línea de OpenBSD son excelentes
  • También es bueno leer páginas man en la terminal
  • Principalmente se usan la búsqueda y el desplazamiento de media página
• pinfo está pensado para ver páginas GNU Info, pero también puede mostrar páginas man
  • Reconoce referencias cruzadas entre páginas y permite navegarlas
• Hay opiniones de que sería bueno contar con una función para saltar a la explicación de una bandera específica
  • Por ahora, se usan expresiones regulares para encontrar la descripción de una bandera
• Se sugiere considerar el proyecto mandoc
  • Puede procesar las páginas de manera semántica y obtener mejores resultados
• Hay quienes creen que Markdown es una mejor solución
  • Están acostumbrados a leer documentación en la web o en editores de código, por lo que otras interfaces resultan incómodas
  • Los desarrolladores están familiarizados con Markdown, y la mayoría de la documentación también se escribe en Markdown
  • Las páginas man son inferiores tanto para quienes escriben la documentación como para quienes la consumen