Ayuda con el apoyo # xmldoc MS Word y C

Question

Busco una herramienta de generación de ayuda y/o documentación que satisfaga estos requisitos:

• debería apoyar comentario xmldoc producido por compilador de C# o (aún mejor) admitir directamente sandcastle
• debe admitir la importación de documentos de MS Word.
• debe admitir la creación de enlaces desde la documentación conceptual a la documentación de referencia producida a partir del código fuente.
• que estaría bien si es compatible con autoría documento conceptual en MS Word

Más detalles. Mi proyecto es un framework/biblioteca para .NET. Tiene varias soluciones VS con más de 50 proyectos C#. Antes que nada quiero generar ayuda (chm & help2 & help3 en el futuro) del código fuente de mis proyectos. Me referiré a esa documentación como "documento de referencia". Sandcastle (especialmente con el uso de SCFB) puede hacer esto de una manera muy agradable. Pero (supongo que es una situación muy común) Tengo algo de documentación adicional para el framework/biblioteca. Esa documentación está en archivos de MS Word (5-10 archivos). Me referiré a esa documentación como "documento conceptual". Quiero producir un sistema de ayuda sólido con doc conceptual y doc de referencia (como MSDN). Y quiero que la parte conceptual de la ayuda contenga enlaces (URL) que hacen referencia a la parte de referencia de la ayuda para cada nombre de tipo .NET del framework/biblioteca. (Obviamente, cualquier sistema de ayuda es solo HTML eventualmente).

El problema es cómo crear estos enlaces. Los archivos de MS Word no saben nada sobre C# xmldoc. Sandcastle no es compatible con archivos de Word. Así que tengo que tomar algo de Help Authoring Tool (HAT). Por el momento no puedo encontrar ninguna herramienta adecuada para mí. ¡Y sería muy apreciado por cualquier ayuda!

Un obstáculo para todas las herramientas es la autocreación de enlaces. Me gustaría que los enlaces se creen automáticamente durante la generación (que puede tener lugar en el servidor de compilación). ¿Por qué automáticamente? Porque permite un fácil cambio de nombre de los tipos. Para una instancia. Tengo un texto en el documento conceptual: "para acceder al contexto de procesamiento de solicitud use la propiedad estática Current of XOperationContext type". Aquí XOperationContext es un nombre de tipo. Me gustaría que se convirtiera en un enlace (URL) a la especificación de la clase XOperationContext en el sistema de ayuda de resultados sin ningún esfuerzo significativo. Me gustaría marcarlo en Word (probablemente con el plugin de HAT instalado) o en el editor de HAT como algo como "hacer este enlace de palabra si es posible". Durante la generación, cada palabra se convertiría en un enlace si hay un nombre de tipo con dicho nombre.

sé acerca de estas herramientas:

• Toolsfactory Doc-o-Matic (usando ahora)
• Innovasys DocumentX and HelpStudio
• ComponentOne Doc-to-Help

Doc-O-Matic enlaces de soporte de creación automática. Verdaderamente automatico Intenta crear un enlace para cada palabra en PascalCase, brillantemente. Pero no es compatible con MS Word. El software de Innovasys y ComponentOne no admite la creación de enlaces automáticamente. El software de Innovasys no es compatible con MS Word (no estoy seguro del 100% sobre esto).

Traté de preguntar en los foros de Innovasys y ComponentOne. Sin suerte hasta ahora. Escenario de soporte suave de Innovasys como el mío: creación de documentos conceptuales en herramientas separadas - HelpStudio y generación de ayuda del código fuente con otra herramienta - DocumentX. Pero no hay posibilidad de crear enlaces automáticamente e importar archivos de MS Word.

Por lo tanto, comparta su caducidad para esa tarea común (estoy seguro de que debería ser habitual).

p.s. por favor, avíseme si no he logrado explicar mis pensamientos correctamente desde el punto de vista de la gramática inglesa, intentaré uno más.

Answer 1

Intenta echar un vistazo a SandCastle.

Answer 2

¿Qué le parece exportar sus archivos de MS Word a HTML y luego combinarlos en el HTML para los archivos de ayuda? ¿Es eso una opción? Podría perder algo de formato, pero podría permitirle integrar todo un poco mejor.

Answer 3

Sandcastle es de código abierto, ¿por qué no inventar algo por su cuenta? Escribir una herramienta de automatización de oficinas no es tan difícil después de todo. E incluso puedes crear un negocio en esa herramienta.

Answer 4

Creo que la solución sería convertir tus archivos de Word en (X) HTML u otro formato no binario primero, y luego importar los documentos conceptuales junto con los documentos de referencia. Puede crear vínculos automáticamente en función del contenido de texto de los cuerpos del documento (como señaló) o ejecutar los documentos conceptuales a través de un paso de preproceso para anotarlos. Esto incluso podría ser un script ejecutado antes de la importación.

Answer 5

¿Has mirado Doxygen? No hace nada con los archivos de Word, pero es de código abierto, por lo que quizás podría agregar esas características usted mismo. Realmente me gustan los documentos que produce, y es muy liviano, así que lo incluí en el proceso de compilación para regenerar documentos automáticamente.

Answer 6

Sugiero comenzar por SandCastle y luego procesar uno de los formatos de archivo de salida para producir documentos de Word. Producir documentos de Office 2007 Word (*.docx) desde cero no es tan difícil, una vez que tiene una buena comprensión de cómo se empacan las cosas. Brian Jones tiene un blog excelente en el Open XML SDK, que proporciona soporte para tratar con documentos de Office desde .NET.

Y siempre puede decidir comenzar con un documento de Word existente y luego reemplazar los marcadores de posición con su propio texto, si crear un paquete completo parece ser demasiado complicado o demasiado trabajo para lo que está tratando de lograr.