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

266 lines
16 KiB
Markdown
Raw Permalink Normal View History

2022-07-26 00:14:01 +00:00
---
id: aqbz43j9b455g8uxrazp5i9r
title: MiniDocs
created: 24 March 2022 6:20:04.213034 pm
modified: 25 July 2022 6:58:05.837708 pm
creator: <unknown>
modifier: <unknown>
---
<div st-class="LeTextSnippet"
st-data="OrderedDictionary{'id':'HRomKmygDQCp++iaAIpAvQ==','parent':'aqbz43j9b455g8uxrazp5i9r','created':'17 July 2022 8:38:41.302259 pm','modified':'17 July 2022 8:39:28.540754 pm','creator':'<unknown>','modifier':'<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/).
</div>
<div st-class="LeTextSnippet"
st-data="OrderedDictionary{'id':'KRQYkQCgDQCBOJHUBVIo7Q==','parent':'aqbz43j9b455g8uxrazp5i9r','created':'12 July 2022 12:16:31.96155 pm','modified':'18 July 2022 7:54:03.653888 am','creator':'<unknown>','modifier':'<unknown>'}">
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.
</div>
<div st-class="LeTextSnippet"
st-data="OrderedDictionary{'id':'4gmnN2WgDQCnhgWSDnOxMw==','parent':'aqbz43j9b455g8uxrazp5i9r','created':'17 July 2022 12:21:24.718734 pm','modified':'17 July 2022 12:34:07.554962 pm','creator':'<unknown>','modifier':'<unknown>'}">
::: {.info}
Este documento está publicado usando MiniDocs.
:::
</div>
<div st-class="LeTextSnippet"
st-data="OrderedDictionary{'id':'dJFVnGKgDQCngc+uDnOxMw==','parent':'aqbz43j9b455g8uxrazp5i9r','created':'17 July 2022 9:14:48.73868 am','modified':'18 July 2022 8:55:51.969768 am','creator':'<unknown>','modifier':'<unknown>'}">
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.
</div>
<div st-class="LeTextSnippet"
st-data="OrderedDictionary{'id':'RvnZcHagDQCXvE9kD8QETg==','parent':'dJFVnGKgDQCngc+uDnOxMw==','created':'18 July 2022 8:54:24.551604 am','modified':'18 July 2022 8:55:51.969768 am','creator':'<unknown>','modifier':'<unknown>'}">
[^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) .
</div>
<div st-class="LeTextSnippet"
st-data="OrderedDictionary{'id':'mZ5Z2mCXDQCk5CeyCQMJBQ==','parent':'aqbz43j9b455g8uxrazp5i9r','created':'24 March 2022 6:22:19.996011 pm','modified':'19 July 2022 3:12:39.75331 pm','creator':'<unknown>','modifier':'<unknown>'}">
# Lenguajes ligeros enriquecidos
</div>
<div st-class="LeTextSnippet"
st-data="OrderedDictionary{'id':'H6B0NnWgDQCXuwahD8QETg==','parent':'mZ5Z2mCXDQCk5CeyCQMJBQ==','created':'18 July 2022 7:26:22.571919 am','modified':'18 July 2022 8:52:41.408528 am','creator':'<unknown>','modifier':'<unknown>'}">
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).
</div>
<div st-class="LeTextSnippet"
st-data="OrderedDictionary{'id':'wVOVD2OgDQCngsAQDnOxMw==','parent':'mZ5Z2mCXDQCk5CeyCQMJBQ==','created':'17 July 2022 9:47:00.895758 am','modified':'19 July 2022 3:12:39.75331 pm','creator':'<unknown>','modifier':'<unknown>'}">
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.
</div>
<div st-class="LeTextSnippet"
st-data="OrderedDictionary{'id':'G+NZ31igDQC7S2TDBEiujA==','parent':'mZ5Z2mCXDQCk5CeyCQMJBQ==','created':'16 July 2022 9:37:42.020985 pm','modified':'17 July 2022 10:12:16.279135 am','creator':'<unknown>','modifier':'<unknown>'}">
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.
</div>
<div st-class="LeTextSnippet"
st-data="OrderedDictionary{'id':'10qmF7iYDQC4GZb8DW4ywA==','parent':'aqbz43j9b455g8uxrazp5i9r','created':'10 April 2022 7:52:18.913891 pm','modified':'25 July 2022 6:16:57.148649 pm','creator':'<unknown>','modifier':'<unknown>'}">
# Instalación
</div>
<div st-class="LeTextSnippet"
st-data="OrderedDictionary{'id':'rLlUxlagDQCnmjX9BGDvjw==','parent':'10qmF7iYDQC4GZb8DW4ywA==','created':'16 July 2022 9:30:28.412617 pm','modified':'16 July 2022 9:31:30.951887 pm','creator':'<unknown>','modifier':'<unknown>'}">
Primero se instala [ExoRepo](https://code.tupale.co/Offray/ExoRepo) y luego se ejecuta:
</div>
<div st-class="LePharoSnippet"
st-data="OrderedDictionary{'id':'zIF4GbiYDQC4HlDrDW4ywA==','parent':'10qmF7iYDQC4GZb8DW4ywA==','created':'10 April 2022 7:52:45.970765 pm','modified':'25 July 2022 6:16:57.148649 pm','creator':'<unknown>','modifier':'<unknown>'}">
~~~ Smalltalk
ExoRepo new
repository: 'https://code.tupale.co/Offray/MiniDocs';
load.
~~~
</div>
<div st-class="LeTextSnippet"
st-data="OrderedDictionary{'id':'TRhaRmygDQCp/OVQAIpAvQ==','parent':'aqbz43j9b455g8uxrazp5i9r','created':'17 July 2022 8:46:37.078562 pm','modified':'25 July 2022 5:16:58.649534 pm','creator':'<unknown>','modifier':'<unknown>'}">
# Utilización
</div>
<div st-class="LeTextSnippet"
st-data="OrderedDictionary{'id':'HtuXCvagDQCGdK4SCziW6A==','parent':'TRhaRmygDQCp/OVQAIpAvQ==','created':'24 July 2022 5:08:36.041226 pm','modified':'25 July 2022 9:50:18.626719 am','creator':'<unknown>','modifier':'<unknown>'}">
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:
</div>
<div st-class="LePharoSnippet"
st-data="OrderedDictionary{'id':'4brAEPagDQCGdUnvCziW6A==','parent':'TRhaRmygDQCp/OVQAIpAvQ==','created':'24 July 2022 5:10:00.703571 pm','modified':'25 July 2022 9:36:39.086322 am','creator':'<unknown>','modifier':'<unknown>'}">
~~~ Smalltalk
NanoID scriptSourceCode fullName
~~~
</div>
<div st-class="LePharoSnippet"
st-data="OrderedDictionary{'id':'q16DjwKhDQCx6tufCs1qsQ==','parent':'TRhaRmygDQCp/OVQAIpAvQ==','created':'25 July 2022 8:04:26.996236 am','modified':'25 July 2022 9:36:56.850547 am','creator':'<unknown>','modifier':'<unknown>'}">
~~~ Smalltalk
NanoID binaryFile
~~~
</div>
<div st-class="LePharoSnippet"
st-data="OrderedDictionary{'id':'ocRDvAKhDQCx66dCCs1qsQ==','parent':'TRhaRmygDQCp/OVQAIpAvQ==','created':'25 July 2022 8:16:57.802806 am','modified':'25 July 2022 9:49:44.837547 am','creator':'<unknown>','modifier':'<unknown>'}">
~~~ Smalltalk
NanoID install
~~~
</div>
<div st-class="LePharoSnippet"
st-data="OrderedDictionary{'id':'6DI+rguhDQCV24dXAEiDZw==','parent':'TRhaRmygDQCp/OVQAIpAvQ==','created':'25 July 2022 6:57:17.262473 pm','modified':'25 July 2022 6:57:23.13625 pm','creator':'<unknown>','modifier':'<unknown>'}">
~~~ Smalltalk
NanoID generate
~~~
</div>
<div st-class="LePharoSnippet"
st-data="OrderedDictionary{'id':'F8E7GQOhDQCo9wCiCBqFfg==','parent':'TRhaRmygDQCp/OVQAIpAvQ==','created':'25 July 2022 8:42:57.523573 am','modified':'25 July 2022 5:16:58.649534 pm','creator':'<unknown>','modifier':'<unknown>'}">
~~~ Smalltalk
Nimble version
~~~
</div>
<div st-class="LeTextSnippet"
st-data="OrderedDictionary{'id':'AyYYAZKgDQCDdCuBDR2/7A==','parent':'aqbz43j9b455g8uxrazp5i9r','created':'19 July 2022 5:47:22.852604 pm','modified':'23 July 2022 7:27:43.525521 am','creator':'<unknown>','modifier':'<unknown>'}">
# Pruebas
</div>
<div st-class="LeTextSnippet"
st-data="OrderedDictionary{'id':'AObhApKgDQCDdn90DR2/7A==','parent':'AyYYAZKgDQCDdCuBDR2/7A==','created':'19 July 2022 5:47:59.321738 pm','modified':'19 July 2022 5:48:07.709235 pm','creator':'<unknown>','modifier':'<unknown>'}">
Para probar la exportación de páginas:
</div>
<div st-class="LePharoSnippet"
st-data="OrderedDictionary{'id':'GrYJBJKgDQCDd85PDR2/7A==','parent':'AyYYAZKgDQCDdCuBDR2/7A==','created':'19 July 2022 5:48:10.652999 pm','modified':'23 July 2022 7:27:43.525521 am','creator':'<unknown>','modifier':'<unknown>'}">
~~~ 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].
~~~
</div>
<div st-class="LeTextSnippet"
st-data="OrderedDictionary{'id':'g3/gnFagDQCnl140BGDvjw==','parent':'aqbz43j9b455g8uxrazp5i9r','created':'16 July 2022 6:55:59.57116 pm','modified':'17 July 2022 10:04:21.17055 am','creator':'<unknown>','modifier':'<unknown>'}">
# Ideas sueltas
</div>
<div st-class="LeTextSnippet"
st-data="OrderedDictionary{'id':'twHZRGOgDQCng4eBDnOxMw==','parent':'g3/gnFagDQCnl140BGDvjw==','created':'17 July 2022 10:02:07.433421 am','modified':'17 July 2022 10:04:21.17055 am','creator':'<unknown>','modifier':'<unknown>'}">
Estas son algunas ideas en borrador.
No deberían considerarse como documentos orientados al lector, sino ayudas de memoria al autor.
</div>
<div st-class="LeTextSnippet"
st-data="OrderedDictionary{'id':'EwPgTxWZDQCwFSEVC1sUOQ==','parent':'g3/gnFagDQCnl140BGDvjw==','created':'15 April 2022 11:05:19.834036 am','modified':'17 July 2022 10:03:04.848332 am','creator':'<unknown>','modifier':'<unknown>'}">
## Lepiter con marcas extra
</div>
<div st-class="LeTextSnippet"
st-data="OrderedDictionary{'id':'UZAyUhWZDQCwGBlDC1sUOQ==','parent':'EwPgTxWZDQCwFSEVC1sUOQ==','created':'15 April 2022 11:06:01.536268 am','modified':'17 July 2022 10:03:04.848332 am','creator':'<unknown>','modifier':'<unknown>'}">
Algunas convenciones para procesar bloques podrían ayudar a las conversiones desde Lepiter a Markdeep/Markdown:
</div>
<div st-class="LeTextSnippet"
st-data="OrderedDictionary{'id':'x5Q2VRWZDQCwG2YaC1sUOQ==','parent':'EwPgTxWZDQCwFSEVC1sUOQ==','created':'15 April 2022 11:06:42.697368 am','modified':'15 April 2022 11:12:01.651704 am','creator':'<unknown>','modifier':'<unknown>'}">
* || Los siguientes elementos hijos deben ser procesados como una lista de items y este como su preámbulo:
</div>
<div st-class="LeTextSnippet"
st-data="OrderedDictionary{'id':'k2t7WRWZDQCwHcxkC1sUOQ==','parent':'x5Q2VRWZDQCwG2YaC1sUOQ==','created':'15 April 2022 11:07:58.577157 am','modified':'15 April 2022 11:08:00.386378 am','creator':'<unknown>','modifier':'<unknown>'}">
Item 1
</div>
<div st-class="LeTextSnippet"
st-data="OrderedDictionary{'id':'d5wnWhWZDQCwIKgcC1sUOQ==','parent':'x5Q2VRWZDQCwG2YaC1sUOQ==','created':'15 April 2022 11:08:04.884755 am','modified':'15 April 2022 11:08:06.949504 am','creator':'<unknown>','modifier':'<unknown>'}">
Item 2
</div>
<div st-class="LeTextSnippet"
st-data="OrderedDictionary{'id':'PrZsYRWZDQCwIk4RC1sUOQ==','parent':'x5Q2VRWZDQCwG2YaC1sUOQ==','created':'15 April 2022 11:10:07.470974 am','modified':'15 April 2022 11:12:01.651704 am','creator':'<unknown>','modifier':'<unknown>'}">
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
</div>
<div st-class="LeTextSnippet"
st-data="OrderedDictionary{'id':'yGz4bhWZDQCwJIhDC1sUOQ==','parent':'EwPgTxWZDQCwFSEVC1sUOQ==','created':'15 April 2022 11:17:19.899876 am','modified':'17 July 2022 8:46:27.436895 am','creator':'<unknown>','modifier':'<unknown>'}">
~~~ Lua linenumbers
print ("Esto debería aparecer con fuente de código
~~~
[Ejemplo [lua]: Ejemplos de código embebido.
</div>