imported "sitemake" documentation

3 files changed, 112 insertions, 0 deletions

diff --git a/src/SW/sitemake/document.en.rest.txt b/src/SW/sitemake/document.en.rest.txt
new file mode 100644
index 0000000..af0bfdf
--- /dev/null
+++ b/src/SW/sitemake/document.en.rest.txt
@@ -0,0 +1,56 @@
+=============================================
+SiteMake - how this site used to be generated
+=============================================
+:CreationDate: 2003-01-31 19:03:19
+:tags: software
+
+Motivations
+===========
+
+Ever since I discovered XML_ and XSLT_, I've been looking for an easy
+and confortable way to keep content and presentation totally
+separate. I started using XWeb_, which is a good program, but with
+some problems:
+
+* it's written in Java (OK, OK, this is personal taste)
+* it "tweaks" files to add (navigational) information, and I thought
+  it was not necessary
+* it does (did?) not have dependency control functionalities (like
+  ``make``)
+
+Shortly after version 0.3 I lost sync with the official codebase
+because of some modifications of mine, and I did not follow later
+developments.
+
+Given the high level of correctness attained by the `Gnome XSLT
+library`_, I decided to try and look if it was possible to use just
+``xsltproc`` and ``make`` to obtain the same results.
+
+So I developed a DTD to describe the structure of the site, a
+stylesheet to convert this structure into a makefile, and retouched
+the stylesheets to keep them working after the modifications.
+
+How it works
+============
+
+Given a description of the site's structure in the file
+``sitemap.xml``, the stylesheet ``compile.xsl`` generates a
+``Makefile`` containing rules for the transformation of every page,
+along with their prerequisites.
+
+In this way calling ``make`` causes the regenaration of only those
+files whose source have actually been modified. Moreover, each
+stylesheet implicitly gets two parameters: ``sitemapuri``
+containing the URI of the sitemap relative to the stylesheet, and
+``active`` which is an XPath expression indicating, inside
+the sitemap, the node corresponding to the page being
+transformed. This way the stylesheets can access all relevant
+navigational information.
+
+You can `consult the software's sources`__.
+
+.. _XML: http://www.w3.org/TR/REC-xml
+.. _XSLT: http://www.w3.org/TR/xslt
+.. _XWeb: http://xweb.sourceforge.net
+.. _`Gnome XSLT library`: http://xmlsoft.org/XSLT
+.. __: http://www.thenautilus.net/cgit/sitemake/
diff --git a/src/SW/sitemake/document.it.rest.txt b/src/SW/sitemake/document.it.rest.txt
new file mode 100644
index 0000000..e9310f3
--- /dev/null
+++ b/src/SW/sitemake/document.it.rest.txt
@@ -0,0 +1,55 @@
+===========================================
+SiteMake - come veniva generato questo sito
+===========================================
+:CreationDate: 2003-01-31 19:03:19
+:tags: software
+
+Le motivazioni
+==============
+
+Da quando ho scoperto `XML`_ e `XSLT`_, ho cercato un modo semplice e
+comodo per gestire in maniera del tutto separata contenuto e
+presentazione. All'inizio usavo `XWeb`_, ottimo programma, ma con
+alcuni difetti:
+
+* è scritto in Java (OK, OK, questa è una questione personale...)
+* "trucca" i file per aggiungervi informazioni (di navigazione), e io
+  pensavo non fosse necessario
+* non ha (aveva?) funzionalità di controllo dipendenze (tipo ``make``)
+
+Poco dopo la versione 0.3 ho perso la sincronizzazione con la codebase
+ufficiale a causa di qualche mia modifica al codice, e non ne ho più
+seguiti gli sviluppi.
+
+Dato l'ottimo livello di correttezza raggiunto dalla `libreria Gnome
+XSLT`_, ho deciso di vedere se fosse possibile usare soltanto
+``xsltproc`` e ``make`` per ottenere gli stessi effetti.
+
+Ho quindi sviluppato un DTD per descrivere la struttura del sito, uno
+stylesheet per convertire questa struttura in un makefile, e ho
+ritoccato gli stylesheet per adeguarli alle modifiche.
+
+Funzionamento
+=============
+
+Data una descrizione della struttura del sito, nel file
+``sitemap.xml``, lo stylesheet ``compile.xsl`` genera un ``Makefile``
+contenente le istruzioni per la trasformazione di tutte le pagine, e i
+loro prerequisiti.
+
+In questo modo, chiamando ``make`` vengono rigenerati soltanto i file
+i cui sorgenti sono stati effettivamente modificati. Inoltre, ad ogni
+stylesheet vengono passati implicitamente due parametri:
+``sitemapuri`` che indica la URI della sitemap relativa allo
+stylesheet, e ``active`` che è un'espressione XPath che identifica,
+dentro la sitemap, il nodo corrispondente alla pagina che si sta
+trasformando. In questo modo gli stylesheet possono accedere a tutte
+le informazioni di navigazione utili.
+
+Potete `consultare i sorgenti`__ del software.
+
+.. _XML: http://www.w3.org/TR/REC-xml
+.. _XSLT: http://www.w3.org/TR/xslt
+.. _XWeb: http://xweb.sourceforge.net
+.. _`libreria Gnome XSLT`: http://xmlsoft.org/XSLT
+.. __: http://www.thenautilus.net/cgit/sitemake/
diff --git a/src/SW/sitemake/du2html.xsl b/src/SW/sitemake/du2html.xsl
new file mode 120000
index 0000000..e2487e0
--- /dev/null
+++ b/src/SW/sitemake/du2html.xsl
@@ -0,0 +1 @@
+../../../templates/du2html.xsl
\ No newline at end of file