docs_src

Documentazione di Alan Italian

Questa è la cartella di lavoro per la creazione automatizzata della documentazione della libreria Alan Italian.

---

Indice dei contenuti

• Contenuti della cartella
• Introduzione
  • Organizzazione dei contenuti
  • Requisiti di sistema
  • Riguardo Doxter

---

Contenuti della cartella

• ./adoc/ — risorse per la toolchain HTML di Asciidoctor.
• ./haml/ — template Haml HTML personalizzati per Asciidoctor.
• ./sass/ — sorgenti Sass/SCSS di ../docs/css/styles.css.
• attributes-it.adoc — traduzione italiana attributi AsciiDoc (a cura di Marco Ciampa).
• DOCUMENTA.bat — script per generare la documentazione.
• index.asciidoc — homepage della documentazione.

Introduzione

La libreria Alan Italian è documentata nel formato AsciiDoc.

Questa cartella di lavoro contiene lo script per generare la documentazione, i vari sorgenti AsciiDoc (autogenerati e non) e altre risorse impiegate nel processo di creazione della documentazione HTML.

La documentazione HTML finale viene creata nella cartella ../docs/ del progetto.

Organizzazione dei contenuti

La documentazione è suddivisa in due gruppi:

• Documentazione dei moduli della libreria.
• Guida all'uso della libreria.

Il primo gruppo consiste in un documento di accompagnamento per ciascun modulo della libreria, generato tramite Doxter dai commenti nel codice dei moduli stessi. Questi documenti sono guide di riferimento ai singoli moduli, destinate sia agli autori di avventure che agli sviluppatori della libreria.

Il secondo gruppo è invece finalizzato a offrire una guida esaustiva all'uso della libreria, offrendo esempi pratici e spiegazioni dettagliate. I documenti di questo gruppo riutilizzano porzioni di testo e codice della documentazione dei moduli della libreria, importandoli tramite la direttiva include di Asciidoctor.

L'intero progetto della documentazione è basato sull'impiego di regioni taggate e il loro riutilizzo tramite inclusione. Poiché parti significative dei contenuti e del codice utilizzati nella documentazione vengono estratti direttamente dai sorgenti della libreria (tramite Doxter), questo approccio garantisce che la documentazione sarà sempre ed automaticamente aggiornata all'ultima versione del codice.

La seguente tabella illustra la catena di lavoro dei file della documentazione.

input Doxter	input Asciidoctor	output HTML
	./index.asciidoc	../docs/index.html
../alanlib_ita/libreria.i	./libreria.asciidoc	../docs/libreria.html
../alanlib_ita/lib_classi.i	./lib_classi.asciidoc	../docs/lib_classi.html
../alanlib_ita/lib_definizioni.i	./lib_definizioni.asciidoc	../docs/lib_definizioni.html
../alanlib_ita/lib_italian.i	./lib_italian.asciidoc	../docs/lib_italian.html
../alanlib_ita/lib_luoghi.i	./lib_luoghi.asciidoc	../docs/lib_luoghi.html
../alanlib_ita/lib_messaggi_libreria.i	./lib_messaggi_runtime.asciidoc	../docs/lib_messaggi_runtime.html
../alanlib_ita/lib_messaggi_runtime.i	./lib_messaggi_libreria.asciidoc	../docs/lib_messaggi_libreria.html
../alanlib_ita/lib_verbi.i	./lib_verbi.asciidoc	../docs/lib_verbi.html

I file AsciiDoc autogenerati tramite Doxter sono ignorati da Git, mentre i documenti gestiti manualmente sono parte integrante del progetto.

Requisiti di sistema

La creazione della documentazione è gestita da un singolo batch script per Windows:

• DOCUMENTA.bat

Per la creazione della documentazione finale in formato HTML, il progetto utilizza i seguenti strumenti:

• Doxter
• AsciiDoctor (Ruby)
• Highlight >= v3.49

Riguardo Doxter

I moduli sorgenti della libreria contengono la propria documentazione nei commenti del codice, impiegando il sistema di notazione di Doxter.

Lo script DOCUMENTA.bat gestisce in maniera automatica l'estrazione della documentazione AsciiDoc dai sorgenti della libreria e la conversione al formato HTML di tutta la documentazione del progetto.

Per maggior informazioni riguardo la suddivisione della documentazione in regioni taggate, vedi:

• DOXTER.md — Annotazioni Doxter.