VD Template Repository

In diesem Repository ist alles drin, um eine neue VD anzufangen. Es fehlen nur die Inhalte. Wenn sich an der Template etwas geändert hat, merged man sie mit der aktuell in Bearbeitung befindlichen VD wie folgt:

 fossil pull http://fossil.forth-ev.de/vd-template --once
 fossil leaves #das zeigt dann an, welche Leaves es gibt
 fossil merge <8-digits> #zum Mergen des gerade 'reingepullten Branches

Wenn man ein neues Heft aus der Template erzeugt, ist der Workflow wie folgt: Repository kopieren (auf dem Server), die Kopie auf den Rechner auschecken, und dort dann

 ausgabe <yyyy-nn>

ausführen. Das zieht die Dateien aus template ins passende Verzeichnis, und biegt die Referenzen gerade.

Editor Startup

Werkzeug

login auf fossil.forth-ev.de

Bernd oder Carsten befragen

fossil

Zweck: die Dateien vom forth-ev.de Server holen und geordnet wieder raufspielen. Bei mir derzeit version 1.22

mit Deinem Lieblingspaketmanager installieren, oder von http://www.fossil-scm.org besorgen

make

Zweck: der komplette Ablauf, um das Heft in .pdf-Format zu erstellen, ist vermittelst make automatisiert. Derzeit Version 3.81.

Mit Deinem Lieblingspaketmanager installieren.

texlive 2011, 2012

Die moderne LaTeX-Distribution heißt "texlive", und ist auf http://www.tug.org/texlive/ erhältlich.

Da kann man die herinstallieren, oder als .iso-Datei runterladen und dann per DVD (selbstgebrannt) installieren. Wir reden von derzeit etwa 2 GB Volumen.

Wer die texlive Pakete aus Debian oder Ubuntu installiert hat, bekommt die Version 2009 (Stand 2012-07-28). Diese funktioniert mit unserem modernisierten make-Prozess nicht (includegraphics ist zu alt). Mit den Versionen 2011 und 2012 funktioniert es erwiesenermaßen.

Es kann auch sein, daß man diverse Pakete nachinstallieren muß, die zunächst nicht mitkommen. z.B. texlive-lang-cyrillic, texlive-lang-greek

LyX

Bernd hat den Prozess, das Heft zu erzeugen, auf lyx umgestellt, also braucht es das noch.

Mit Deinem Lieblingspaketmanager installieren.

Editor und pdfViewer

Freie Auswahl. Alles, was funktioniert und was man bedienen kann, ist erlaubt.

Beispiel Vorgang

Als erste Übung erzeugen wir ein Heft mit einer klitzekleinen Änderung. Alle Befehle werden hier auf der Kommandozeile der bash Shell gezeigt. "bash> " ist der prompt der Shell, abschließende "return"s gebe ich NICHT an.

VD Arbeitsverzeichnis

Als erstes suchen wir uns ein schattiges Plätzchen:
    bash> mkdir -p VierteDimension/fossil
    bash> cd VierteDimension/fossil
In diesem Verzeichnis entsteht das Arbeitsverzeichnis (oder mehrere, für jede Ausgabe ein separates Verzeichnis).

Dann definieren wir ein paar Variablen. Die sind eigentlich komplett überflüssig, verdeutlichen aber, wo ggf. Dinge anders einzutragen sind.
    bash> LOGIN="martin"
    bash> ISSUE="2012-03"

Verwendet werden die Variablen so:
    bash> echo ${LOGIN}

clone: die bereitgestellte, leere VD holen

Vom Server besorgen wir das leere Heft oder den aktuellen Zustand:
    bash> fossil clone https://${LOGIN}@fossil.forth-ev.de/vd-${ISSUE}  vd-${ISSUE}
    password for $LOGIN: <hier muss das Zauberwort rein>
                    Bytes      Cards  Artifacts     Deltas
    Sent:              53          1          0          0
    ....
Jetzt gibt es hier eine neue Datei mit dem Namen "vd-${ISSUE}", also vd-2012-03, die enthält eine Kopie des Repositories, mit allen Dateien und deren Geschichte für diese Ausgabe der VD.

open: Arbeitsverzeichnis erstellen

Theoretisch kann man das repository im derzeitigen Verzeichnis auspacken. Aber dann kommt man mit verschiedenen Ausgaben durcheinander. Mir gefällt das so nicht. Also

    bash> mkdir dir_vd-${ISSUE}
    bash> cd dir_vd-${ISSUE}

Und dann packen wir die Dateien des Hefts hier aus:

    bash> fossil open ../vd-${ISSUE}

Jetzt haben wir viele Dateien

    bash> ls -l
    total 8236
    drwxr-x--- 3 ew ew    4096 2012-07-29 18:35 2012-03/
    -rw-r----- 1 ew ew  399392 2012-07-29 18:38 4d2012-03-gray.pdf
    -rw-r----- 1 ew ew    5161 2012-07-29 18:37 4d2012-03.aux
    -rw-r----- 1 ew ew   80442 2012-07-29 18:37 4d2012-03.log
    -rw-r----- 1 ew ew     223 2012-07-29 18:37 4d2012-03.out
    -rw-r----- 1 ew ew 3420586 2012-07-29 18:37 4d2012-03.pdf
    -rw-r----- 1 ew ew    1697 2012-07-29 18:37 4d2012-03.toc
    -rw-r----- 1 ew ew   99009 2012-07-29 18:37 4d2012-03.tpm
    -rw-r----- 1 ew ew 3432448 2012-07-29 18:35 _FOSSIL_
    ...

status: Gucken, was fossil weiß

BEVOR wir irgendwelche Änderungen machen, schauen wir erst mal nach, was fossil anzeigt, wenn es KEINE Änderungen gibt.
    bash> fossil status
    repository:   /home/ew/tmp-VD/VierteDimension/fossil/dir_vd-2012-03/../vd-2012-03
    local-root:   /home/ew/tmp-VD/VierteDimension/fossil/dir_vd-2012-03/
    checkout:     f8199f9e33268f78b737c6b5b415a2735c3e784e 2012-07-29 16:13:38 UTC
    parent:       9210905ef9b43a9aee2d326be339f08aa9b6f3a6 2012-07-29 14:48:02 UTC
    tags:         trunk
    comment:      im Artikel Lokale Variablendie Zusammenfassung eingefügt.
                  (user: martin)
Es wird uns angezeigt, woher diese Arbeitskopie kommt, wie der aktuelle Zustand heißt (das ist die cryptische Nummer hinter checkout:) und wer die letzte Änderung gemacht hat.

Daß wir keine lokalen Änderungen gemacht haben, sieht man daran, daß eben auch keine weiteren Zeilen ausgegeben werden.

make, pdflatex

Ein Aufruf von make erzeugt, wenn LaTeX und all seine Verwandten richtig installiert sind, eine längliche Ausgabe auf den Schirm:
    bash> make
    pdflatex 2012-03/4d2012-03.ltx
    This is pdfTeX, Version 3.1415926-2.3-1.40.12 (TeX Live 2011)
     restricted \write18 enabled.
    entering extended mode
    ...
    Page 21
    Page 22
    Page 23
    bash>
Wenn Du bis hierher gekommen bist, dann sollte die Datei "4d${ISSUE}.pdf" neu erzeugt worden sein. Und die kannst Du jetzt mit Deinem Lieblingsprogramm zum .pdf-Dateien anschauen öffnen.

${LOGIN} was here

Also machen wir jetzt eine Änderung. Mit Deinem Lieblingseditor öffne die Datei "${ISSUE}/editorial.tex" und füge hinter der Zeile
    \section*{Liebe Leser,}
irgendeinen neuen Text ein, mit 'ner Leerzeile davor und dahinter.

Jetzt kontrollieren wir als erstes, ob fossil von unserer Aktion weiß:
    bash> fossil status
    repository:   /home/ew/tmp-VD/VierteDimension/fossil/dir_vd-2012-03/../vd-2012-03
    local-root:   /home/ew/tmp-VD/VierteDimension/fossil/dir_vd-2012-03/
    checkout:     f8199f9e33268f78b737c6b5b415a2735c3e784e 2012-07-29 16:13:38 UTC
    parent:       9210905ef9b43a9aee2d326be339f08aa9b6f3a6 2012-07-29 14:48:02 UTC
    tags:         trunk
    comment:      im Artikel Lokale Variablendie Zusammenfassung eingefügt.
                  (user: martin)
    EDITED     2012-03/editorial.tex
    EDITED     4d2012-03.pdf
Ja, fossil hat aufgepasst: wir haben die Datei 4d2012-03.pdf vorhin neu erzeugt, und außerdem die Datei 2012-03/editorial.tex mutwillig geändert. Mit make erzeugen wir das Heft neu und kontrollieren, daß der neue Satz auf der Editorial-Seite auch auftaucht.

Und dann lassen wir uns von fossil noch sagen, was es sieht, was wir geändert haben:

    bash> fossil diff ${ISSUE}/editorial.tex 
    --- 2012-03/editorial.tex
    +++ 2012-03/editorial.tex
    @@ -4,10 +4,12 @@
     %\parpicr{\includegraphicsscale=0.8{ulli}}
     %\parpicr{\includegraphicsscale=0.4{ew}}
     %\parpicr{\includegraphicsscale=1{bernd}}
     %\parpicr{\includegraphicsscale=0.5{cas}}
     \section*{Liebe Leser,}
    +
    +Neuer Editor \verb+$LOGIN+ war auch schon hier \ldots
.
     Sator Arepo tenet opera rotas (Der Sämann Sator dreht mühsam (am Rad??))
.
     , consetetur sadipscing elitr, sed diam
     nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,

Ok, Bahnhof?

Zuerst steht da 'ne Information, welche Datei das betrifft. Die --- und +++ könnten sich ja auf zwei verschiedene Dateien beziehen (das ist hier nicht der Fall).

Dann kommen so Blocks von der Bauart

@@ -134,11 +134,11 @@

Heißt: die Änderung bezieht sich auf

@@ alte Datei ab Zeile 134, 11 Zeilen lang; neue Datei ab Zeile 134, 11 Zeilen lang @@

Und dann kommt die Änderung als Kontext-diff.

Alle Zeilen, die mit einem völlig unscheibaren Leerzeichen " " anfangen, sind in der alten und neuen Version gleich.

Alle Zeilen, die mit einem ebenfalls unscheinbaren Minus "-" anfangen, sind nur in der alten Version der Datei.

Alle Zeilen, die mit einem "+" anfangen, sind nur in der neuen Version.
    +
    +Neuer Editor \verb+$LOGIN+ war auch schon hier \ldots
Sagt mir jetzt piekfein, daß ich zwei Zeilen neu dazueditiert habe, eine mit Text, und eine leere Zeile.

Kontext heißt, daß vor und nach der Änderung noch ein paar Zeilen (oft 3, hier 5) hingemalt werden, daß Menschlein besser lesen kann.

Ich kann nur empfehlen: immer "status" befragen. Da darf nixx als editiert markiert sein, was man sich nicht erklären kann. Und die editierten DAteien immer mit "diff" angucken. Es braucht Übung, um den Buchstabensalat zu verstehen, und es gibt auch gui-zentrierte Diff-Werkzeuge. Aber der diff muß immer erklärbar sein.

die Klick-Verweise im .pdf Dokument

Wer noch nie mit LaTeX gearbeitet hat, den wird es evtl. wundern, daß die Klick-Verweise (wenn man auf einen Eintrag im Inhaltsverzeichnis oder auf der Titelseite klickt) möglicherweise nicht dahinführen, wo das sein soll. Dann make noch einmal aufrufen. Normalerweise ist das im zweiten Durchgang behoben.

commit: Änderungen dauerhaft in's Geschichtsbuch eintragen

Sind alle Änderungen zu unserer Zufriedenheit, und haben wir die .pdf--Datei brav zwei mal neu erzeugt, und haben wir uns davon überzeugt, daß die Klick links korrekt verzweigen, dann ist es Zeit, die Änderungen ins Repository und auf den Server zu übertragen.
    bash> fossil commit -m 'Erster Versuch: $LOGIN war hier!'
Der Text zwischen den '...' einfachen Hochkommas ist die Meldung, unter der die vorhandenen Änderungen dann in der timeline angezeit werden (commit message). Die lässt sich hinterher nicht mehr frisieren. Also erst noch mal nachdenken, lesen, dann abschicken.

Auf der Webseite gucken

Wenn man mit dem Webbrowser auf http://fossil.forth-ev.de/vd-2012-03 gucken geht, und auf "timeline" klickt, dann sollte die gerade angegebene Meldung zuoberst erscheinen.

keinen fossil close!

Einen "fossil close" brauchen wir nicht, wenn die verschiedenen Ausgaben der VD auch brav in verschiedenen Verzeichnissen wohnen. Schließt man das repository mit "fossil close", dann muß man es vor dem nächsten Bearbeiten auch erst wieder öffnen. Dabei werden vorhandene lokale Änderungen locker ausradiert!

Viel Erfolg!