Al utilizar nuestro sitio web, usted acepta que utilicemos cookies. Más información

| Acepta

Blog

Un nuevo manual escrito en AsciiDoc

Parte 1

Portada del manual de Merlin Project

Estamos optimizando constantemente Merlin Project para facilitar su uso. Ya empezamos hace tiempo con el diálogo de inicio y la puesta en orden del inspector.

Con la versión 8, ha llegado la ayuda dinámica: Sólo tienes que hacer clic en el símbolo ? y obtendrás un texto de ayuda explicativo para cada objeto que señales con el ratón (o con el dedo en el iPad). Incluso puede crear sus propios textos de ayuda para sus propios campos.

Pero lamentablemente nuestro manual está un poco atrasado. Pero no te preocupes, hay una amplia y actualizada documentación, como:

Pero por el momento no existe un manual completo. Y eso es exactamente lo que me gustaría cambiar ahora.

El proyecto

Recientemente he empezado a reescribir el manual y a crear esta misma referencia. Por supuesto, he creado un proyecto para esto, pero desgraciadamente tiene que compartir el tiempo disponible con todos mis otros proyectos.

El objetivo

Además del objetivo obvio de crear una documentación actualizada de las funciones de Merlin Project en los idiomas más importantes, me he propuesto algunas submetas o subobjetivos más:

Sin embargo, la fecha prevista está completamente abierta a toda planificación, ya que tengo una carga de trabajo variable de una semana a otra. Así que una fecha fija como objetivo sería completamente irreal.

Las herramientas

En ProjectWizards escribimos todo el texto en formato ascii y lo registramos en nuestro git como muy tarde al final del día.

En contra de la moda actual, no escribimos en Markdown ni en ninguno de sus derivados o suplementos. Ya nos centramos en AsciiDoc hace mucho tiempo y desde hace unos años en el nuevo Asciidoctor, la nueva implementación de Dan Allen (vía Twitter). Los motivos de esta decisión son principalmente:

  • Variables,
  • vinculación de otros archivos,
  • textos y formatos condicionales,
  • tablas, diagramas y muchos otros contenidos,
  • salida de texto en muchos formatos diferentes,
  • índices automáticos, así como glosarios, índices y bibliografías
  • y mucho más...

Y antes de que se me olvide, por supuesto, BBEdit sigue siendo el editor número 1 para mí.

AsciiDoc vs Asciidoctor

En resumen, le das la fuente de AsciiDoc a Asciidoctor y obtienes un resultado que puedes publicar. Así que:

  • AsciiDoc es el lenguaje
  • Asciidoctor es el procesador

Al igual que Markdown, AsciiDoc fue diseñado como un lenguaje para ser discreto y conciso, y para hacer la escritura más fácil, incluso más agradable. Pero AsciiDoc en sí no es un formato de publicación. Es más bien una taquigrafía. Aquí es donde entra en juego un procesador AsciiDoc.

Un procesador AsciiDoc, como Asciidoctor, lee el texto fuente AsciiDoc y lo convierte en formatos publicables como HTML 5, eBook o PDF. Por supuesto, todo el proceso se complementa con herramientas de diseño como las hojas de estilo en cascada (CSS).

Trabajar en voz alta (WOL)

De acuerdo con el espíritu de Working out Loud, intentaré informar regularmente sobre este trabajo. Haré menos hincapié en el número de palabras o frases que he podido escribir durante la semana. Estoy mucho más interesado en presentar ayudas y nuevos conocimientos sobre Asciidoc y Asciidoctor.

Con este enfoque, por supuesto, también estoy honrando el incansable trabajo de Dan Allen y apoyándolo. Al menos, esto es un voto para Asciidoc en la gestión de proyectos.

El próximo viernes empezaremos en este punto.


Continuación - Un nuevo manual en AsciiDoc, parte 2

Publicado por Frank Blome on 08.10.2021 en Internas
Etiquetas: asciidoc asciidoctor proyecto-manual wol

Merlin Project en el Mac y el iPad

Sus ideas, nuestra magia – ¡realice proyectos de forma sencilla!
Pruebe ahora 30 días de forma gratuita.