Markdown y Markdeep son formatos ligeros para la escritura y publicación de documentación. En mutabiT los hemos extendido para que permita también compartir rápidamente versiones web de las notas interactivas escritas Lepiter. Para ello, esencialmente hemos colocados un conjunto de metadatos alrededor de los trozos de texto exportado desde Lepiter, con información que permiten reimportarlos de vuelta. Dichos metadatos están contenidos en etiquetas div de HTML con lo cual no se pierde la compatibilidad con Markdeep/Markdown, ni se crea una variante nueva de tales lenguajes (esfuerzos como CommonMark surgieron para armonizar tal eclosión de variantes).

Combinando metadatos y formatos ligeros para compartir y publicar información, nos dotamos de un conjunto de ventajas, que los enfoques populares basados en XML y JSON no tienen:

• Buena legibilidad de los documentos para humanos: A diferencia de los documentos JSON y XML, los formatos ligeros de documentación son sencillos de leer, incluso si no se cuenta con el software donde se escribieron originalmente los documentos.
• Amigable respecto a los sistemas de control de versiones: Dado que los formatos ligeros no son muy verborrágeos (a diferencia de XML) y soportan saltos de línea (a diferencia de JSON) es posible leer fácilmente los cambios históricos entre versiones del documento (por ejemplo, estos son los históricos de este documento), y permiten soportar saltos de línea semánticos.
• Fáciles de compartir por correo o publicar en la web: Basta con enviar/publicar un simple archivo de unos cuandos kilobytes, en contraste con los pesados formatos XML, que habitualmente son carpetas comprimidas con recursos asociados a un archivo (ejp imágenes). Para compartir y versionar tales recursos extra usamos Fossil, lo cual nos permite mantener los documentos sencillos, a la vez que podemos colaborar en su escritura, rastrear sus históricos y los de los recusos asociados a los documentos.
• El documento web contiene la información clave para ser importado de vuelta como documento interactivo: alternativas más populares, como Jupyter, Org Mode y el mismo exportador nativo de Lepiter, no permiten, hasta el momento, que un documento en línea pueda ser reimportado en tales entornos. Nuestros metadatos y convenciones de publicación de código fuente sí permiten, dado un enlace al archivo exportado, importar su código fuente y “rehidratarlo” dentro del entorno interactivo.

Si revisas el código fuente de documento podrás apreciar cómo lucen nuestro formato ligero enriquecido y experimentar de primera mano tales ventajas.

Hemos agregado otras configuraciones extra, que permiten a Pharo/Lepiter usar cabeceras y hojas de estilo personalizadas y, en general, controlar el proceso de exportación desde el entorno de Pharo (llamado la imagen) hacia el sistema de archivos. Para el caso de Markdeep, dichas configuraciones están en la variable config del objeto Markdeep y son adicionales a las opciones de Markdeep, que también soportamos, para controlar sus documentos (pues configuran aspectos extra). Para el caso de Markdown, hemos usado las cabeceras de metadatos en YAML, que son donde habitualmente Pandoc controla la exportación del documento.

Primero se instala ExoRepo y luego se ejecuta:

ExoRepo new
    repository: 'https://code.tupale.co/Offray/MiniDocs';
    load.

MiniDocs also provides Nano ID preliminary support to uniquely ID the documents. This is done via an external Nim’s programming language implementation of Nano ID, which allow us to reuse it with extreme portability without reimplementing it natively in Pharo. To see and compile the source code for the Nano ID run:

NanoID scriptSourceCode fullName

NanoID binaryFile 

NanoID install

NanoID generate

Nimble version

Para probar la exportación de páginas:

pruebas := LePage new title: 'Pruebas exportación'.
OSSUnixSubprocess new 
        command: 'pandoc' ;
        arguments: { pruebas markdownFileName. '-o'. pruebas htmlFileName};
        workingDirectory: pruebas storage fullName;
        runAndWaitOnExitDo: [ :process :outString  | pruebas storage / pruebas htmlFileName].

Estas son algunas ideas en borrador. No deberían considerarse como documentos orientados al lector, sino ayudas de memoria al autor.

Algunas convenciones para procesar bloques podrían ayudar a las conversiones desde Lepiter a Markdeep/Markdown:

• || Los siguientes elementos hijos deben ser procesados como una lista de items y este como su preámbulo:

Item 1

Item 2

Item 3: Nótese que esto quizás requiera incorporar en los metadatos información sobre el tipo de etiqueta ad-hoc, para recuperarla cuando se importe la libreta

~~~ Lua linenumbers print (“Esto debería aparecer con fuente de código ~~~

[Ejemplo [lua]: Ejemplos de código embebido.