texto metadatos mdn introduccion intro etiquetas codigo articulo html pdf documentation latex pdf-generation

metadatos - ¿Cuál es la mejor manera de escribir documentación orientada tanto a HTML como a PDF?



metadatos html5 (16)

¿Látex? ¿Seriamente? No sabía que nadie fuera de la academia todavía lo usara. Me gustaría ir con HTML, que puedes guardar como PDF desde el navegador web. Si realmente debe tener algunos elementos tipográficos avanzados, vaya con Word en su lugar: tiene una forma de guardar en HTML (probablemente no tan limpio como a uno le gustaría), y puede guardar como PDF con un complemento gratuito (descargable por separado) .

Ah, y no me molestaría en usar cosas como InDesign: son excesivas. Además, no se moleste en pagar por Acrobat Professional; hay un millón de soluciones gratuitas disponibles.

Los convertidores de látex a html que he visto en el pasado han sido bastante horribles. Editar html en bruto no es divertido y no parece traducirse bien a la página impresa. ¿Cómo resuelven los demás este problema? Los enlaces a ejemplos (tanto pdf como html) serían geniales.

Agregado: Se hizo otra pregunta similar:

¿Qué lenguaje de formato debo usar para la documentación del proyecto?

Después de muchos años de angustia y varios comienzos en falso, estoy a punto de volver a visitar esto, y voy a darle una oportunidad a Sphinx . Puede generar HTML o LaTeX a partir de ReStructured Text .

Espero que sea una opción mucho más "ligera" que el DocBook completo, pero con muchas de las ventajas.

Esta es una elección personal, pero Latex en teoría es perfecto, sin embargo, en la práctica es dolor en el culo. Estoy usando el editor HTML VS.NET + edición HTML sin procesar cuando lo necesito.

Entonces, creo que usar un editor HTML WSIWYG es la mejor opción. Siempre puede usar una herramienta simple para convertirlo a PDF, y siempre puede editar HTML cuando necesita algo avanzado. También es más fácil poner en línea cuando lo necesite.

Así es como estoy administrando mis documentos de software y funciona bien para mí.

He usado TeXinfo en el pasado y hace un buen trabajo. Aquí hay un ejemplo: http://yootles.com/api . Preferiría quedarme con LaTeX, en lugar de usar otro idioma.

No estoy seguro de que el látex sea realmente la mejor herramienta para esto. El problema que está teniendo con el convertidor habitual de latex a html es indicativo del problema: html es simple, no tan expresivo como el látex.

Si insiste en latex to html, tenga cuidado de usar un subconjunto limitado que se pueda convertir razonablemente.

Sí, los convertidores de LaTeX a HTML solían chupar (probablemente haya probado LaTeX2HTML), pero últimamente han mejorado. Tex4ht es altamente configurable y produce buenos XHTML + CSS. Ver también otros convertidores .

También puede usar Docbook , si puede soportar escribir en él. Hay conversores de DocBook para HTML y LaTeX (o para PDF directamente); un ejemplo de este último es dblatex .

Ver esta publicación: LaTeX vs Docbook .

AsciiDoc parece una posibilidad interesante.

Para documentar el código, también recomiendo Sphinx. ReStructured Text es agradable porque es legible y algo marcado en texto plano, y puede hacer un buen trabajo convirtiendo a html y a pdf. Todavía me gusta LaTeX para ciertas cosas. Mi esposa y yo usamos LaTeX para escribir nuestra carta navideña, que enviamos por correo postal. La versión en PDF es bastante elegante, con dos columnas, encabezados y pies de página. La versión html es más simple. Me convierto con plastex. Ejemplos aquí: http://fedibblety.com/annualReports

No creo que ningún formato binario sea una buena opción (Word) para cualquier tipo de documento que le gustaría leer dentro de 10 años. Esa es una de las cosas buenas de LaTeX.

Si todo lo demás falla, podría tomar un convertidor de LaTeX a XML y escribir una hoja de estilo XSLT simple para convertirlo a HTML, o crear una hoja de estilo CSS y adjuntarlo directamente al archivo XML.

Hemos estado usando WebWorks ePublisher (www.webworks.com) que ofrece formatos de fuente única múltiples (estamos usando Word) y la capacidad de generar resultados en muchos formatos de salida (damos salida a Adobe PDF y a la Ayuda en línea (.CHM) .

Como la respuesta que menciona a Asciidoc fue algo corta en cuanto a los ejemplos, estas son algunas de las cosas que está buscando:

  • Un pdf generado con Asciidoc
  • Una hoja de prueba con un lado a lado del marcado de Asciidoc y el resultado html.
  • Una lista de publicaciones realizadas utilizando Asciidoc, incluidos los libros de O''Reilly y la documentación de git (para ver los dos extremos de la escala de usuario).

Estábamos enfrentando este problema en un proyecto académico que involucraba software Eclipse, y usamos Plastex para convertir Latex a HTML y Ayuda de Eclipse. Hacerlo funcionar fue bastante difícil, pero el resultado final se ve muy bien. Puedes ver las tres versiones aquí:

http://handbook.event-b.org/

Además, como se trata de un proyecto abierto, el código (scripts de compilación) está disponible. Tenemos un sistema de construcción continuo (Jenkins) que reconstruye todo cuando se registra el nuevo Latex. Esto es particularmente agradable, ya que los contribuyentes no necesitan instalar la cadena de herramientas en sus sistemas. Simplemente revisan el nuevo Latex y verifican si el HTML se produjo correctamente. Fuentes:

http://sourceforge.net/p/rodin-b-sharp/svn/HEAD/tree/trunk/Handbook/org.rodinp.handbook.feature/

Mejor, Michael

Podría dar un paso atrás y usar algo como DocBook y renderizar en PDF a través de LaTeX y HTML directamente desde los archivos de DocBook. Alternativamente, Adobe Technical Communication Suite (Framemaker) le permitirá obtener un documento de fuente única en PDF y HTML. Consulte esta publicación para ver un resumen de varios sistemas de documentación técnica.