================================
WebCoso - generatore di siti web
================================
:Id: SW/WebCoso
:CreationDate: 2009-08-18 11:26:45
:tags: - software
       - perl

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: https://docutils.sourceforge.net/rst.html
.. _`content negotiation`: https://httpd.apache.org/docs/2.2/content-negotiation.html
.. _XSLT: https://www.w3.org/TR/xslt.html
.. _WebCoso: https://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`: https://www.thenautilus.net/cgit/WebCoso/tree/lib/WebCoso/Maker.pm
.. _`Slay::Maker`: https://metacpan.org/dist/Slay-Maker
.. _`Template Toolkit`: https://metacpan.org/dist/Template-Toolkit
.. _`Text::Restructured`: https://metacpan.org/dist/Text-Restructured
.. _`XML::LibXSLT`: https://metacpan.org/dist/XML-LibXSLT
.. _rsync: https://www.samba.org/rsync/