Ieri stavo chiacchierando con Paolo dei miei ultimi "smanettamenti".
Nel tentativo di far passare la documentazione di un progetto da Markdown
a Asciidoc ho dovuto trovare un sostituto all'ottimo mkdocs
(https://www.mkdocs.org/) e così ho scoperto nell'ordine:
- Opal (https://opalrb.com/) un source-to-source compiler o meglio
un "transpiler" (ecco il termine che non ricordavo Paolo!)
(https://en.wikipedia.org/wiki/Source-to-source_compiler)
e che permette a antora, scritto in javascript, di compilare
asciidoc usando asciidoctor che in origine è scritto in ruby...
devo dire che mi si è aperto un mondo (o meglio un vaso di pandora...)
> Ieri stavo chiacchierando con Paolo dei miei ultimi "smanettamenti".
>
> Nel tentativo di far passare la documentazione di un progetto da Markdown
> a Asciidoc ho dovuto trovare un sostituto all'ottimo mkdocs
> (https://www.mkdocs.org/) e così ho scoperto nell'ordine:
[..]
Posso chiederti il perché del passaggio da Markdown a Asciidoc (es
limiti mi markdown che non potevi superare, ecc).
Perché markdown è, per essere gentili, un non-standard.[0]
E perché non direttamente sphinx/rst ?
Sebbene rst sia interessante come formato, (IMHO) sicuramente meglio di
markdown, più completo e senza "dialetti", asciidoc è migliore sotto
molti punti di vista (vedi per esempio le tabelle). Peraltro mi pare ci
sia una specifica[1] ma nessun tentativo di riconoscimento come "standard".
Sphinxs è uno strumento eccezionale, peccato ci sia solo un modulo per
generare asciidoc da rst[2] e non per gestire direttamente la
documentazione in formato asciidoc.
La specifica ufficiale di asciidoc è attualmente stata presa in carico da
Eclipse Fundation[3].
Al solito su wikipedia c'è una brevissima paginetta esplicativa:
comunque, per farla breve, quasi tutto o tutto che trovi in md puoi farlo
anche in adoc, il contrario non è sempre vero. Ma quello che preoccupa di
più è che non c'è nessuna garanzia che quello che si è scritto in md,
sarà in futuro riutilizzabile senza doverlo rielaborare.