From 0b90ab5a97865119bc84b443dd94a3bdde85f54b Mon Sep 17 00:00:00 2001 From: dakkar Date: Tue, 18 Aug 2009 13:26:24 +0200 Subject: imported "sitemake" documentation --- src/SW/sitemake/document.en.rest.txt | 56 ++++++++++++++++++++++++++++++++++++ src/SW/sitemake/document.it.rest.txt | 55 +++++++++++++++++++++++++++++++++++ src/SW/sitemake/du2html.xsl | 1 + 3 files changed, 112 insertions(+) create mode 100644 src/SW/sitemake/document.en.rest.txt create mode 100644 src/SW/sitemake/document.it.rest.txt create mode 120000 src/SW/sitemake/du2html.xsl 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 -- cgit v1.2.3