Open Source im professionellen Einsatz
Linux-Magazin 10/2016
© psdesign1, Fotolia

© psdesign1, Fotolia

Kernel- und Treiberprogrammierung mit dem Linux-Kernel – Folge 88

Kern-Technik

,

Mit Kernel 4.8 stellt Linus Torvalds die Kerneldokumentation auf die leichtgewichtige Markup-Sprache Restructuredtext um. Das Ganze ist kein fauler Kompromiss, sondern soll bei gleichem oder gar geringerem Dokumentationsaufwand im Quelltext bessere Ergebnisse liefern.

733

Wer Gedanken aller Art zu Papier bringen will, darf dies natürlich mit Libre Office oder einer Notiz-Software tun. Die Deklaration einer Datenstruktur aus einer Headerdatei auf die gleiche Weise dynamisch zu einer Entwickler-Dokumentation zu verfassen, wäre naheliegend ein holpriger Weg. Ungleich schneller führen wenige Zeilen Skriptcode zum Ziel, die klassische Ascii-Textdateien analysieren, Texte extrahieren und in möglichst geeigneter Weise interpretieren.

Um die Vorteile der Textverarbeitung mit den Vorteilen der Textdateien zu verbinden, sind die Markup-Sprachen (ML) wie HTML oder Docbook aufgekommen. Um explizit eine Dokumentation zu verfassen, schreibt der Entwickler zumeist mit einem Ascii-Editor in ein neues Ausgangsdokument, das er dann mit Hilfe eines Formatierprogramms in ein ansehnliches Ausgabeformat wie HTML oder PDF bringt (Abbildung 1) – und dieser Vorgang lässt sich leicht mit einem Skript automatisieren.

Abbildung 1: Das Prinzip ist einfach: Textbasierte Ausgangsdokumente lassen sich über Formatiersoftware in beliebige Ausgabeformate übersetzen.

So ist zu erklären, dass im Linux-Quellcode ein Informationsschatz von rund 5500 Dateien entweder als Plaintext-Dateien oder im Docbook-Format schlummert. Hinzu kommt ein Satz von Skripten – allen voran das Skript »kernel-doc« –, die in der Theorie aus einem Teil dieser Dateien in Kombination mit den C- und H-Dateien des Kernel-Quellcods eine HTML- oder PDF-Doku erzeugen.

In der Praxis funktioniert das allerdings nicht wie erhofft. Wer im Linux-Quellcode-Verzeichnis die Kommandos »make htmldocs« oder »make pdfdocs« tippt, produziert statt informativer Dokumente Fehlermeldungen. Denn zum Erzeugen der Dokumente bedarf es eines größeren Sets von Werkzeugen, die installiert sein wollen und die selten sofort zueinander passen. Hinzu kommt, dass sowohl die Einarbeitung in das Docbook-Format als auch das Interpretieren von Syntaxfehler-Meldungen als aufwändig gelten.

Up and down

Die Misere ist den Entwicklern natürlich nicht verborgen geblieben, weshalb für den Linux-Kernel seit Anfang des Jahres der Vorschlag konkret im Raum steht, leichtgewichtiges Markup, Markdown genannt, als Dokumentationsformat einzuführen [1]. Markdown-Sprachen sollen das Anfertigen einer Dokumentation signifikant erleichtern.

Dazu ist innerhalb des Ascii-Textes keine extra Auszeichnung mit Tags wie »<Section>« notwendig. Vielmehr erkennt die Analysesoftware an einem vorangestelltem »#« eine Überschrift und formatiert diese bei der Umsetzung in HTML oder PDF ansehnlich. Wer in der Vergangenheit also seine Doku mit normalem Ascii geschrieben hat, kann mit geringem Aufwand ein professionelles HTML, PDF, Epub oder auch eine Präsentation generieren.

In guter Open-Source-Manier hatten Entwickler für den Linux-Kernel nicht nur die Variante Asciidoc vorgeschlagen, sondern gleich erste Versionen geeigneter Formatiersoftware geliefert. Andere Entwickler brachten wiederum eine Umstellung auf ein in der Python-Welt produktiv eingesetztes Format namens Restructuredtext und das zugehörige Formatierungswerkzeug Sphinx ins Spiel.

Kind der Schlange

Auch Restructuredtext [2] ist eine leichtgewichtige, vereinfachte Auszeichnungssprache. Ihr gelingt durch Vermeiden langer Tags ein so genanntes Pretty-Printing unter Beibehaltung der Lesbarkeit des Ausgangsdokuments. Listing 1 zeigt beispielhaft ein solches Ausgangsdokument, Abbildung 2 die Umsetzung mit Hilfe von »rst2pdf« in ein PDF.

Listing 1

linuxmag.rst – Restructuredtext im Beispiel

01 ================
02  Linux Magazin
03 ================
04 ----------------
05  Kern-Technik 88
06 ----------------
07
08 .. |date| date::
09
10 Absätze werden durch Leerzeilen voneinander
11 getrennt. Einzelne Worte lassen sich leicht
12 **fett** oder *kursiv* auszeichnen.
13
14 Kapitel 1 Historie
15 ==================
16
17 Kapitel 1.1 Früher war alles ...
18 -----------------------------------
19
20 Aufzählungen werden durch "``-``" eingeleitet,
21 automatisch mummerierte Aufzählungen durch "``#.``".
22
23 - Gestern
24 - Datum heute: |date|
25
26 Jetzt die nummierte Liste:
27
28 #. Reine Ascii-Dokumentation
29 #. Markup
30 #. Markdown
31
32 Direktiven werden durch "``..``" eingeleitet.
33 Der zugehörige Text wird eingerückt.
34
35 .. code:: C
36
37   int main()
38   {
39         printf("Hello World\n");
40         return 0;
41   }
42
43 Durch die Direktive ``image::`` werden Bilder eingebunden.
44 Weitere Direktiven sind unter
45 http://docutils.sourceforge.net/docs/ref/rst/directives.html
46 beschrieben.
47
48 .. image:: picture.jpg
49    :scale: 15 %
50    :align: center
Abbildung 2: Pretty-Printing mit dem im Kernel eingesetzten Tool rst2pdf.

Restructuredtext erkennt einen Dokumenttitel daran, dass dieser mit Gleichheitszeichen über- und unterstrichen ist. Kapitelüberschriften sind demgegenüber nur unterstrichen, für die erste Indirektion mit Gleichheitszeichen, für die zweite mit Bindestrichen. Die Elemente einzelner Listen leiten Bindestriche (Minuszeichen) ein. Nummerierte Aufzählungen entstehen per ».#« . Innerhalb eines Textes lässt sich Kursivdruck durch vor- und nachgestellte »*« erreichen, bei Fettdruck verwendet der Programmierer zwei Sterne (»**« ).

Neben diesen statischen Auszeichnungen kennt Restructuredtext so genannte Direktiven, um Texte dynamisch und automatisiert umzusetzen beziehungsweise für komplexere Auszeichnungen. Direktiven werden grundsätzlich durch zwei Punkte (»..« ) eingeleitet. Danach kommt der Direktiventyp, den Doppelpunkte (»: :« ) einrahmen. Einige Direktiven lassen sich per Option parametrieren (Unterdirektive). Optionen sind mit Doppelpunkten umschlossen, sie folgen – eingerückt – direkt nach der Direktivenzeile.

Diesen Artikel als PDF kaufen

Express-Kauf als PDF

Umfang: 6 Heftseiten

Preis € 0,99
(inkl. 19% MwSt.)

Linux-Magazin kaufen

Einzelne Ausgabe
 
Abonnements
 
TABLET & SMARTPHONE APPS
Bald erhältlich
Get it on Google Play

Deutschland

Ähnliche Artikel

  • SQL-Suchmaschinen

    Volltextsuchmaschinen wie Solr, Xapian und Sphinx machen nicht nur das tägliche Datenchaos auf einer Festplatte durchsuchbar, sondern kommen auch mit relationalen Datenbanken klar.

  • Kern-Technik

    Fertige Bibliotheken nehmen Programmierern Arbeit ab. Auch der Kernel bietet Hilfsfunktionen, obwohl er keinen Zugriff auf Libraries wie die Glibc hat. Von der Stringumwandlung bis zur Listenverwaltung findet sich allerlei Nützliches, das dieser Artikel erklärt und übersichtlich auflistet.

  • Kern-Technik

    Ein ausgeklügeltes Framework verwaltet das Abarbeiten asynchroner Codesequenzen im Linux-Kernel: Kworker-Threads. Was sie sind, wie sie arbeiten und wer die Arbeitstiere für seine Zwecke einspannen darf, erklärt die neueste Folge der Kern-Technik.

  • Kern-Technik

    Der Linux-Kernel bietet seine Verschlüsselungsfunktionen auch zum asynchronen Zugriff an. Ineinander geschachtelte Datenstrukturen und undokumentierte Funktionen machen dem Programmierer allerdings das Leben schwer. Diese Kern-Technik schafft Abhilfe.

  • Kern-Technik

    Dass es TCP/IP-Netzwerkfunktionen im Kernel gibt, überrascht kaum, denn schließlich implementiert der Betriebssystemkern den zugehörigen Stack. Das Nutzen der Funktionen in eigenen Kernelmodulen funktioniert aber etwas anders als bei den Userspace-Verwandten.

comments powered by Disqus

Ausgabe 09/2017

Artikelserien und interessante Workshops aus dem Magazin können Sie hier als Bundle erwerben.