<< Neuere Einträge

Dokumentieren von Source Code mit Muse

2010-04-12

Emacs Muse eignet sich hervorragend zur Erstellung von technischer Dokumentation und auch zum Dokumentieren von Source Code, da es eine einfache Wiki-Syntax bietet und in viele unterschiedliche Formate publizieren kann (HTML, PDF, LaTeX, Info, DocBook und weitere).

Der folgende Demo-Artikel über Fibonacci-Folgen enthält ein kurzes JAVA-Programm und wurde von mir als Beispiel einmal in HTML und PDF) publiziert.

Unten steht der ursprünglichen Wiki-Text, aus welchem die jeweilige HTML und PDF Dokumentation generiert wurde. Später zeige ich dann, wie dieser Wiki-Text noch drastisch verkürzt werden kann, indem man beim Publizieren direkt den originalen Source Code verwendet, anstatt diesen zu kopieren.

Doch hier ist erst einmal der ungekürzte (und daher suboptimale) Wiki-Text:

#title Die Fibonacci-Folge 

Bei der Fibonacci-Folge handelt es sich um eine unbegrenzte Folge von
Zahlen, bei der sich *die folgende Zahl durch Addition der beiden
vorhergehenden* ergibt. **Beispiel: 1, 1, 2, 3, 5, 8, 13, 21, 34, 55,...**

Da sich die Fibonacci-Folge selbst durch ein rekursives Bildungsgesetz
definiert, kann diese idealerweise anhand 
[[http://de.wikipedia.org/wiki/Rekursive_Programmierung][rekursiver Programmierung]]
umgesetzt werden.

** Source Code

<src lang="jde">

// File: Fibonacci.java

public class Fibonacci {

    static int fibonacci(int n) {
        if ( (n==1) || (n==2) ) {
            return 1;
        } else {
            return fibonacci(n-1)+fibonacci(n-2);
        }
    }

    public static void main (String [] args) {
        int max = (args.length>0 ? Integer.parseInt(args[0]) : 10);
        for (int i = 1; i<=max; i++) {
            System.out.println(fibonacci(i));
        }
    }
}
</src>

** Übersetzung, Aufruf & Ausgabe

<example>
$ javac Fibonacci.java 
$ java Fibonacci 
1
1
2
3
5
8
13
21
34
55
</example>

Und nun die optimierte Variante

Es ist ja sinnvoll die Dokumentation direkt neben dem Source-Code in einer Versionkontrolle nachzuhalten. Denn zum einen kann so konkurrierend an der Dokumentation gearbeitet werden und zum anderen können Änderungen zwischen Versionen einfacher nachvollzogen werden, bzw. stehen Code und Dokumentation immer als eine Einheit zur Verfügung, anstatt auf unterschiedlichen Medien verteilt zu sein.

Wir machen uns diese Tatsache, dass Source-Code und Dokumentation in einem gemeinsamen Projekt-Verzeichnis abgelegt sind, zu Nutze. Via dem Element wird mit dem Shell-Kommando “cat” der tatsächliche Source-Code der Datei Fibonacci.java dynamisch in den Wiki-Text eingefügt:

...
** Source Code

<command markup="src" lang="jde">
cat Fibonacci.java
</command>
... 

Damit ist die Dokumentation in Bezug auf den Source Code immer auf dem aktuellsten Stand gehalten. So besteht keine Gefahr mehr, dass Beispiel-Code und tatsächlich ausführbarer Code auseinander driften, wenn z.B. Fehler korrigiert werden oder Schnittellen einer API verändert werden.

In dem darauf folgenden Schritt “Übersetzung, Ausführung und Ausgabe” werden nun sogar die Schritte zur Übersetzung, Ausführung und auch der Programm-Ausgabe mit den tatsächlich ausgeführten Kommandos selbst dokumentiert:

** Übersetzung, Aufruf & Ausgabe

<command markup="example">
set -x
javac Fibonacci.java 
java Fibonacci 
</command>

Zuerst wird das Shell-Kommando “set -x” ausgeführt. Dies führt zu einem Echo der jeweils nachfolgend ausgeführten Shell-Kommandos in der Standardausgabe. D.h. alle folgenden Shell-Kommandos werden mit ihrem eigenen Aufruf und ihrer Ausgabe selbst in den Wiki-Text mit einfließen.

Der folgende, komplette Wiki-Text generiert daher die gleiche Dokumentation, ist jedoch erheblich kürzer und ist durch die Nutzung des echten Source Codes immer auf dem aktuellsten Stand:

#title Die Fibonacci-Folge 

Bei der Fibonacci-Folge handelt es sich um eine unbegrenzte Folge von
Zahlen, bei der sich *die folgende Zahl durch Addition der beiden
vorhergehenden* ergibt. **Beispiel: 1, 1, 2, 3, 5, 8, 13, 21, 34, 55,...**

Da sich die Fibonacci-Folge selbst durch ein rekursives Bildungsgesetz
definiert, kann diese idealerweise anhand 
[[http://de.wikipedia.org/wiki/Rekursive_Programmierung][rekursiver Programmierung]]
umgesetzt werden.

** Source Code

<command markup="src" lang="jde">
cat Fibonacci.java
</command>

** Übersetzung, Aufruf & Ausgabe

<command markup="example">
set -x
javac Fibonacci.java 
java Fibonacci 
</command>

Tastaturbelegung MAC/VMware/Ubuntu

2010-04-03

Das MacBook Pro besitzt ja unter anderem eine recht schicke Hardware, doch was die Tastatur angeht, habe ich es immer als störend empfunden, dass Apple diese recht eigenwillig belegt hat. Insbesondere wenn ich Ubuntu unter VMware Fusion nutze. Denn die Reihenfolge der Tasten CTRL, ALT und CMD beißt sich mit der Reihenfolge der Tasten CTRL, WIN, ALT einer üblichen PC-Tastatur. Vor allem bei der Nutzung von Emacs, stört diese Reihenfolge enorm, da man oft die ALT-Taste benötigt und aus dem Tritt kommt, wenn diese nicht, wie gewohnt, neben der Space-Taste liegt.

Mit der folgenden Konfiguration werden unter anderem diese Apple-Tasten unter VMware Fusion so um belegt, dass sie der Anordnung nach einer PC-Tastatur entsprechen: Apple-ALT wird zu PC-WIN und Apple-CMD wird zu PC-ALT um belegt. Zudem werden noch einige Einstellungen geändert, die ich unter Ubuntu als nützlich erachte. Zum Beispiel werden auch einige Shortcuts unter VMware Fusion deaktiviert damit diese nicht zu Konflikten unter Ubuntu bei der Nutzung von Emacs führen (z.B. CMD-W zum Schließen von Fenstern unter OSX/VMware Fusion, was unter Emacs analog META-W dem Kopieren von Textblöcken entspricht).

VMware Fusion Einstellungen

Key Mappings

Keyboard plus Mouse

Max OS Shortcuts

Fusion Shortcuts

Ubuntu Einstellungen

Die folgenden Einstellungen wurden für Ubuntu 9.10 – Karmic Koala – vorgenommen. Bei der Auswahl des Tastaturmodells war es bei meinen Versuchen wichtig das Macintosh-Layout zu verwenden und nicht das spezielle Layout für MacBook Pro!

Ubuntu Tastatureinstellungen

Im Folgenden wird die Meta-Funktion für die ALT-Taste festgelegt und das anschließende Vertauschen von CMD und ALT auf dem Apple-Keyboard.

Weitere Ubuntu Tastatureinstellungen


Abgleich OSX und X11 Zwischenablage

2010-03-31

Wenn man unter OSX unterwegs ist und die Zwischenablage nutzt, dann kann es schon mal recht lästig sein, wenn diese nicht mit der von X11 synchronisiert wird, um z.B. zwischen nativen Applikationen und X11 Texte auszutauschen.

Abhilfe schaffen die folgenden Kommandos auf der Konsole, um das Pasteboard und Clipboard zu verbinden:

defaults write org.x.X11 sync_pasteboard_to_clipboard -boolean true
defaults write org.x.X11 sync_pasteboard_to_primary -boolean true
defaults write org.x.X11 sync_clipboard_to_pasteboard -boolean true

Somit sind dann das Pasteboard und das Clipboard ‚kurzgeschlossen‘, so dass man nur noch eine gefühlte Zwischenablage nutzt. Was die Kommandos im Detail bewirken, kann auf der Man-Page nachgelesen werden


Variablen mit XOR tauschen

2010-03-30

Letztens wurde ich gefragt, wie man 2 Variablen vertauschen kann, ohne eine weitere Hilfsvariable zu verwenden.

Nach einer Weile bin ich darauf gestoßen. Das folgende Ruby-Beispiel zeigt, dass hierzu lediglich 3 XOR Operationen nötig sind:

y=887; x=345
x=x^y
y=x^y
x=x^y
puts x // => 887
puts y // => 345

Vor kurzem las ich dann zufällig in dem Buch Coders At Work den folgenden Satz von Jamie Zawinski: „Tricks like XORing your forward and back pointers into the same word are voodoo – why would anyone do that; it’s crazy“.

Ich kann ihm da nur Recht geben. Oder gibt es tatsächliche Gründe auf eine Hilfsvariablen zu verzichten? Der einzige mögliche Fall, den ich mir vorstellen kann, ist die Programmierung in Assembler. Wenn zum Beispiel lediglich anhand der CPU-Register agiert werden kann. Oder gibt es noch weitere Gründe?


Erste Schritte mit Derby

2010-03-15

Installieren von Java6 und der Derby DB unter Ubuntu:

sudo aptitude install sun-java6-javadb

Umgebungsvariablen setzen, bzw. am besten direkt in .bashrc hinterlegen:

export JAVA_HOME=/usr/lib/jvm/java-6-sun/
export DERBY_HOME=$JAVA_HOME/db
export PATH=$PATH:$DERBY_HOME/bin/

Server starten:

startNetworkServer

Mit DB-Server verbinden und gleichzeitig eine neue DB anlegen:

ij
ij>connect 'jdbc:derby://localhost:1527/my_new_db;create=true';

Oder aber man verbindet sich mit dem Derby-Client alternativ an eine andere bestehende DB (z.B. Mysql). Dazu ist natürlich der DB-spezifische Connector zuvor im CLASSPATH zu berücksichtigen:

ij>connect 'jdbc:mysql://localhost:3306/your_mysql_db?user=username&password=secret';

Anlage einer Tabelle:

ij>create table foo(anId int primary key, bar varchar(100));

Schemainfo via SQL:

ij>describe foo;
-- COLUMN_NAME         |TYPE_NAME|DEC&|NUM&|COLUM&|COLUMN_DEF|CHAR_OCTE|IS_NULL
-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-- ANID                |INTEGER  |0   |10  |10    |NULL      |NULL      |NO
-- BAR                 |VARCHAR  |NULL|NULL|100   |NULL      |200       |YES

Daten einfügen:

ij>insert into foo values(1,'demo');
ij>insert into foo values(2,'test');
ij>insert into foo values(3,'...');

Selektieren der Tabelle:

ij> select * from foo;
-- ANID       |BAR
-- ++++++++++++++++
-- 1          |demo
-- 2          |test
-- 3          |...

Schemainfo via Kommandozeile:

dblook -d 'jdbc:derby://localhost:1527/my_new_db'

# Zeitmarke: 2010-03-15 17:50:11.757
# Quellendatenbank: my_new_db
# Verbindungs-URL: jdbc:derby://localhost:1527/my_new_db
# appendLogs: false
# 
# +++++++++++++++++++++++++++++++++++++++++++++
# DDL-Anweisungen für Tabellen
# +++++++++++++++++++++++++++++++++++++++++++++
# 
# CREATE TABLE "APP"."FOO" ("ANID" INTEGER NOT NULL, "BAR" VARCHAR(100));
# 
# +++++++++++++++++++++++++++++++++++++++++++++
# DDL-Anweisungen für Schlüssel
# +++++++++++++++++++++++++++++++++++++++++++++

>> Ältere Einträge