Markdown-Dialekt festlegen

[Bengt]

Das Markup-Format der Gesetzestexte im Repository ist bisher nur als "Markdown" spezifiziert, obwohl es einige Markdown-Dialekte gibt. Neben John Gruber's originalem Standard Markdown (SM), und dem erwähnten Pandoc Markdown fällt mir noch Multimarkdown ein und die index.md-Dateien werden hier mit GitHub-Flavoured Markdown (GFM) interpretiert. Die englische Wikipedia hat eine Liste der Markdown-Implementationen.

GFM erweitert SM im Wesentlichen um für GitHub-spezifische Dinge wie automatisches Linken von Commits/Issues/Personen und fügt Code-Blöcke hinzu. Ich denke, dass die Unterschiede zwischen GFM und SM vernachlässigbar sind. Über den kleinen Unterschied beim Umgang mit Leeraum sollte man aber vielleicht noch mal nachdenken.

SM wie GFM kennen keine Syntax für Tabellen. Sollten solche benötigt werden, wäre es vielleicht besser, sich auf Pandoc-Markdown oder Multimarkdown festzulegen. Für die weitere Verarbeitung von SM/GFM Quellen mit Inline-HTML müssten diese sonst erst komplett zu HTML und anschließend zum eigentlichen Zielformat konvertiert werden. Mit Pandoc z.B. ist das kein Problem, aber vielleicht für andere Szenarien.

[Bengt]

Außerdem sind die tief verschachtelten Überschriften der Gesetzestexte ein Problem. Siehe dazu auch https://github.com/bundestag/gesetze/issues/21#issuecomment-7654402 in #21

[rriemann]

http://kramdown.rubyforge.org/tests.html – Dort werden die gängigen Markdown-Implementationen verglichen. Wir sollten wirklich probieren irgendeinen schon häufiger verwendeten Parser zu nehmen. MultiMarkdown höre ich zum ersten mal.

Nette Übersicht über Markdown-Bibliotheken: https://www.ruby-toolbox.com/search?q=markdown

[Bengt]

@saLOUt Ich denke, dass Gängigkeit kein gutes Kriterium zum Wählen einer Implementation für dieses Projekt ist. Abgesehen davon, dass sich die Gängigkeit nur schwer (z.B. über die Anzahl der Google-Ergebnisse, wie es die Wikipedia macht ) belegen lässt, möchte ich behaupten, nützt sie auch recht wenig. Ob man nun Pandoc-Markdown oder Kramdown wählt: Man muss sich trotzdem über cabal bzw. gem Pakete selber bauen, wenn man halbwegs aktuelle haben will.

Außerdem hat dieses Projekt weil es eben Gesetzestexte händelt besondere Anforderungen an die Markup-Sprache. Je länger ich darüber nachdenke, desto mehr habe ich den Eindruck, man müsste sich einen eigenen Konverter für diese Textart schreiben. Das Rendern der Markdown-Dateien zu HTML ginge dann übrigens zwar noch mit Jekyll, aber nicht mehr auf mit GitHub Pages, weil keine Plugins unterstützt werden.

Laut dem Hilfe-Artikel zu GitHub Pages sind nur Markdown und RDismarkdown erlaubt. Die Doku zu Jekyll beschreibt aber Kramdown, rdiscount und redcarpet. Ist die Hilfe vielleicht veraltet und es kann auch der Kramdown-Interpreter benutzt werden?

[rriemann]

Ich habe lange kramdown mit Github-Pages eingesetzt. Hat funktioniert.

Warum müssen wir denn tatsächlich github-jekyll als Generator verwenden? Hier ein Beispiel wie man jekyll mit plugins (z.B. octopress) doch noch automatisiert auf github pages zum Laufen bekommt: http://blog.dlecan.com/octopress-continous-integration/

[Bengt]

Ich denke auch, dass man durchaus etwas anderes als den Jekyll von GitHub Pages benutzen könnte. Analog zu dem von dir verlinkten Beispiel kann man ja beliebige Konverter auf einen CI-Server irgendwo so konfigurieren, dass sie auf den gh-pages-Branch lauschen.

Im Moment funktioniert aber die Rendern der Dateien auf GitHub unter Code noch. Das müsste dann vielleicht aufgegeben werden. Geht das wohl noch mit Kramdown?

[tobislaw]

Ein Großteil der Gesetzestexte ist ja einfach nur Text, die bisher identifizierten Problemfälle wären Tabellen, Fußnoten und wahrscheinlich Graphiken. (Wobei Graphiken häufig eher in Anlage sind)

Mal ein Beispiel von einem aktuellen Gesetzesentwurf:

• Jetzige Fassung: http://bundestag.github.com/gesetze/v/vig/
• Entwurf im PDF (ab S. 7): http://dipbt.bundestag.de/dip21/btd/17/073/1707374.pdf

Eigentlich geht ja der Entwurf sehr schön von oben nach unten durch, sowas könnte man doch auch ohne zusätzliche Strukturinfo im Markup über regex hinkriegen?

[Bengt]

Klar kann man aus html und markdown-dialekten auch PDFs machen. Pandoc z.B. kann das ohne Weiteres:

pandoc -o entwurf_nachbau.pdf http://bundestag.github.com/gesetze/v/vig/index.html

Es gibt kleinere Probleme mit eingerückten Sachen, aber das ließe sich vorher filtern, denke ich.

[tobislaw]

Ah hab mich schlecht ausgedrückt: Ich hatte jetzt die andere Richtung gemeint, also wenn man aus dem .pdf Entwurf automatisch eine Markdown-Version generieren würde, damit man per Pull-Request die aktuellen Änderungen nachverfolgen kann. Dazu habe ich mich gefragt, ob das nicht schon allein mit regex gehen müsste, weil du ja oben mal gemeint hast, Gesetzestexte hätten besondere Anforderungen ans Markup.

[Bengt]

Die andere Richtung ist deutlich schwieriger und ein paar dahingehackten regulären Ausdrücken spätestens dann nicht mehr handhabbar, wenn man wie wir auch die Struktur erhalten will. Pandoc kann beispielsweise schlicht keine PDFs lesen. Dafür gibt es aber andere Tools, z.B. den Allesfresser Apache Tika.

Wie die Gesetzestexte aus den Quellen extrahiert werden, ist aber so weit ich verstehe die Fragestellung, der sich das Gesetze-Tools-Repo widmet. Hier geht es nur darum eine eine Datenbasis anzulegen und zu warten, wozu man sich dann eben auch mal Gedanken um das Datenformat machen muss.

[Bengt]

Die auf GitHub für das Rendern von Dateien mit entsprechendem Inhalt benutzbaren Markup-Sprachen und zugehörige Markdown-Implementierungen werden auf GitHub verwaltet: https://github.com/github/markup#readme Das sind aber abgesehen von Markdown sind das aber alles Nicht-Markdown-Markup-Sprachen. Also schon außerhalb der gemachten Einschränkung auf Markdown.