Herramientas de autorización de la ayuda del usuario final de la plataforma
https://stackoverflow.com/questions/2977398
-
24-10-2019 - |
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
RussianPregunta
¿Cuáles son algunas buenas herramientas de autoría para crear archivos de ayuda multiplataforma para usuarios finales? (Nuestra aplicación está utilizando el marco QT, si eso hace alguna diferencia).
Nota: No estoy interesado en la documentación interna de la API, estaba usando doxígeno para eso.
Idealmente, una solución:
- Permítanos administrar todo el contenido de ayuda (texto, tabla de contenido, imágenes, etc.) en una sola ubicación.
- Salida a formatos de ayuda nativa. (CHM para Windows, o al menos algo que podríamos alimentar directamente en la API de ayuda HTML; no estoy seguro de cuáles son los formatos de ayuda "estándar" de otras plataformas).
- Soporte de Wysiwyg decente: manejar la entrada de texto común, imágenes, referencias cruzadas, etc. fácilmente, pero podemos editar el HTML cuando necesitemos.
- Proyecto de formato de archivo basado en texto para el proyecto de ayuda (XML, etc.) para que pueda verificarse en subversión.
- Cualquier gancho que ayude a mantenerlo en sincronización con la base de código real sería excelente. (Quizás de alguna manera un tema de ayuda se asocia con un archivo de código, y puede verificar la subversión para ver si se han realizado cambios y marcar un tema como "posiblemente desactualizado" ... ¿estoy soñando?)
- El contenido de ayuda se puede localizar.
- No se opone al producto comercial, pero una opción gratuita sería buena.
Continuaré y haré de este un wiki y comenzaré con algunos ejemplos. Vota o baja si tienes experiencia con ellos y deja algunos comentarios. Agregue herramientas adicionales también.
Solución
Acabo de descubrir Esfinge; Creo que estoy enamorado.
- Mejor que wysiwyg sobre html: reestructuredText
- Salidas a Qthelp (entre otras cosas), por lo que será fácil distribuir (e integrar) en nuestra aplicación.
- Todavía no estoy seguro de la localización, pero cruzaremos ese puente cuando necesitemos.
- Fue fácil de configurar y "solo funciona"; Parece profesional.
Otros consejos
He usado robohelp durante años.
Está bien, pero la tecnología central es muy vieja ahora. Además, la forma en que bloquean las versiones de Word es un PITA total (y me ha obligado a evitar actualizaciones de MS Office varias veces).
Nos estamos moviendo a Madcap Flare http://www.madcapsoftware.com/products/flare/robohelp.aspx
pienso Abarbook Aborda todos sus requisitos, excepto posiblemente los ganchos de sincronización, que pensaré un poco más adelante. Es esencialmente un subconjunto de XML diseñado para crear documentación, y es gratuito y de código abierto. Es solo un formato más un conjunto de transformaciones de salida XSL que convierten el Docbook en formatos más útiles (HTML y, por lo tanto, CHM, Javahelp, PDF a través de XML-FO o Tex).
Esto significa que aún necesita elegir una herramienta de autoría XML para editarla realmente para que cosas como Wysiwyg dependan de las características de su software de autoría XML. Utilizamos Syntext Serna, ya que tiene un buen soporte para Wysiwyg y la edición en línea de XML #includes (nadie más parece apoyar a este último). Puede encontrar que otras herramientas de autoría XML se adaptan mejor a sus necesidades: Serna es una oferta comercial razonablemente costosa.
Docbook proporciona mucha flexibilidad a través de la creación de perfiles, que le permite incluir/excluir elementos XML en función de sus atributos. Los casos de uso de ejemplo serían tener una salida de ayuda ligeramente diferente para OS = Windows que OS = Linux. La localización también se admite mediante perfiles y otros mecanismos.
Un bien bueno Introducción a Docbook puede ser encontrado aquí.
Utilizamos Docbook para nuestro formato de ayuda y lo compilamos en archivos CHM que contienen ayuda solo para las características relevantes para un producto específico (es decir, Enterprise Edition tiene características que no están en las versiones estándar o de demostración). Los pasos relevantes son:
- Ejecute las plantillas XSL de perfiles en la fuente XML (usando EG XSLTPROC).
- Ejecute las plantillas XSL HTML-HELP en la salida de 1.
- Compile los archivos HTML de salida utilizando el compilador de ayuda HTML de Microsoft (HHC).
El único que conozco es látex, uno de los convertidores de látex2HTML, y luego algunas adaptaciones para hacer que el HTML resultante esté listo para el Archiver de CHM.
- texto, html, chm, pdf, ps no hay problema.
- La conversión a Word a través de RTF solía ser un desastre, no conozca el estado actual.
- Los convertidores HTML de látex 2, mientras que varios, todos tienen sus propios problemas.
- Los PDF se ven absolutamente geniales.
- Wysiwym (a través de lyx) posible.
Este archivo tiene un montón de CHM de esa manera (especialmente el Prog, Ref y las partes de los usuarios, el resto (RTL, FCL, LCL) se generan por nuestro propio Doxygen equivalente, FPDOC)
http://www.stack.nl/~marcov/doc-chm.zip
Tenga en cuenta que los CHM anteriores están hechos con nuestro propio compilador CHM (portátil). Sí, no más taller.
Un documento LYX como PDF y HTML:
