Cómo generar un archivo de rebajas de GitHub desde Microsoft Word usando TypeScript

¿Qué? ¿Por qué querría uno generar un archivo MD a partir de un documento de Microsoft Word? Si ese es el primer pensamiento que tuvo después de leer este título, permítame darle un caso de uso sólido.

Considere una situación en la que está utilizando Git o cualquier otro sistema de control de versiones (VCS) para las fuentes de su proyecto, así como sus artefactos. Ahora, como la mayoría de los proyectos, decide utilizar Microsoft Word para la documentación y registrarlo en Git. Nuevamente, varios miembros del equipo editan el mismo documento. Después de editar, registran el documento en el repositorio.

Ahora, Git podrá mantener el historial de su documento. ¿Cómo podrá ver los cambios que se han realizado en el documento desde la última vez que lo registró? Sí, puede usar el modo de cambio de pista de Microsoft Word, pero ¿no es complicado? O, por el amor de Dios, ¿podrá usar la utilidad Git diff para verificar las diferencias rápidamente? Yo diría que no.

¿Entonces cuál es la solución? ¿Debería dejar de utilizar Microsoft Word para la documentación? ¿O debería cambiar a algún otro VCS?

Yo diría que no. ¿Qué tal si mantiene su documentación en Microsoft Word? Luego, cámbielo a un archivo de rebajas (MD) (en términos simples, un archivo de texto) durante la fase de construcción y regístrese. Si esa solución te emociona, sigue leyendo.

Pero antes de pasar directamente a la conversión, déjame decirte qué es exactamente un archivo de rebajas.

¿Qué es un archivo Markdown o MD?

Markdown es un lenguaje de sintaxis que tiene como objetivo facilitar la lectura y escritura de texto estructurado. Además, es fácil de aprender y solo requiere un editor de texto para crear un documento.

Ahora, hay múltiples implementaciones del lenguaje (como GFM, también conocido como Markdown con sabor a Github). Cada una de estas implementaciones tiene sus propias mejoras y características que no son necesariamente compatibles entre sí.

Cada implementación admite varias características comunes como párrafos, citas en bloque, encabezados y listas. Esto ayuda a mantener el texto de una manera estructurada como Microsoft Word. Pero, en lugar de utilizar códigos binarios internos, los archivos MD utilizan caracteres de texto sin formato para estas funciones. Esto hace que un archivo MD sea un archivo de texto pero no un archivo binario como un archivo docx.

Por ejemplo, en el tipo de rebajas de GitHub, aquí están las diversas características y formas de representarlas en forma de texto en comparación con un documento de Word.

Para conocer las ventajas detalladas de los archivos MD sobre los documentos de Word, también puede consultar este artículo.

¡OKAY! Estoy convencido. Enséñame el código.

Descargo de responsabilidad: este proyecto está inspirado en el código fuente de TypeScript. Mientras lo navegaba, encontré esta idea de convertir un documento de Word en un archivo MD. Puedes ver su código fuente aquí.

Para simplificar, eliminé algunas secciones de código en mi repositorio. El código original estaba destinado a convertir la documentación de especificación de TypeScript en un archivo MD. Este archivo contiene muchos estilos personalizados. Entonces, una vez que haya terminado con este artículo, puede revisar el código del convertidor de TypeScript y apreciar sus capacidades para realizar conversiones más complejas.

El código completo mencionado en este artículo se puede consultar aquí. El código completo se puede dividir en 3 secciones:

  1. Configuraciones de Gulp.
  2. Ejecución de CScript.
  3. Función principal de TypeScript

Como se indicó anteriormente, puede convertir un documento de Word en un archivo MD durante la fase de compilación. Esto puede hacerlo cualquier corredor de tareas. Aquí, he elegido tragar.

En las configuraciones de Gulp, he definido 3 tareas. El primero es limpiar el directorio de compilación, que es bastante estándar. El segundo es compilar el código TypeScript. Y el último es llamar al CScript para ejecutar JavaScript.

¿Qué es CScript?

CScript.exe (presente en C: \ Windows \ System32) es un ejecutable basado en consola para el host de secuencias de comandos que se utiliza para ejecutar las secuencias de comandos. Puede interpretar lenguajes de secuencias de comandos como VB Script o JavaScript. De manera similar, tenemos WScript pero se usa para aplicaciones de Windows. En esto, la consola no está conectada. Entonces, si tiene el requisito de crear una aplicación basada en consola, podemos usar CScript.

Ahora, en nuestro proyecto, el trabajo principal de CScript es proporcionar un entorno de tiempo de ejecución para nuestro script, es decir, JavaScript. Ahora, debes estar pensando, ¿por qué no he usado un nodo en lugar de CScript para ejecutar mi JavaScript?

Ambos proporcionan un entorno de tiempo de ejecución para JavaScript. CScript proporciona soporte inherente para la técnica del modelo de objetos de componentes de Windows. Entonces, si intenta ejecutar este script a través de Node, obtendrá un error como este.

var fileStream = new ActiveXObject ("ADODB.Stream"); ​​ReferenceError: ActiveXObject no está definido

Ahora bien, ¿qué es una técnica de modelo de objetos componentes?

El modelo de objetos componentes es una tecnología desarrollada por Microsoft. No es un idioma sino un estándar binario. Según la definición,

El Modelo de objetos componentes (COM) de Microsoft es un sistema orientado a objetos, distribuido e independiente de la plataforma para crear componentes de software binarios que pueden interactuar. COM es la tecnología fundamental para OLE (documentos compuestos) de Microsoft, ActiveX (componentes habilitados para Internet), entre otros.

En términos sencillos, los objetos COM son interfaces para los distintos objetos en tiempo de ejecución. (Es por eso que la definición tiene un término llamado "componentes de software binario"). No es un lenguaje, sino una técnica que es independiente del lenguaje de programación.

El único requisito de lenguaje para COM es que el código se genere en un lenguaje que pueda crear estructuras de punteros. Ya sea explícita o implícitamente, llame a funciones a través de punteros. Los lenguajes orientados a objetos como C ++ y Smalltalk proporcionan mecanismos de programación que simplifican la implementación de objetos COM

Después de eso, podemos usar cualquier otro lenguaje como Java, VB o JavaScript para interactuar con esos objetos COM. Esto nos dará acceso a las aplicaciones en tiempo de ejecución. En nuestro caso, a las aplicaciones de Microsoft Word.

Entonces, ¿estás diciendo que no podemos usar Node en absoluto aquí?

No, eso no es verdad. También podemos usar Node en lugar de CScript. Pero para admitir COM, necesitaremos instalar otro paquete llamado win32com para compatibilidad con COM. Detalles pueden ser encontrados aqui.

Código final

Ahora, para interactuar con la aplicación de Word, se han utilizado varias API. Y como estamos usando el modelo de objetos COM, me referí a la palabra modelo de objetos.

Word proporciona cientos de objetos con los que puede interactuar. Estos objetos están organizados en una jerarquía que sigue de cerca la interfaz de usuario. En la parte superior de la jerarquía se encuentra el objeto Aplicación. Este objeto representa la instancia actual de Word. El objeto Aplicación contiene los objetos Documento, Selección, Marcador y Rango. Cada uno de estos objetos tiene muchos métodos y propiedades a los que puede acceder para manipular e interactuar con el objeto.

Ahora, en nuestro script, primero hemos creado un objeto de aplicación de Word usando ActiveXObject. Una vez que se obtiene el objeto de la aplicación, el objeto del documento se crea pasando el nombre del documento (obtenido de los argumentos de la línea de comandos de la llamada cscript).

Ahora, esto representa el objeto activo del documento real. Este objeto es capaz de analizar y manipular el documento de Word. Sin embargo, en nuestro caso de uso, solo necesitamos analizar el documento y escribir un archivo de texto.

Este código es muy genérico y se utiliza para convertir características muy básicas de un documento de Word, como referencias cruzadas, listas, textos con subíndices, caracteres en negrita y cursiva, etc., en formato GFM. Sin embargo, puede escribir su propio código convirtiendo sus estilos personalizados del documento de Word al formato deseado.

Puede encontrar el código mecanografiado real aquí. El código es bastante fácil de leer. A continuación se muestran algunos aspectos destacados importantes:

  1. Primero, se pasa un objeto de documento a la función convertDocumentToMarkdown que devuelve el texto a escribir en un archivo MD.
  2. Además, en convertDocumentToMarkdown, se llaman a los métodos y propiedades del objeto de documento para buscar y reemplazar características de palabras relevantes con la sintaxis del lenguaje GFM correspondiente. Por ejemplo, primero se buscan textos en subíndice y negrita y cursiva. Después de eso, el texto se reemplaza por el código específico de GFM. Y finalmente, se eliminan los estilos de palabras. Todo esto se hace aquí.
  3. Después de esto, se reemplazan las referencias cruzadas. Sin embargo, esto es complicado. Primero, se llama a la función toggleShowCodes. Esto tiene un impacto similar al de alt + F9 en un documento de Word. Esto reemplaza todas las referencias cruzadas en un documento con el código. Después de eso, se llama al método de buscar y reemplazar para buscar y reemplazar todas las referencias cruzadas con el estilo GFM. Aquí, "19 REF" se pasa como argumento a una función. Este es un criterio de búsqueda estándar para encontrar todas las referencias cruzadas en un documento de Word. Por último, después de reemplazar, nuevamente se llama a la función toggleShowCodes para devolver el documento a su forma original.
  4. Por último, se llama a la función writeDocument que hace el trabajo principal. Lee el documento párrafo por párrafo y luego, usando mayúsculas y minúsculas, busca los estilos de los párrafos (como si es un encabezado o una tabla o un párrafo de lista o una imagen). Ahora, dependiendo del estilo encontrado, el texto deseado se escribe en el archivo MD.

Una palabra o dos sobre cómo incrustar imágenes: incrustar imágenes en un archivo MD es un poco complicado.

Primero, necesitas almacenar las imágenes en tu repositorio de git. Luego, el enlace debe incluirse en el archivo MD para incrustarlo. La sintaxis es! [Texto alternativo] (ruta / en / el / repositorio / imagen1.jpg).

Ahora, para generar automáticamente este enlace para una imagen mientras se convierte una palabra en un archivo MD, se crea un texto oculto (justo después de la imagen sin ningún espacio) con el contenido como el enlace en sí. Y luego, en el código, este texto oculto se quita y se inserta en el archivo MD.

Ahora, puede encontrar el código real para hacer todas estas cosas muy tedioso, pero todo esto es según la API expuesta por la aplicación Word. Así que no se preocupe por eso. Definitivamente puede consultar mi código o el código original de TypeScript. Ambos serán un buen comienzo para su próximo proyecto.

¡¡Oh espera!! Eso es. ¿Llegaste hasta el final? Bien entonces ? ¡Felicidades! ? Y, si te gustó este artículo, por favor dale un aplauso. boton de abajo. Significaría mucho para mí y ayudaría a otras personas a ver la historia. ¡Salud! ?