MiniDocs/Wiki/es/minidocs--aqbz4.md

id	title	created	modified	creator	modifier
aqbz43j9b455g8uxrazp5i9r	MiniDocs	24 March 2022 6:20:04.213034 pm	25 July 2022 6:58:05.837708 pm	<unknown>	<unknown>

MiniDocs es un conjunto de herramientas "minimalistas" para publicar y compartir documentación escrita desde [Lepiter](https://lepiter.io/feenk/introducing-lepiter--knowledge-management--e2p6apqsz5npq7m4xte0kkywn/).

En los enfoques de procesadores de palabras populares (MS Word, Libre Office Writer, etc) un programa pesado (de centenares de megas o gigas) usa un formato pesado y engorroso para humanos (XML) para labores de documentación. En contraste, MiniDocs se enfoca en lenguajes de etiquetamiento ligero, como [Markdown](https://en.wikipedia.org/wiki/Markdown), [Markdeep](https://casual-effects.com/markdeep/) y la navaja suiza de tales lenguajes ligeros, [Pandoc](https://pandoc.org/), que pueden ser escritos desde centenares de procesadores de texto y palabra, con mínimos requerimientos de hardware, en diversidad de dispositivos (teléfonos, tabletas, computadores de escritorio) y con una notación amigable para escritura y lectura por humanos. La intensión es hacer de tales lenguajes/formatos ligeros, la manera de compartir y publicar documentos creados desde Lepiter.

::: {.info} Este documento está publicado usando MiniDocs. :::

MiniDocs incorpora a Lepiter (2021) las lecciones aprendidas de [Grafoscopio](https://mutabit.com/grafoscopio/) [^lecciones] (2015), en las que complejos documentos tipo libros, como el [Manual de Grafoscopio](https://mutabit.com/repos.fossil/grafoscopio/uv/Docs/En/Books/Manual/manual.pdf) (2016), el [Manual de Periodismo de Datos](https://mutabit.com/repos.fossil/mapeda) (2018), el libro de [Feminismo de Datos](https://mutabit.com/repos.fossil/datafem/) (2019a) o la [Documentatón](https://mutabit.com/repos.fossil/documentaton/) (2019b), eran almacenados por completo en sencillos formatos de texto enriquecidos vía [STON](https://github.com/svenvc/ston/blob/master/ston-paper.md). También hemos agregado algunas ideas de diseño de micrositios y documentación en línea provenientes de [IndieWeb con Brea](https://mutabit.com/repos.fossil/indieweb/) (2020). Para las libretas interactivas en Grafoscopio, usamos STON como un formato donde embebíamos trozos de Markdown y de Pharo. Le hemos dado la vuelta a esa idea, generando ahora lenguajes ligeros de documentación enriquecidos con trocitos de metadatos en STON. Veamoslo en detalle.

[^lecciones]: De hecho, MiniDocs reempaqueta y modulariza funcionalidad relacionada con lenguajes de etiquetamiento ligero, que anteriormente estaba en el paquete [GrafoscopioUtils](https://code.tupale.co/Offray/GrafoscopioUtils) .

# Lenguajes ligeros enriquecidos

Markdown y Markdeep son formatos ligeros para la escritura y publicación de documentación. En [mutabiT](https://mutabit.com/) 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](https://commonmark.org/) 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](https://casual-effects.com/markdeep/#api), 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](https://pandoc.org/MANUAL%202.html#extension-yaml_metadata_block), que son donde habitualmente Pandoc controla la exportación del documento.

# Instalación

Primero se instala [ExoRepo](https://code.tupale.co/Offray/ExoRepo) y luego se ejecuta:

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

# Utilización

MiniDocs also provides [Nano ID](https://github.com/ai/nanoid) 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:

~~~ Smalltalk NanoID scriptSourceCode fullName ~~~

~~~ Smalltalk NanoID binaryFile ~~~

~~~ Smalltalk NanoID install ~~~

~~~ Smalltalk NanoID generate ~~~

~~~ Smalltalk Nimble version ~~~

# Pruebas

Para probar la exportación de páginas:

~~~ Smalltalk 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]. ~~~

# Ideas sueltas

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

## Lepiter con marcas extra

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.