1 files changed, 121 insertions, 0 deletions
diff --git a/src/SW/WebCoso/document.it.rest.txt b/src/SW/WebCoso/document.it.rest.txt
new file mode 100644
index 0000000..5aa65ce
--- /dev/null
+++ b/src/SW/WebCoso/document.it.rest.txt
@@ -0,0 +1,121 @@
+================================
+WebCoso - generatore di siti web
+================================
+:CreationDate: 2009-08-18 13:26:45
+:tags: software
+
+La storia
+=========
+
+Leggetevi `la preistoria <../sitemake/>`_ se vi interessa…
+
+Il vecchio sistema funzionava abbastanza bene, ma mi stavo stufando
+delle sue limitazioni:
+
+* l'input era XHTML con annotazioni (per la lingua), e scrivere XHTML
+  a mano non è proprio agevole
+* la struttura era molto rigida:
+
+  - per avere più di due livelli di profondità nelle categorie
+    richiedeva di rivedere pesantemente il compilatore
+  - la navigazione non sarebbe stata proprio delle più comode, se
+    avessi aggiunto parecchie categorie
+
+* non c'era alcun modo di assegnare un documento a più di una
+  categoria (quelli che di questi tempi si chiamano "tag")
+
+Ovviamente era l'ora di scrivere (o trovare) qualcosa di meglio.
+
+Le funzioni necessarie erano:
+
+- input in `reStructuredText`_
+- supporto multilingua:
+
+  * ogni documento può essere presente in varie lingue
+  * l'utente deve poter passare da una lingua all'altra tramite link
+  * il server deve scegliere la versione giusta tramite "`content
+    negotiation`_"
+
+- presentazione definita in XSLT_
+- ogni documento deve poter definire una presentazione specifica
+- supporto di tag
+- ridurre al minimo la quantità di cose che devono essere scritte per
+  creare un nuovo documento
+
+Dopo qualche anno di lavoro molto sporadico, il risultato è WebCoso_
+
+.. _reST:
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+.. _`content negotiation`: http://httpd.apache.org/docs/2.2/content-negotiation.html
+.. _XSLT: http://www.w3.org/TR/xslt.html
+.. _WebCoso: http://www.thenautilus.net/cgit/WebCoso/
+
+Come funziona
+=============
+
+Al `centro di tutto`_ sta una serie di dichiarazioni per
+`Slay::Maker`_; queste definiscono due passate di elaborazione [#]_:
+
+.. [#] gli asterischi stanno per la sigla della lingua
+
+1) generazione XML:
+
+   * i file di nome ``document.*.rest.tt`` vengono elaborati da
+     `Template Toolkit`_, generando file di nome
+     ``document.*.rest.txt``
+   * i file di nome ``document.*.rest.txt`` vengono elaborati da
+     `Text::Restructured`_ generando file di nome
+     ``document.*.du.xml``
+   * i file di nome ``feed.*.tt`` vengono elaborati da `Template
+     Toolkit`_ generando file di nome ``feed.*.xml``
+   * dai documenti in `reST`_ vengono estratti i tag a cui ciascun
+     documento è associato, e le date di creazione e ultima modifica
+   * i documenti presenti nella directory ``tags`` sono elaborati come
+     gli altri, ma dopo che è avvenuta l'estrazione dei tag
+
+   Notare che, visto che stiamo usando un procedimento stile ``make``,
+   se ad esempio un ``document.it.rest.txt`` è già presente, il
+   programma non guarda neppure se ``document.it.rest.tt`` esista
+   (incidentalmente, la maggior parte di documenti non passa da
+   `Template Toolkit`_)
+
+2) generazione (X)HTML e feed:
+
+   * i file di nome ``document.*.du.xml`` vengono elaborati da
+     `XML::LibXSLT`_ usando lo "stylesheet" ``du2html.xsl`` presente
+     nella stessa directory, generando file di nome
+     ``document.*.html`` che finiscono nella opportuna directory di
+     destinazione
+   * i file di nome ``feed.*.xml`` vengono elaborati da
+     `XML::LibXSLT`_ usando lo "stylesheet" ``fillFeed.xsl`` presente
+     nella stessa directory, generando file di nome ``feed.*.xml`` che
+     finiscono nella opportuna directory di destinazione
+
+Notare che i moduli che interfacciano `Template Toolkit`_,
+`Text::Restructured`_ e `XML::LibXSLT`_ a WebCoso_ esportano varie
+funzioni di estensione in modo da permettere di accedere ai dati
+estratti (tag, date).
+
+A questo punto tutti i file sono stati generati, e un paio di `rsync`_
+(uno per i documenti, uno per immagini css etc.) aggiornano la copia
+sul server web.
+
+Sviluppi futuri
+===============
+
+La generazione dei feed è sub-ottimale: per avere il testo completo
+dei documenti all'interno dei feed, ciascun documento viene
+trasformato più volte del necessario; probabilmente dovrei aggiungere
+una passata specifica per i feed in modo da poter usare i documenti
+già trasformati.
+
+Sicuramente ci sono delle funzioni che non sono esposte ai template,
+ma che prima o poi serviranno: non è difficile aggiungerle.
+
+.. _`centro di tutto`: http://www.thenautilus.net/cgit/WebCoso/tree/lib/WebCoso/Maker.pm
+.. _`Slay::Maker`: http://search.cpan.org/dist/Slay-Maker/
+.. _`Template Toolkit`: http://search.cpan.org/dist/Template-Toolkit/
+.. _`Text::Restructured`: http://search.cpan.org/dist/Text-Restructured/
+.. _`XML::LibXSLT`: http://search.cpan.org/dist/XML-LibXSLT/
+.. _rsync: http://www.samba.org/rsync/
+