Ich plane derzeit recht viel Dokumentation zu schreiben und habe mir deswegen Outliner genauer angesehen. Hier möchte ich kurz beschreiben, was Outliner sind, wie ich sie nutzen möchte und wie man die Dokumente am Ende über Markdown zu HTML macht.

Meine Erfahrung an der Universität hat gezeigt, dass logisch aufgebaute Dokumente mit einem klaren Plan der Gliederung nicht immer ganz einfach sind. Viele Hausarbeiten werden wild formatiert und weisen eine flache Hierarchie der Gedanken auf, auch wenn der Inhalt sinnvoller in kleinen Baumstrukturen aufgebaut wäre. Dabei hilft ein Outliner sehr, daher soll die Installation und Benutzung für Vim erklärt werden.

Nicht erklärt wird hier die grundsätzliche Benutzung von Vim. Wer sich dafür interessiert, ist gut beraten, die Bedienung zu lernen. Für Programmierer, Systemadministratoren und Linux-Enthusiasten lohnt es sich ohne Zweifel.

Outliner

Outliner Editoren, bei denen ein starker Augenmerk auf die Gliederung des Dokuments steht. Damit lassen sich Dokumente erstellen, die sowohl zahlreiche Überschriften, die in hierarchischer Beziehung zueinander stehen, als auch die dazugehörigen Textblöcke, beinhalten. Damit lassen sich vor allem zusammenhängende Themen unter einer Überschrift gruppieren, das Verhältnis zu anderen Themen wird so auch leicht visuell ersichtlich:

Einzelne Abschnitte können auch eingeklappt werden, um nur die Struktur des Dokumente im Auge zu behalten. Dabei können auch einzelne Blöcke in der Hierarchie eine Ebene höher (visuell damit nach links) oder niedriger (visuell rechts) verschoben oder mit anderen Blöcken ausgetauscht werden. Das Erstellen längerer Dokumentationen oder generell das Sortieren der Gedanken hinter größeren Dokumenten wird damit stark erleichtert, außerdem ein logischer Aufbau der Arbeiten gefördert.

Vim

Als Musterbeispiel für solche Editoren, vor allem mit noch viel mehr Funktionen und Einsatzzwecken, gilt wohl der Emacs Org-Mode. Ich brauche allerdings bei weitem nicht alle Funktionen dieses Programms und setze darüber hinaus auch den Editor Vim ein. Traditionell haben diese Beiden Editoren gespaltene Lager; beide haben eine hohe Lernkurve und so bleibe ich bei meinem Vim.

Die meiste Funktionalität zum Erstellen von Outlines bringt Vim bereits mit. Man kann auch ohne Erweiterungen ein Dokument anlegen und Überschriften mittels Einrückung voneinander abgrenzen, etwa wenn man einen Tabulator einfügt. Dann kommt das folding in’s Spiel, was dann Textabschnitte auf Tastendruck oder automatisch einfalten kann. Dazu muss im Vim eine kleine Einstellung vorgenommen werden:

:set foldmethod=indent

Mit Tastendruck zc (close fold, das Z muss man sich wie ein gefaltetes Papier vorstellen) und zo (open fold) können dann Abschnitte eingefaltet beziehungsweise aufgefaltet werden. Die Einrückung einer Zeile (oder mehrerer) geschieht über > und < Das Vim Tips Wiki hat eine gute Einführung zum Folding.

Vim-Outliner

Schöner geht das Ganze noch mit dem Vim Outliner. Diese kleinere Erweiterung für Vim bietet vor allem optisch ansprechendere Repräsentation des Dokuments. Im Screenshot weiter oben ist das schön ersichtlich. Verschiedene Ebenen des Dokuments werden unterschiedlich eingefärbt.

Installation

Die Installation unter Ubuntu und Debian ist nicht ganz intuitiv: Man muss sowohl das Paket vim-vimoutliner als auch vim-addon-manager installieren und dann erst das Addon aktivieren:

sudo apt-get install vim-vimoutliner vim-addon-manager
vim-addons install vimoutliner

Bedienung

Das Einfärben der Ebenen geht automatisch, sobald eine Datei mit der Dateiendung .otl geöffnet wird. 

Darüber hinaus gibt es noch einige Tastaturkürzel, die sich als praktisch erweisen:

  • ,,1 bis ,,9 : Klappt verschiedene Ebenen der Gliederung ein
  • ,,0 : Klappt wieder alles auf
  • Strg+T und Strg+D : rückt die aktuelle Zeile auch im Insert-Mode eins weiter ein

Eine Liste der Tastenkombinationen findet sich in der Hilfe zum Vim-Outliner.

Zur Bedienung des Outliners muss man nicht viel wissen: Neue Zeilen sind immer neue Überschriften gleicher Ordnung. Eine eingerückte Zeile ist der darüber liegenden Zeile dann untergeordnet. Fließtext beginnt stets mit einem Doppelpunkt.

VOoM 

Noch eine Erweiterung, die sich für das Vorhaben lohnt, ist der Vim Outliner of Markers (VOoM). Diese kann eine zweite Spalte im Editor anzeigen, mit der man die einzelnen Gliederungspunkte und Kapitel dann direkt ansteuern kann. Das würde wohl auch mit ctags gehen, dann müsste man aber für jedes Dokument wohl ständig Tags erstellen.

Installation

VOoM gibt’s im vim-Scriptarchiv. Die Zip-Datei kann einfach nach ~/.vim entpackt werden.

Bedienung

Damit die Dokumente, die man mit dem Vim-Outliner erstellt, auch richtig interpretiert werden, kann man beim Editieren die Seitenleiste mit der Navigation wie folgt aufrufen:

:Voom vimoutliner

Die Navigation bedient sich auch sehr einfach:

  • Eingabetaste: springt, in der Navigation aufgerufen, zum entsprechenden Eintrag im Text. Dort aufgerufen springt es zur Navigation an der richtigen Stelle
  • Leertaste: klappt in der Navigation den aktuellen Gliederungspunkt ein beziehungsweise auf.

Wichtiges Feature ist darüber hinaus das einfachere Verschieben von Gliederungspunkten samt dazugehörigem Text. Während das ohne VOoM hauptsächlich mit Copy und Pase gemacht werden kann, kann man in der Navigation von VOoM auch direkt Gliederungspunkte hoch und runter schieben oder nach links und rechts, um es in der Hierarchie zu verschieben.

  • Strg+Oben, Strg+unten: verschiebt Gliederungspunkte nach oben und unten, ohne die Ebene in der Hierarchie zu ändern
  • Strg+Links, Strg+rechts: Ändert die Ebene in der Hierarchie, belässt es in der Reihenfolge am gleichen Ort

Mehr Funktionen und Dokumentation finden sich auf der Homepage von VOoM.

Feineinstellungen

Mir persönlich gefallen noch ein paar kleine Feineinstellungen an Vim ganz gut: Das automatische Öffnen von VOoM beim Öffnen einer Outline-Datei sowie die Reduzierung der Tab-Breitte auf 2 (ich programmiere sonst in Python, da hat man eher 4 oder 8). Die folgenden Änderungen habe ich also unten in meine ~/.vimrc hinzugefügt:

au FileType vo_base :Voom vimoutliner
au BufEnter *.otl setlocal tabstop=2
au BufEnter *.otl setlocal shiftwidth=2

Export in andere Programme

Damit sollte Vim als Outliner gut funktionieren. Die meiste Arbeit wird man auch dort verbringen. Möchte man jedoch das Dokument etwa in einer Office-Anwendung weiterverwenden oder auch nur mal im Browser betrachten, taugt das beim Vim-Outliner mitgelieferte Script leider nicht so viel, das Markup ist seltsam, man braucht ein extra Stylesheet und mit UTF-8 kann es nicht umgehen. Ich habe mir also selbst ein kleines Script geschrieben, mit dem ich von Outline auf Markdown konvertiere.

Markdown

Markdown ist eine Auszeichnungssprache, die etwa in Wikis verwendet wird. Damit lässt sich Text schreiben, der sowohl für Menschen leicht zu lesen und von Computern leicht zu verarbeiten ist. Diesen Text kann man dann etwa in’s HTML-Format umwandeln und von dort aus auch im Office-Programm öffnen.

Die wichtigsten Auszeichnungselemente von Markdown:

  • *kursiv*
  • **fett**
  • - Aufzählungslistenpunkt 1
    • Aufzählungslistenpunkt 2
  • Code blocks werden automatisch mit Monotype-Font geschrieben, wenn man vorn 4 Leerzeichen lässt
  • [Links](http://blog.heinle.cc)

Auf Überschriften und Zitate sollte man aufgrund von Konflikten mit der Syntax des Outliners verzichten. Ohnehin macht man Überschriften bereits mit dem Outliner.

Zur kompletten Markdown-Syntax

Konvertierung

Zur Konvertierung habe ich ein kleines Script geschrieben. Es macht im Grunde nicht viel anderes als die Ebenen der Einrückung in Markdown-Überschriften zu übersetzen. Markdown unterstützt aber nur Überschriften bis zur sechsten Ordnung (HTML…). Wenn man in seinem Dokument also tiefere Ebenen hat, erscheinen in der Ausgabe dann Zeilen, die zwar schon ganz in Ordnung formatiert sind, aber noch ein paar # vorne dran haben.

Die Bedienung ist sehr einfach gehalten:

$ ./otl2md.py dateiname.otl|markdown>dateiname.html

Dazu muss natürlich Markdown installiert und im Pfad vorhanden sein.

#!/usr/bin/env python
# -*- coding:utf-8 -*-
#
""" convert vim outliner files to markdown """

import sys

def count_indent(line):
    """count indentation level
    
    will be used later to create headings/sections"""
    count = 0
    for character in line:
        if character == "\t":
            count += 1
        else:
            return count

def main(argv):
    """convert indentation to heading levels

    body text (i.e. lines starting with ":") are ignored"""
    otl_file = open(argv[1], 'r').readlines()
    output_lines = []
    for line in otl_file:
        if line.strip().startswith(':'):
            output_lines.append(line.strip()[2:])
        else:
            heading = (count_indent(line) + 1) * '#'
            output_lines.append("%s %s" % (
                    heading,
                    line.strip()
                )
            )
    return "\n".join(output_lines)

if __name__ == '__main__':
    print(main(sys.argv))