diff --git a/Wiki/es/minidocs--aqbz4.md b/Wiki/es/minidocs--aqbz4.md new file mode 100644 index 0000000..bfa3679 --- /dev/null +++ b/Wiki/es/minidocs--aqbz4.md @@ -0,0 +1,265 @@ +--- +id: aqbz43j9b455g8uxrazp5i9r +title: MiniDocs +created: 24 March 2022 6:20:04.213034 pm +modified: 25 July 2022 6:58:05.837708 pm +creator: +modifier: +--- + +
+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](../../../../finfo?name=wiki/es/minidocs--aqbz4.md)), + y permiten *soportar [saltos de línea semánticos](https://sembr.org/)*. + - **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](https://fossil-scm.org/), + 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](https://jupyter.org/), [Org Mode](https://orgmode.org/) 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](../../../../file?name=wiki/es/minidocs--aqbz4.md&ci=tip&txt=1) 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. +
+