¿Cómo escribo páginas de manual? [cerrado]

16

¿Cómo escribo una página de manual?

¿Dónde puedo encontrar una referencia de todos los códigos de formato?

¿Hay algún buen tutorial sobre cómo escribir páginas de manual?

¿Cuál es la forma más conveniente de escribir una página de manual? ¿Debo ingresarlo directamente en un editor de texto? ¿Hay editores WYSIWYG? ¿O debería escribirlo en un formato diferente y luego convertirlo?

¿Qué reglas debe seguir una buena página de manual?

documentation

— amarillion
fuente

Esta pregunta parece ser demasiado amplia. Solo ha logrado atraer un montón de respuestas de solo enlace y algunas opiniones no respaldadas.

— 200_success

man man, man groff.

— Jenny D

13

Aquí hay algunas páginas web que lo ayudarán a comenzar:

Un par de herramientas útiles:

— Pausado hasta nuevo aviso.
fuente

6

Existen herramientas para escribir páginas man que omiten el formato troff. Las páginas de manual son un lenguaje pequeño, bien delimitado y fácil de orientar.

Dos herramientas populares son:

xmltoman , un lenguaje xml pequeño y bien estructurado que puede generar páginas de manual y html. Es utilizado por los proyectos de Lennart Poettering, syrep y pulseaudio, por ejemplo .
asciidoc , usado por git por ejemplo .

yodl y zoem parecen ser otros formatos agradables en este espacio.

En general, recomendaría xmltoman porque es un dsl muy específico de la página de manual que lo guiará de cerca.

— Tobu
fuente

"dsl" == "idioma específico del dominio"?

— Pausado hasta nuevo aviso.

sí (da. si. 15 caracteres)

— Tobu

1

Otra buena opción es ronn , que lee el lenguaje de marcado de texto Markdown más utilizado.

— Poolie

5

He escrito un artículo de blog bastante extenso sobre el tema, que puedes encontrar aquí:

http://2buntu.com/articles/1034/how-to-write-a-manpage/

— Nathan Osman
fuente

44

Sería útil si al menos pudiera resumir el artículo aquí: los enlaces por sí solos no valen nada una vez que la página vinculada inevitablemente se mueva o desaparezca.

— Caleb

No estoy de acuerdo con Caleb. Esta es la web. La web se basa en enlaces, y stackexchange no conlleva ninguna excepción especial a esto. Copiar contenido es contraproducente. Cualquier cosa mala que le pueda pasar a esa página o documento también le puede pasar a esta . No podemos acumular copias raspadas de todo el contenido solo porque el resto de la web podría desaparecer. (Deje ese trabajo a sitios como la máquina wayback).

— Kaz

Kaz, puede que no esté de acuerdo, pero el comentario de Caleb es definitivamente la mejor práctica de ServerFault.

— MadHatter

2

No conozco ningún IDE o tutorial, pero puede comenzar copiando una página de manual existente y modificarla para satisfacer sus necesidades.

Para obtener una referencia del lenguaje groff con macros MAN (que es lo que usa una página man), consulte la página man groff_man , o léalo en línea aquí

— Dan Andreatta
fuente

2

Echa un vistazo al proyecto ronn . Es un descuento para el generador de páginas de manual. También puede generar las páginas man en html, de esta manera .

Me gusta la idea de escribir toda mi documentación de software en un formato. Markdown IMO es una buena opción

— Bruno Polaco
fuente