moved stuff around

it's a good idea to separate the documents from the templates

11 files changed, 319 insertions, 0 deletions

diff --git a/src/SW/du2html.xsl b/src/SW/du2html.xsl
new file mode 120000
index 0000000..911609c
--- /dev/null
+++ b/src/SW/du2html.xsl
@@ -0,0 +1 @@
+../../templates/du2html.xsl
\ No newline at end of file
diff --git a/src/SW/kanatrain/document.en.rest.txt b/src/SW/kanatrain/document.en.rest.txt
new file mode 100644
index 0000000..40fe770
--- /dev/null
+++ b/src/SW/kanatrain/document.en.rest.txt
@@ -0,0 +1,30 @@
+KanaTrain
+=========
+:CreationDate: 2003-01-20 10:09:25
+:tags: - software
+       - japanese
+
+``kanatrain.pl`` is a program to help memorize japanese phonetic
+characters, in particular hiragana (平仮名). It requires a Perl
+interpreter, version 5.6.0 or later (but it won't work with Perl 6)
+and a terminal capable of displaying glyphs specified with UTF-8.
+
+The program contains two exercises: in the first one you're presented
+with a hiragana and you should write its pronounciation. To avoid
+ambiguities is best to write it after the *Kunrei* romanization (ち
+'ti', し 'si', ぢ 'di') instead of the more common *Hepburn* (ち
+'chi', し 'shi', ぢ 'ji'). If you make a mistake the correct
+pronounciation will be shown, along with the hiragana corresponding to
+the one you gave (if any).
+
+In the second exercise you're presented with a pronunciation (written
+after the *Kunrei* system) and five different hiragana characters,
+where only one is the right one. You should write the number relative
+to the right one. If you make a mistake the correct hiragana will be
+shown, along with the pronunication of the one you chose.
+
+To end each exercise just give an empty answer.
+
+The source_ is a single file.
+
+.. _source: /src/kana-train.pl
diff --git a/src/SW/kanatrain/document.it.rest.txt b/src/SW/kanatrain/document.it.rest.txt
new file mode 100644
index 0000000..cde9474
--- /dev/null
+++ b/src/SW/kanatrain/document.it.rest.txt
@@ -0,0 +1,30 @@
+KanaTrain
+=========
+:CreationDate: 2003-01-20 10:09:25
+:tags: - software
+       - japanese
+
+``kanatrain.pl`` è un programma per aiutare a memorizzare i caratteri
+fonetici giapponesi, in particolare i hiragana (平仮名). Richiede un
+interprete Perl versione 5.6.0 o successive (ma non funzionerà col
+Perl 6) e un terminale capace di visualizzare caratteri in UTF-8.
+
+Il programma prevede due esercizi: nel primo viene mostrato un
+hiragana e bisogna inserirne la pronuncia. Per problemi di ambiguità è
+preferibile inserirla secondo la romanizazione *Kunrei* (ち 'ti', し
+'si', ぢ 'di') piuttosto che la più comune *Hepburn* (ち 'chi', し
+'shi', ぢ 'ji'). Quando si sbaglia viene mostrata la pronuncia
+corretta, e lo hiragana corrispondente alla pronuncia inserita (se
+esiste).
+
+Nel secondo esercizio viene proposta una pronuncia (scritta secondo il
+sistema *Kunrei*) e cinque scelte di hiragana diversi, di cui solo uno
+è giusto.  Bisogna inserire il numero corrispondente a quello
+giusto. Se si sbaglia, viene mostrato lo hiragana giusto e la
+pronuncia di quello scelto.
+
+Per terminare ciascun esercizio basta dare una risposta vuota.
+
+Il sorgente_ è un singolo file.
+
+.. _sorgente: /src/kana-train.pl
diff --git a/src/SW/kanatrain/du2html.xsl b/src/SW/kanatrain/du2html.xsl
new file mode 120000
index 0000000..e2487e0
--- /dev/null
+++ b/src/SW/kanatrain/du2html.xsl
@@ -0,0 +1 @@
+../../../templates/du2html.xsl
\ No newline at end of file
diff --git a/src/SW/kblayout/document.en.rest.txt b/src/SW/kblayout/document.en.rest.txt
new file mode 100644
index 0000000..f609813
--- /dev/null
+++ b/src/SW/kblayout/document.en.rest.txt
@@ -0,0 +1,63 @@
+Optimize keyboard layout
+========================
+:CreationDate: 2003-01-28 10:09:25
+:tags: - software
+       - keyboard
+
+I'm sure you, too, know the history of the Sholes ("QWERTY") keyboard,
+that was designed to avoid that too fast typists jammed mechanical
+typewriters. You would know also that the Dvorak layout is cosidered
+by many to be faster and more effective.
+
+When I tried to learn to use the Dvorak keyboard, a friend of mine
+asked me: «Why don't you write a program to measure your keyboard
+usage, and then obtain a personalized layout?». In a moment of
+crazyness, I decided to do just that.
+
+The first program is freq.pl_, which reads the files given on the
+command line and produces a probability matrix, writing it into the
+file whose name is in the ``$MATRFN`` variable, default
+``/tmp/freq.matr``. Actually it sees the text as a Markov process over
+the characters with memory 1, and extracts the transition
+matrix. Note: the elements are frequencies, not probabilities. The
+optional normalization is left as exercise to the reader.
+
+The second program is freqdump.pl_, which is probably
+useless. I've written it (three or four different versions) to have an
+idea about the frequencies. Give it a look if you want.
+
+The most useful program (I hope) is optkeyb.pl_, which starting
+from the matrix (as usual, filename hardcoded) and the QWERTY layout
+searches by stochastic gradient descent a better layout. In other
+words, it calculates a value for the layout (sum over the pairs of
+keys of their distance times the frequency of that pair), then tries
+to exchange two random keys looking for a better result.  To avoid
+local minima (there are a lot) it starts by randomly exchanging
+``$PRE_SHUFFLE`` pairs, and if it doesn't find a better layout for
+``$STARVATION`` tries it starts again, after having written the
+locally optimum layout at the end of the file ``/tmp/layouts``. It
+uses curses and the corresponding Perl module ``Curses.pm``.
+
+To avoid bad things, like numbers scattered between other keys, it's
+possible to set into the ``%locked`` hash the keys that must not be
+moved.
+
+To give yoy an idea of the results, after some hours of computation
+the best layout was::
+
+    ` 1 2 3 4 5 6 7 8 9 0 ; =
+       - x w h t s a l b y ' j q
+       z \ [ c i e r u p . ,
+        k v f d n o m g ] /
+
+Bear in mind I use a IBM U.S. keyboard, and where the ``q`` is,
+there's usually the backslash/pipe key, which is larger than the
+others, so I should have locked it...
+
+To have an idea of the optimization, the value relative to the QWERTY
+layout is 10.190.280, for the one above is 6.797.370, meaning a 34%
+reduction in the space travelled by the fingers during writing.
+
+.. _`freq.pl`: /src/freq.pl
+.. _`freqdump.pl`: /src/freqdump.pl
+.. _`optkeyb.pl`: /src/optkeyb.pl
diff --git a/src/SW/kblayout/document.it.rest.txt b/src/SW/kblayout/document.it.rest.txt
new file mode 100644
index 0000000..cf92e2d
--- /dev/null
+++ b/src/SW/kblayout/document.it.rest.txt
@@ -0,0 +1,64 @@
+Migliorare il layout di tastiera
+================================
+:CreationDate: 2003-01-28 10:09:25
+:tags: - software
+       - keyboard
+
+Conoscerete anche voi la storia della tastiera Sholes ("QWERTY"), che
+è stata inventata per evitare che i dattilografi troppo veloci
+facessero inceppare i martelletti delle macchine per scrivere
+meccaniche. Saprete anche che il layout Dvorak è da molti considerato
+più efficace e veloce.
+
+Quando provai a imparare a usare la tastiera Dvorak, un mio amico mi
+disse pressappoco: «Perché non scrivi un programma che misuri l'uso
+che fai tu della tastiera, e ricavi un layout personalizzato?». In un
+momento di follia, ho deciso di farlo davvero.
+
+Il primo programma è freq.pl_, che legge i file dati a riga di
+comando e calcola una matrice di probabilità (nel file il cui nome è
+nella variabile ``$MATRFN``, al momento ``/tmp/freq.matr``). In
+effetti tratta il testo come un processo di Markov sui caratteri a
+memoria 1, e ricava la matrice di transizione. Nota: gli elementi sono
+frequenze, non probabilità. L'eventuale normalizzazione è lasciata
+come esercizio al lettore.
+
+Il secondo programma è freqdump.pl_, che probabilmente non serve a
+niente. L'ho scritto (tre o quattro versioni diverse) per avere
+un'idea di come fossero le frequenze. Dateci un'occhiata se volete.
+
+Il programma più utile (spero) è optkeyb.pl_, che parte dalla
+matrice (al solito, nome di file hardcoded) e dal layout QWERTY
+cercando per discesa di gradiente stocastica un layout migliore. In
+parole povere, calcola un valore per il layout (somma sulle coppie di
+tasti della distanza per la frequenza), poi prova a scambiare due
+tasti a caso e vedere se il risultato è migliore. Per aggirare i
+minimi locali (e ce ne sono tanti) all'inzio scambia a caso
+``$PRE_SHUFFLE`` volte, e se per ``$STARVATION`` tentativi non ha
+trovato un miglioramento ricomincia, dopo aver appeso il layout
+localmente ottimo al file ``/tmp/layouts``. Usa le curses e il
+corrispondente modulo Perl ``Curses.pm``.
+
+Per evitare cose brutte (i.e. i numeri a spasso) nell'hash ``%locked``
+è possibile impostare i tasti che non si vogliono spostare.
+
+Per dare un'idea dei risultati, dopo qualche ora di calcoli il miglior
+layout era::
+
+    ` 1 2 3 4 5 6 7 8 9 0 ; =
+       - x w h t s a l b y ' j q
+       z \ [ c i e r u p . ,
+        k v f d n o m g ] /
+
+Tenete conto che io uso una tastiera IBM U.S., e dove è finita la
+``q`` c'era il tasto pipe/backslash (che è più largo degli altri, e
+quindi avrei dovuto bloccarlo...)
+
+Per dare un'idea del miglioramento, il valore calcolato per la QWERTY
+è 10.190.280, per quella riportata sopra è 6.797.370, che si traduce
+in una riduzione del 34% del chilometraggio delle dita durante la
+battitura.
+
+.. _`freq.pl`: /src/freq.pl
+.. _`freqdump.pl`: /src/freqdump.pl
+.. _`optkeyb.pl`: /src/optkeyb.pl
diff --git a/src/SW/kblayout/du2html.xsl b/src/SW/kblayout/du2html.xsl
new file mode 120000
index 0000000..e2487e0
--- /dev/null
+++ b/src/SW/kblayout/du2html.xsl
@@ -0,0 +1 @@
+../../../templates/du2html.xsl
\ No newline at end of file
diff --git a/src/SW/kblayout/index/du2html.xsl b/src/SW/kblayout/index/du2html.xsl
new file mode 120000
index 0000000..7364257
--- /dev/null
+++ b/src/SW/kblayout/index/du2html.xsl
@@ -0,0 +1 @@
+../../../../templates/du2html.xsl
\ No newline at end of file
diff --git a/src/SW/pmset-linux-workaround/document.en.rest.txt b/src/SW/pmset-linux-workaround/document.en.rest.txt
new file mode 100644
index 0000000..c510d0f
--- /dev/null
+++ b/src/SW/pmset-linux-workaround/document.en.rest.txt
@@ -0,0 +1,63 @@
+===================================
+ Waking up a Mac at a certain time
+===================================
+:CreationDate: 2008-10-02 18:10:00
+:tags: software
+
+I have an old G3 iBook that I use to perform backups (using
+rsnapshot_). The scripts that run the backup process start it as soon
+as the machine wakes up, and put it back to sleep afterwards (using
+pbbuttonsd_). Problem: every time I want to run a backup, I have to
+manually wake the machine up (by pressing the power button, or opening
+the lid). Clearly I'd like for the backup to happen ever if I forget,
+or if I'm not at home.
+
+How it works on `Mac OS X`
+==========================
+
+If that iBook were running `Mac OS X`, it would be easy::
+
+  pmset repeat wake MTWRFSU 05:00:00
+
+and it would wake up automatically, every day at 5 in the morning
+(those letters are ugly abbreviations for the English names of the
+days of the week).
+
+But I have Linux running on that machine!
+
+Can it be done in Linux?
+========================
+
+It seems it can't: ``drivers/macintosh/via-pmu.c``, the Power
+Management Unit's driver, implements only a couple of functions.
+
+How did I manage?
+=================
+
+Using a trick. I started with the `Mac OS X` 10.4 installation disk,
+opened a Terminal, and run ``pmset``. Which did not work, giving me an
+error 0xe00002bc. Digging a bit on the Web we discover that such error
+means more or less "I can't write a file". *Write a file*? Whoever
+asked for such a thing?
+
+Reading more attentively the documentation_ for ``pmset``, we discover
+that it writes a couple of file in
+``/Library/Preferences/SystemConfiguration``. Obviously, having booted
+off a CD, that directory is read-only.
+
+I can't find a way to create a ``tmpfs`` or similar, so I take a USB
+stick and try to mount it. It does not work: there are no drivers for
+`FAT`, or something. OK, I just format it `HFS`, and finally I mount
+it::
+
+  mount -o union -t hfs /dev/disk5s1 /Library/Preferences/SystemConfiguration
+
+I re-run ``pmset``, nd finally the configuration is set.
+
+.. _rsnapshot: http://www.rsnapshot.org/
+
+.. _pbbuttonsd: http://pbbuttons.berlios.de/
+
+.. _documentazione:
+   http://developer.apple.com/documentation/Darwin/Reference/ManPages/man1/pmset.1.html
+
diff --git a/src/SW/pmset-linux-workaround/document.it.rest.txt b/src/SW/pmset-linux-workaround/document.it.rest.txt
new file mode 100644
index 0000000..472c9b6
--- /dev/null
+++ b/src/SW/pmset-linux-workaround/document.it.rest.txt
@@ -0,0 +1,64 @@
+=====================================
+ Svegliare il Mac a un'ora stabilita
+=====================================
+:CreationDate: 2008-10-02 18:10:00
+:tags: software
+
+Ho un vecchio iBook G3 che uso per fare i backup (tramite
+rsnapshot_). Gli script che ho si occupano del backup lo avviano
+appena la macchina si sveglia, e poi la ri-addormentano (usando
+pbbuttonsd_). Problema: tutte le volte che voglio lanciare un backup,
+devo svegliarlo manualmente (premendo il pulsante di accensione, o
+aprendo il coperchio/schermo). Ovviamente vorrei che i backup
+avvenissero anche se mi scordo, o se non sono a casa.
+
+Come funziona col `Mac OS X`
+============================
+
+Se su quel iBook girasse `Mac OS X`, sarebbe facile::
+
+  pmset repeat wake MTWRFSU 05:00:00
+
+e si sveglierebbe in automatico ogni giorno alle 5 del mattino (quelle
+lettere sono abbreviazioni brutte per i giorni della settimana in
+Inglese).
+
+Ma su quella macchina gira Linux!
+
+Si può fare da Linux?
+=====================
+
+Purtroppo sembra proprio di no: ``drivers/macintosh/via-pmu.c``, il
+driver della Power Management Unit, implementa solo un paio di
+funzioni.
+
+Come sono riuscito?
+===================
+
+Ho truccato. Ho avviato con il disco di installazione di `Mac OS X`
+10.4, ho aperto un terminale, e ho eseguito ``pmset``. Che non ha
+funzionato, dandomi un errore 0xe00002bc. Scavando un po' in rete si
+scopre che l'errore è grosso modo "non riesco a scrivere un
+file". *Scrivere un file*? E chi gliel'ha chiesto?
+
+Leggendo meglio la documentazione_ di ``pmset``, si scopre che scrive
+un paio di file in
+``/Library/Preferences/SystemConfiguration/``. Ovviamente, avendo
+avviato da CD, quella directory è in sola lettura.
+
+Non riesco a trovare un modo di creare un ```tmpfs`` o simili, per cui
+prendo una chiavetta USB e provo a montarla. Non funziona: non ci sono
+i driver per la `FAT`, o qualcosa del genere. Ok, formatto la
+chiavetta `HFS`, e finalmente la monto::
+
+  mount -o union -t hfs /dev/disk5s1 /Library/Preferences/SystemConfiguration
+
+rilancio ``pmset`` e finalmente la configurazione entra.
+
+.. _rsnapshot: http://www.rsnapshot.org/
+
+.. _pbbuttonsd: http://pbbuttons.berlios.de/
+
+.. _documentazione:
+   http://developer.apple.com/documentation/Darwin/Reference/ManPages/man1/pmset.1.html
+
diff --git a/src/SW/pmset-linux-workaround/du2html.xsl b/src/SW/pmset-linux-workaround/du2html.xsl
new file mode 120000
index 0000000..e2487e0
--- /dev/null
+++ b/src/SW/pmset-linux-workaround/du2html.xsl
@@ -0,0 +1 @@
+../../../templates/du2html.xsl
\ No newline at end of file