moved stuff around

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

4 files changed, 129 insertions, 0 deletions

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