Motivación Este es un pequeño proyecto exploratorio surgió a partir de la regorganización que se hizo para que la documentación fuera más adecuada para auto-aprendizaje, como se explicó acá. Dicha regorganización mostró como estábamos teniendo, durante la documentanción el los pads, un conjunto de prácticas emergentes, referidas a etiquetar partes de documento con marcas como IMPORTANTE, ATENCIÓN, etc, que no eran muy bien preservadas por la variante de Markdown que es soportada nativamente en Fossil, pero que sí lo son es AsciiDoc, mejorando mucho la legibilidad y contribuyendo así a orientar a futuros lectores y aprendices sobre aspectos claves de lo que están conociéndo y practicando a través de los documentos.
Por lo anterior, exploraremos el soporte a AsciiDoc en Fossil y miraremos si algunas de estas lecciones pueden ser transladadas a soportar un mejor lenguaje de etiquetamiento para la documentación, que soporte las prácticas emergentes de la comunidad y las etiquetas ad hoc que vamos creando en los talleres y otros encuentros. Esto podría derivar en el uso más extenso de AsciiDoc, o la creación de una variante personalizada de Markdown, a la medida de nuestras practicas y necesidades de documentación, desde infraestructuras robustas como las ofrecidas por Pandoc o Lunamark y por tanto transportable a otros sistemas de documentación.
Referencias extra:
- AsciiDoc en la Wikipedia.
- What is AsciiDoc? Why do we need it?.
- Writing vs. typing: Separa las fases de escritura en pensar, teclear (typing) y editar y muestra maneras fluidas de escribir y lidiar con el síndrome de hoja en blanco, incluyendo escribir entradas al blog, recibir realimentación y compilarlas luego en partes del libro (muy parecido a lo propuesto por LeanPub.
- The Toolchain for My iOS Book: Un flujo de trabajo usando AsciiDoc para escribir un libro, similar al que viene a continuación, pero desde una mirada menos detallada y con editor de texto y control de versiones diferentes.
- Living the Future of Technical Writing: Explica un flujo de trabajo basado en AsciiDoc para documentación técnica, probadas con el libro ProGit, y ventajas del mismo sobre el uso de Markdown básico (muchas de tales limitaciones no existen con el Markdown de Pandoc).
- writing, the future, take 2: a better workflow, yes, but not git(hub): Una respuesta al texto anterior, resaltando las desventajas de GitHub, pero reconociendo las ventajas de un formato de etiquetamiento ligero para escritura y múltiples formatos de salida. Nosotros, con Grafoscopio hacemos lo propio: combinando el Markdown de Pandoc con el DVCS Fossil, que no tiene las desventajas de GitHub, ni se pone entre nosotros y la escritura. El autor tiene el (¿molesto?) "estilo" de jamás usar mayúsculas.
- writing, the future, take 3: 10 big points on future writing systems: Expansión sobre las ventajas del uso de texto plano para escritura. Particularmente interesantes los puntos relacionados con el remix y el trabajo en progreso, ampliando temas sobre los que ya hay propuestas como las de LeanPub.
- We will control our own culture: Del mismo autor de las dos anteriores, un manifiesto sobre cómo internet permite (aún) la desintermediación del acceso a la cultura y cómo puede permitirlo en el futuro, sí no permitimos o esquivamos los DRM y los protocolos que lo soporten.
- AsciiDoc Writer’s Guide.
- Asciidoctor User Manual.
- AsciiDoc Preview package: Paquete para [Atom][https://atom.io/], que mejora la experiencia de escritura con AsciiDoc.
- Editing AsciiDoc with Live Preview: extiende el tema anterior, para más plataformas, además de Atom.
- Plain-text diagrams take shape in Asciidoctor!: Cómo insertar
diagramas en AsciiDoc usando descripciones en texto plano.
- Conversaciones sobre AsciiDoc con motivo de un hilo en Hacker News sobre Scholarly Markdown. En particular, ver las diferencias frente al uso de listas en AsciiDoc versus Markdown y la idea de extender Pandoc, de maneras más lentas y no centradas en términos anglo.
- asciidoctor-bibtex: Adiciona soporte para referencias bibliográficas de BibTeX en AsciiDoc.
- Asciidoctor PDF: A native PDF converter for AsciiDoc.
- AsciiDoc: Preguntas Frecuentes.
- Antora: Un generador de sitios estáticos para crear lugares web de documentación
a partir de múltiples sistemas de control de versiones, que usa AsciiDoc.
- Referencing Pages: Muestra un esquema alternativo de enlaces entre páginas, para documentación técnica. Algunos ideas de enlaces portables podrían servir para complementarlas con ideas sobre enlaces cortos con identificadores únicos en Grafoscopio.
- Content is Sovereign:
Habla sobre cómo Antura usa distintos repositorios y un libro de configuración,
llamado Playbook para definir cómo estos documentos serán creados.
Algunas ideas podrían ir para el nodo
%metadataen Grafoscopio. - OpenDevise: La compañia detrás de Antora, centrada en flujos y herramientas ágiles alredor de la documentación.
- Integración Fossil AsciiDoc:
- Sobre asciidoc.js, una biblioteca que permitiría incorporar AsciiDoc a Fossil vía JavaScript:
- Asciidoctor.js: AsciiDoc in JavaScript powered by Asciidoctor.
- asciidoctor.js - Render AsciiDoc in your browser!.
- Asciidoctor.js User Manual.
- Fossil Cookbook: Muestra varias recetas para extender Fossil, vía JavaScript, particularmente añadiendo source hilighting y editores WYSIWYG.
- microjs: Un listado de aplicaciones minimalistas en JavaScript, como scaleApp y muchas más, que podrían incorporarse a Fossil, en caso de ser necesario.
- Admonitions:
- Help on Smileys: Un lenguaje de signos, que se podría usar como inspiración para una extensión de Pandoc que permita hacer admonitions similares a las de AsciiDoc, sin emplear el inglés para ello.
- Pandoc: Divs and Spans: Otra alternativa a explorar para los admonitions.
- Lunamark: Una rápida, extensible y pequeña librería de Lua, que soporta Markdown extendido con algunos elementos de Pandoc. Este quizás sería el camino de integración más adecuado hacia un Fossil más versátil y sin embargo ligero respecto a sus posibilidades y requerimientos.
- Sobre asciidoc.js, una biblioteca que permitiría incorporar AsciiDoc a Fossil vía JavaScript: