266 lines
16 KiB
Markdown
266 lines
16 KiB
Markdown
---
|
|
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>
|
|
|