Documentazione sin da subito con AsciiDoc & AsciiDoctor

Viene citato Linus Torvalds nel sito di AsciiDoctor

 Use AsciiDoc for document markup. Really. 
 It's actually readable by humans, easier to parse 
 and way more flexible than XML

Bruce Eckel ne parla in un post dove si limita a dire

I'll keep my eye on AsciiDoc

mettendo a confrondo asciiDoc a markdown.

Obiettivo

Vogliamo creare la documentazione a partire dai nostri file asciidoc

Cosa Installare

$ sudo gem install asciidoctor
$ sudo gem install pygments.rb

Generiamo la documentazione

$ asciidoctor -a toc2 index.asciidoc

se volete generare senza table of contents basta chiamare

$ asciidoctor index.asciidoc

se dovessimo incontrare errori del tipo:

only book doctypes can contain level 0 sections

un workaround è aggiungere -d book

asciidoctor -a toc2 -d book index.asciidoc

ed otteniamo il risultato sperato  nel formato html

generiamo poi lo stesso contenuto in formato pdf

gem install --pre asciidoctor-pdf

asciidoctor-pdf -d book index.asciidoc

per installarlo e generare la documentazione in pdf.

Naturalmente anche questo post è stato generato da file plain-text
scritti in asciidoc

Voi cosa usate per mettere a corredo del vostro codice
della documentazione?

AsciiDoctor

scritto il post con Atom e il package atom-asciidoc-preview per la preview

Condividi:

Leave a Reply

Your email address will not be published. Required fields are marked *

Il presente sito Web utilizza cookie tecnici e di profilazione di terze parti per migliorare l'esperienza di navigazione. Puoi usare il sito senza cambiare le impostazioni dei cookie o cliccare su Accetta per acconsentire il loro utilizzo. Informazioni

The cookie settings on this website are set to "allow cookies" to give you the best browsing experience possible. If you continue to use this website without changing your cookie settings or you click "Accept" below then you are consenting to this.

Close