WebCoso docs

3 files changed, 235 insertions, 0 deletions

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