From da071b2df7564fab34049bcc259a92231d78fdad Mon Sep 17 00:00:00 2001 From: dakkar Date: Tue, 18 Aug 2009 14:29:40 +0200 Subject: WebCoso docs --- src/SW/WebCoso/document.it.rest.txt | 121 ++++++++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 src/SW/WebCoso/document.it.rest.txt (limited to 'src/SW/WebCoso/document.it.rest.txt') 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/ + -- cgit v1.2.3