Dokumente aus Discourse Themen erzeugen

Einleitung

Hier soll es darum gehen, wie man aus bestimmten Discourse-Beiträgen dokumentartige Ausgaben erzeugen kann (hardcopy, fine print), die u.U. auch für eine Druckausgabe geeignet sind [1].

Ziel

Der Anspruch soll kein geringerer sein, als Discourse als Authoring-System für Abschnitte einer Systemdokumentation verwenden zu können. Dabei geht es weniger um eine kohärente Repräsentation eines Diskussionsverlaufs sondern vielmehr um Funktionalitäten, die einen Dokumentations-Autor sinnvoll unterstützen können. Als kanonisches Ausgabeformat bietet sich das PDF-Format an, weitere Formate sind aber ebenfalls denkbar, z.B. ODT oder EPUB.


  1. Bei https://community.hiveeyes.org/t/vorbereitung-eines-selektiven-blog-planet-hiveeyes-org-auf-artikelebene/1231, https://community.hiveeyes.org/t/wie-kann-ich-discourse-ausdrucken/2113 und https://community.hiveeyes.org/t/gestaltung-eines-faq-bereichs/1967 haben wir auch schon geschaut, wie manche Dinge spezifisch anders gerendert werden können. ↩︎

A post was merged into an existing topic: Dokumentechte Ausgabeformate über die Druckfunktion des Browsers erzeugen

:aquarius: Motivation: Create hardcopy-like documents from Discourse content easily

Basic research

Evaluation am Beispiel

Für das Bee Observer Projekt wollen wir gerne einige bereits vorbereitete Ressourcen in Papierform bringen. Als kanonisches Beispiel verwenden wir dafür die Beiträge bei Anleitung, Aufbau und Installation des Sensor-Kits (grüne Platine).

  1. So bekommt man aus der JSON Repräsentation [1] den fertig nach HTML gerenderten Inhalt (im Fachjargon “cooked”) eines Posts – ganz ohne CSS.

    http 'https://community.hiveeyes.org/t/anleitung-aufbau-und-installation-des-sensor-kits-grune-platine/2443.json?include_raw=true' | jq -r '.post_stream.posts[0].cooked' > 2443.cooked.html
    
  2. Das ist eine leicht händisch aufgemöbelte Variante mit CSS im Seiten-Look. Obacht, das sind keine echten DIN A Seiten o.ä., daher ist auch jenes nur bedingt fürs Drucken geeignet.

  3. Das ist Variante 2. dann als per “Firefox » Save Page As » Web Page, complete” gespeichert und anschließend in ein Zip-Archiv gepackt.


P.S.: Bei keinem dieser Varianten scheint das TOC durchzukommen.


  1. z.B. https://community.hiveeyes.org/t/anleitung-aufbau-und-installation-des-sensor-kits-grune-platine/2443.json ↩︎

Discourse Markdown in verschiedene Formate konvertieren

Einleitung

Mit dem Gedanken, über pandoc Konnektivität zwischen der Discourse-Domäne und der TeX-Domäne herzustellen, um sich damit geschickt ohne nennenswerte Aufwände aus der Affäre ziehen zu können, ging ich schon länger schwanger.

Hier habe ich ein paar erste kurze Versuche gewagt, das Original-Markup (Markdown) optimal weiterzuverarbeiten.

Beispiele

#!/bin/bash

# Acquire Markdown of single post.
# https://meta.discourse.org/t/discourse-api-documentation/22706/161
title="Anleitung, Aufbau und Installation des Sensor-Kits"
markup=$(http 'https://community.hiveeyes.org/t/anleitung-aufbau-und-installation-des-sensor-kits-grune-platine/2443.json?include_raw=true' | jq -r '.post_stream.posts[0].raw')
echo "$markup" > 2443.md

# Convert Markdown to other formats.
pandoc 2443.md --standalone --from=markdown --metadata title="$title" --output 2443.pdf
pandoc 2443.md --standalone --from=markdown --metadata title="$title" --output 2443.html
pandoc 2443.md --standalone --from=markdown --metadata title="$title" --output 2443.epub

Zwischenfazit

Das Markdown bräuchte noch zusätzliche Massage, z.B. Ergänzung der Links zu Bildern, bevor da etwas anständiges herauszuholen wäre. Das sieht man ganz schnell, wenn man das selbst einmal versucht.

Ausblick

Besser mal das Cooked HTML ausprobieren, das Discourse bereits aus sich heraus pro Post zur Verfügung stellt.

Discourse cooked HTML anyone?

Hier versuchen wir, mit pandoc die von Discourse bereitgestellten vorgekochten HTML-Fragmente als Basis für die Transformation in andere Formate zu verwenden. TLDR; Klappt ganz gut.

Vorbereitung

# HTML beschaffen
http 'https://community.hiveeyes.org/t/anleitung-aufbau-und-installation-des-sensor-kits-grune-platine/2443.json?include_raw=true' | jq -r '.post_stream.posts[0].cooked' > 2443.cooked.html

# Titel bestimmen
title="Anleitung, Aufbau und Installation des Sensor-Kits"

PDF erstellen

pandoc 2443.cooked.html --standalone --metadata title="$title" --table-of-contents --output "$title.pdf"

Anleitung, Aufbau und Installation des Sensor-Kits - pandoc.pdf (818.7 KB)

ODT erstellen

pandoc 2443.cooked.html --standalone --metadata title="$title" --table-of-contents --output "$title.odt"

Anleitung, Aufbau und Installation des Sensor-Kits.odt (702.1 KB)

EPUB erstellen

pandoc 2443.cooked.html --standalone --metadata title="$title" --output "$title.epub"

Anleitung, Aufbau und Installation des Sensor-Kits.epub (700.4 KB)

PDF aus EPUB erstellen

Mit https://calibre-ebook.com/.

Anleitung, Aufbau und Installation des Sensor-Kits.pdf (804.8 KB)

1 Like

Discourse cooked HTML in andere Dokumentformate konvertieren

Introducing the discodoc program…

About

The discodoc program offers effortless document generation from Discourse content. Its main workhorse is pandoc, the universal document converter.

Synopsis

# Generate PDF document from all posts of given topic.
discodoc https://community.hiveeyes.org/t/anleitung-aufbau-und-installation-des-sensor-kits-grune-platine/2443 --format=pdf

For advanced command line options, please invoke "discodoc --help" or visit the discodoc usage documentation.

Features

All output formats are provided by pandoc fame. These have been tested:
pdf, docx, odt, pptx, epub2, epub3, fb2, latex, texinfo, html, html5, json, plain, rtf, revealjs, s5.

Details

Die ersten Ergebnisse dieser Renderings sehen nicht schlecht aus – vor allem aus der Perspektive, dass dieser Vorgang vollständig automatisierbar Dokumente ausspucken kann.

Neben dem klassisch-kanonischen PDF-Ausgebeformat ist auch das HTML-Ausgabeformat praktisch, weil pandoc hier die undankbare Aufgabe per resource-inlining ein self-contained Bündel zu erzeugen, ganz hervorragend ausführt.

Auch die Presentation-/Slideshow-Renderings können sich sehen lassen, also z.B. LaTeX/Beamer oder HTML/S5 bzw. HTML/Reveal.js – aber auch .pptx.

Ausblick

Wenn man es auf dieser Basis noch edler haben will, exportiert man die Inhalte z.B. im .odt-Format oder wenn es unbedingt sein muss auch im .docx-Format und schnippelt noch ein wenig dran rum, z.B. im Bereich von Formatvorlagen (Header- und Footer mit Organisationslogo/-branding/-CI) oder bei der manuellen Nachjustage von Seitenumbrüchen. Voilà.

Um bei den Presentation-/Slideshow-Formaten out-of-the-box optimale Ergebnisse zu erzielen, kann man dieses potentielle Ziel entweder bereits ein wenig bei der Beitragsgestaltung berücksichtigen [1], oder eben über das .pptx-Format gehen und dann noch im Impress oder Powerpoint entsprechend manuell nacharbeiten.


cc: @clemens, @wtf, @weef


  1. Die Beiträge (Posts) sollten für angestrebte Slideshows nicht zu lang werden, da sie schließlich auf A4 quer passen müssen – dadurch wird der Inhalt recht schnell geclipped, da der (Auto-)Layout-Mechanismus slideshow-getreu großzügig arbeitet; schließlich wollen auch die Leute aus der letzten Reihe ohne Brille noch die Bullet-Points lesen… Manchmal ;]. ↩︎

1 Like

Habe den ODT-Export heute gleich testen dürfen, da vom BOB-Projekt die Anforderung nach einem bearbeitbaren und druckbaren Dokument kam. War zwar nicht hübsch, grob aber ok. An folgenden Aspekten habe ich händisch korrigierend nachgearbeitet:

  • Bilder hatten umlaufenden Text.
  • Die Dateinamen im Text sind unnütz, wenn sie wie hier z.B. einfach nur screenshot-x lauten.
  • Einige Bilder überlagerten sich im Dokument.

Aber weniger Arbeit als ganz von Hand aus PDF kopieren und in Word oder anderswo einfügen ist es allemal!

1 Like

Klar.

Wenn man es auf dieser Basis noch edler haben will […] und schnippelt noch ein wenig dran rum.

Danke vielmals für die Bestandsaufnahme. Genauso klar, dass man da für die populärsten Schnitzer ggf. noch nen automatischen Postprocessing-Task dranhängen könnte, der noch einmal drüberschmirgelt.

Dieses “grob” ist nichts anderes als die Aufrechterhaltung und passabel-korrekte Umsetzung der kompletten Dokumentstruktur, die für eine weitere Überarbeitung das Rückgrat eines jeden Dokuments darstellt.

Dank der Mächtigkeit und Flexibilität von pandoc bekommen wir diese Strukturinformation ganz passabel ohne selbst zu implementierende Konvertierungen von einer Dokumentformatdomäne in eine andere – hier konkret aus dem cooked HTML von Discourse à la <h1><h2><h3>... nach whatever pandoc can do for us.

Dafür wars gedacht. Schön! Das Werkzeug spart - gerade bei wiederholten Iterationen - wirklich eine ganze Menge Arbeit. Zumindest habe ich das gehofft – daher freue ich mich über viele Einsatzzyklen dieses Werkzeugs [1], um den Grauen Herren…


  1. Weitere Ideen und Wünsche dazu sind natürlich ebenso gerne gesehen, auch wenn sie vermutlich bis auf weiteres im Backlog landen werden. ↩︎

Backlog

  • Automatische Erzeugung eines Inhaltsverzeichnisses – Table of Content (TOC).
  • Automatische Erzeugung von self-contained Dokumenten (z.B. HTML).
  • Mehrere Topics in einem Rutsch verarbeiten, um Dokumenserien sowie kombinierte Dokumente zu erzeugen.
  • Gestaltung des Aussehens per CSS.
  • Gestaltung der Header- und Footer-Bereiche pro Ausgabeseite.
  • Das erzeugte Dokument um ein Deckblatt oder Anhänge ergänzen.
  • More at the discodoc backlog.

Beim Rendern von S5-Slides (--format=html --renderer=s5) glaubte ich feststellen zu können, dass der Transformationsvorgang Seitenumbrüche berücksichtigt, wenn sie hier im Markdown per horizontal ruler --- ausgezeichnet wurden.

Drüben bei [INDEX] Dokumentation für Bee Observer Nachbau haben wir vier für Bee Observer relevante Dokumente identifiziert und deren Inhalte entsprechend verarbeitet und PDF Dateien daraus produziert.