Reverse‐engineering 170K LOC de documentación para traerla al siglo XXI
'cramm' AKA Ramiro Morales
Encuesta rápida
¿Qué editor de texto usas?
Que comience la guerra :-)
Enfoquémonos en la documentación
Emacs
Visual Studio Code
Sublime Text
PyCharm
¿Y Vim?
Vim :(
Vim :(
What about Neovim?
What about Neovim?
“Literally the future of Vim”
Literalmente el futuro de Vim
What about Neovim?
El formato está destinado a y limitado por una restricción importantísima:
La salida debe funcionar en una consola de 80 caracteres de ancho.
Los resultados de esta restricción están presentes aún en los intentos de generar un formato mas amigable con salida HTML como vimhelp.appspot.com
Vim
Masivamente documentado
$ git clone https://github.com/vim/vim $ cd vim $ wc -l runtime/doc/*.txt ... 177412 total
- Realmente bien documentado
- Tiene guia de usuario y Una referencia completísima
Vim
Fuertemente cross-linked
$ wc -l runtime/doc/tags
9842 runtime/doc/tags¿Sería posible mejorar la apariencia de la documentación de Vim?
- Esta es la motivacion de este proyecto
- Aprender
- Divertirse
- Ojo: No es solamente estético sino tambien mejorar como vremos mas adelante (crear un codigo fuente semantico)
¿Sería posible?
Obtener resultado final
- Visualmente rico
- Multi-plataforma
PDF, ebook, iPad, consola, ...
Vim y su formato de documentación Sui generis: Vimdoc
Vimdoc
- Especificación muy básica
- Orientado a presentación en pantalla
Vimdoc
Referencias cruzadas
- Destino de referencia: *destino*
- Referencia: |destino|
Vimdoc
Referencias cruzadas
Ejemplo
Un click en este |enlace| te lleva a ese punto en el documento en el cual existe el destino de esa referencia. [...] *enlace* Destino de referencia, el click te trae aquí.
Vimdoc
Referencias cruzadas II
- Destino de referencia: *'option_name'*
- Referencia: 'destino'
Vimdoc
Referencias cruzadas II
Ejemplo
Un click en este nombre de opción 'textwidth' te lleva al punto en
el documento en el cual se describe esa opción.
[...]
Invisible en rendering final -> *'textwidth'*
'textwidth'
Maximum width of text that is being inserted. A longer line will be
broken after white space to get this width.Vimdoc
Ejemplos de código
- Línea previa termina en '>'
- Texto del ejemplo justificado
- Ejemplo termina en 1ra. línea que no tiene espacio en columna 1
- Otra forma de marcar final: '<' en columna 1
Vimdoc
Ejemplos de código
On Unix systems "~user" can be used too. It is replaced by the home directory
of user "user". Example: >
:set path=~mool/include,/usr/include,.
On Unix systems the form "${HOME}" can be used too. ...Características de Vimdoc
Puramente visuales:
- Línea termina en ' ~': Se colorea de forma diferente
- Prefijo 'CTRL-'
- '<PageUp>'
- Palabras 'Note', 'Notes'
Vimdoc
Eso es todo
Y ese es el problema
Al estar sub-especificado, deja mucho terreno librado a la interpetación
Especificacion principalmente enfocada en lo visual + Diferentes autores = Altamente inconsistente
Lightweight markup languages (LML)
Lightweight markup languages
- reStructuredText (AKA reST)
- Markdown
- AsciiDoc
- ...
Lightweight markup languages
- WYSIWYM
- Se integran mejor con sistemas SCM
- No es necesario el uso de un editor GUI
Markdown
- Popular
- Simple
reStructuredText
- Popular en comunidad Python
- Sphinx -> difundido mas generalmente
- Un lugar en nuestro <3 al haber nacido en la comunidad Python
AsciiDoc
- Creado en 2002
- Python 2.x
- http://www.methods.co.nz/asciidoc/
AsciiDoc
Tiene dos partes:
- La especificación de formato de LML AsciiDoc
- La herramienta asciidoc(1)
Ejemplos de uso de AsciiDoc
Git
- Manual del usuario
- Manpages (man git y git help foo)
Ejemplos de uso de AsciiDoc
Kernel Linux (brevemente)
- kernel-doc
- Uso de LML en C source code comments
Ejemplos de uso de AsciiDoc
Kernel Linux (brevemente)
- 2015: Plain text -> (2015) Markdown
- 2015: Markdown -> AsciiDoc
- 2016: AsciiDoc -> reST (Sphinx)
Problema: asciidoc(1) is dead
No tiene mantenimiento desde Nov 2013
OJO: La herramienta, no la especificación
Enter Asciidoctor
Asciidoctor
- Sucesor oficial de AsciiDoc
- Ruby
- https://asciidoctor.org/
Asciidoctor
Implementa y extiende la especificación de LML AsciiDoc
Asciidoctor
También:
- Bindings Java (AsciidoctorJ)
- Implementación JS (Asciidoctor.js)
Legibilidad vs. Features
En los Lightweigth Markup Languages: Legibilidad y features -> Naturalmente existe una tensión entre ambos
Legibilidad vs. Features
Markdown
Por diseño:
- Debe ser legible
- Explicitamente sólo para salida HTML
Legibilidad vs. Features
Markdown
Features -> Diáspora
- GitHub‐Flavored Markdown
- CommonMark
- ...
- Hay necesidad de aplicar markdown a documentos mas complejos
- Pero eso entra en conflicto con el objetivo de su diseño por parte de John Gruber su creador
- Esa es la razón por la que nacen tantas variaciones/forks. Y porque está under-specified
Legibilidad vs. Features
Markdown
No nos sirve para modelar la documentación de Vim
Recordar: Esto es asi por una decisión de diseño de Markdown
Legibilidad vs. Features
reStructuredText
- Fuertemente especificado
- Mas features que Markdown
- Todavía insuficiente para modelar la documentación de Vim
Too much reliance on indenting
¿Porqué Asciidoc?
Explícitamente creado para "seguir" a DocBook
Asciidoc:
- Semánticamente similar a DocBook
- Sintácticamente menos complejo (no XML!)
¿Porqué Asciidoc?
DocBook tiene los features necesarios para modelar la documentación de Vim
Docbook (ya AsciiDoc) estan creados para poder escribir libros y manuales técnicos
github.com/ramiro/vimdocs
¡Toda ayuda es bienvenida!
Podria ser de interés para:
- Documentation junkies
- Parser junkies
- ¿ML junkies?
github.com/ramiro/vimdocs
Estado actual
Mostrar algunos archivos HTML de salida en un browser Web
github.com/ramiro/vimdocs
Estado actual
github.com/ramiro/vimdocs
Sabemos que no será posible automatizar completamente la conversión
El desafío es reducir el trabajo manual al mínimo posible
github.com/ramiro/vimdocs
¿Ideas?
- ¿Crear un AST y en base al mismo crear el codigo fuente AsciiDoc?
- ¿Un backend formatter Vimdoc? (full Vimdoc <-> Asciidoc roundtrip)
- ...
Q/A
¡Gracias!
@ramiromorales
Fin
Colofón
- Hovercraft!, Lennart Regebro
- Libre Baskerville, Impallari Type