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.en.rest.txt | 113 +++++++++++++++++++++++++++++++++ src/SW/WebCoso/document.it.rest.txt | 121 ++++++++++++++++++++++++++++++++++++ src/SW/WebCoso/du2html.xsl | 1 + 3 files changed, 235 insertions(+) create mode 100644 src/SW/WebCoso/document.en.rest.txt create mode 100644 src/SW/WebCoso/document.it.rest.txt create mode 120000 src/SW/WebCoso/du2html.xsl diff --git a/src/SW/WebCoso/document.en.rest.txt b/src/SW/WebCoso/document.en.rest.txt new file mode 100644 index 0000000..972d92e --- /dev/null +++ b/src/SW/WebCoso/document.en.rest.txt @@ -0,0 +1,113 @@ +============================ +WebCoso - web site generator +============================ +:CreationDate: 2009-08-18 13:26:45 +:tags: software + +The story +========= + +Read `the pre-history <../sitemake/>`_ if you're interested. + +The old system worked well enough, but I was getting tired of its +limitations: + +* the input was XHTML with annotations (for languages), and writing + XHTML by hand is a bit painful +* the structure was very rigid: + + - having more than two nesting levels of categories would have + required heavy changes to the compiler + - navigation would not have been not very comfortable, if I had + added many categories + +* these was no way to assign a document to more than one category + (the things that nowadays are called "tags") + +It was evidently the time to write (or find) something better. + +The functions I wanted were: + +- input in `reStructuredText`_ +- multi-language support: + + * each document can exists in different languages + * the user can go from one language to the other via links + * the web server must choose the right version using `content + negotiation`_ + +- presentation defined in XSLT_ +- each document must be able to define a specific presentation +- support for tags +- reduce to a minimum the amount of writing to create a new document + +After a few years of sporadic development, the result is 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/ + +How does it work +================ + +At the `heart of the thing`_ is a set of declarations for +`Slay::Maker`_; these define two passes [#]_: + +.. [#] asterisks stand for the language code + +1) generation of XML: + + * files called ``document.*.rest.tt`` are processed by + `Template Toolkit`_, producing files called + ``document.*.rest.txt`` + * files called ``document.*.rest.txt`` are processed by + `Text::Restructured`_ producing files called + ``document.*.du.xml`` + * files called ``feed.*.tt`` are processed by `Template + Toolkit`_ producing files called ``feed.*.xml`` + * from `reST`_ documents, the system extracts the tags with which + each document is associated, and the dates of creation and last + modification + * documents in the ``tags`` directory are processed like the + others, but only after the tag extraction + +2) generation of (X)HTML and feeds: + + * files called ``document.*.du.xml`` are processed by + `XML::LibXSLT`_ using the "stylesheet" ``du2html.xsl`` in the + same directory, producing files called ``document.*.html`` which + are stored in the destination directory + * files called ``feed.*.xml`` are processed by `XML::LibXSLT`_ + using the "stylesheet" ``fillFeed.xsl`` in the same directory, + producing files called ``feed.*.xml`` which are stored in the + destination directory + +Note that the modules that interface `Template Toolkit`_, +`Text::Restructured`_ and `XML::LibXSLT`_ to WebCoso_, export various +extension functions to allow access to the various data extracted +(tags, dates). + +At this point all files have been generated, and a couple of rsync_ +(one for the documents, one for images css etc.) will update the copy +on the web server. + +Future developments +=================== + +Feed generation is sub-optimal: to get the full text of the documents +inside the feeds, each document is transformed multiple times; I +should probably add a third pass, specific for feeds, to use the +already transformed documents. + +There are, surely, functions that are not exported to the templates, +and that one day I'll need: they're not hard to add. + +.. _`heart of the thing`: 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/ + 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/ + diff --git a/src/SW/WebCoso/du2html.xsl b/src/SW/WebCoso/du2html.xsl new file mode 120000 index 0000000..e2487e0 --- /dev/null +++ b/src/SW/WebCoso/du2html.xsl @@ -0,0 +1 @@ +../../../templates/du2html.xsl \ No newline at end of file -- cgit v1.2.3