[epdf] - Markdown, LaTeX + Convertertools

[Beta-User]

Hallo zusammen,

ich trenne mal diesen Teil der Fragen rund um die "Einsteiger-Doku 2020" hierher ab.
(Kann man nur verstehen, wenn man den Quelltext kennt, bitte also hier nur Kommentare dazu von denen, die Zugriff haben oder eine besonders gute Glaskugel).

Meine aktuelle Verständnis:

* pandoc und Co.
"pandoc" transferiert (im Standard) alles zunächst in eine "Großfile" und entfernt dabei (fast) alle "html"-Formatierungen (oder ignoriert sie). Einzige Ausnahme, die mir bisher aufgefallen ist, war das "width"-Element, das es immerhin (via .css) in's pdf geschafft hat (aber beim epub ignoriert wird).
Man kann das umgehen, wenn man ein anderes Zwischenformat wählt (getestet bisher html via wkhtmltopdf); das generiert dann aber wieder Links, die entweder gar nicht funktionieren (direkt via pandoc) oder teilweise in die Irre gehen (von Schotty berichtet: Github Wikito Converter).
Im Moment _glaube ich_, mit pandoc am Ende besser bedient zu sein, allerdings gehe ich davon aus, dass dafür einige Tweaks am LaTeX-Ende erforderlich sind (die leider sehr schwer nachzuvollziehen sind, wenn man nicht eine volle LaTeX-Installation (oder wenigstens die passenden Pakete) hat...).

Außerdem scheinen bestimmte LaTeX-Anweisungen (/footnotesize) nicht den Weg in's epub gefunden zu haben (minor issue), was aber darauf hindeutet, dass man sowas für den epub-Pfad vermutlich über html-Ersetzungen in tex-File lösen muß? (Dafür klappen aber Emoji's (Beispiel: ":+1:") direkt im epub, die pdf-Konvertierung meckert über das fehlende Unicode-Zeichen (=> andere Schriftart verwenden?)...)

* Bilder:
- Da wir (auch) ins Wiki wollen, scheint es mir sinnvoll, alle Bilder direkt da reinzuladen und dann darauf zu referenzieren. Korrekt?
- Die Skaliererei machen pdf und epub sehr unterschiedlich. Ich würde das eigentlich ungern über die in dem jeweiligen Bild hinterlegte Größe (teilweise?) lösen. Ergo wäre die Frage, ob es Sinn macht, je eine eigene, zentrale Referenzierungsfile für pdf und epub zu pflegen (im ebub gehen html-Anweisungen, oder?).
- \wrapfigure hatte ich ausgetestet, aber dabei passen die Seitenumbrüche nicht wirklich gut. Ich vermute, dass es auch da einen Trick gibt, und das dann der beste Weg wäre, die Bilderpositionierung im pdf zu fixen? (Irritierenderweise vermute ich, dass ausgerechnet das .css die richtige Stelle ist, um die \wrapfigure-Anweisungen zentral reinzumischen, ohne alle Mitautoren mit allzuviel LeTeX-Gewusel zu irritieren; korrekt?)

* Fußzeile: Wäre nett...

* Deckblatt@pdf: notfalls händisch, aber auch dafür gibt es einen Weg, oder?

* Doppelte Frontpage@epub: Wie abschalten/wo kommt das her, wie bekommt man tatsächlich ein Bild/"echtes Deckblatt" (automatisiert?) auf die allererste Seite?

Grüße, Beta-User

[andies]

Ich habe zweimal Bücher von latex in epub konvertiert und es war jedes mal eine Qual. Es gibt da keine vernünftigen Tools. Dann aber zwei Texte gleichzeitig zu pflegen, macht wesentlich mehr Arbeit.

BoD hat so eine Art epub-pdf. Die ist nicht skalierbar. Aber vielleicht wäre das die Lösung?

[xenos1984]

Wenn es darum geht, einen gemeinsamen Quelltext in mehrere verschiedene Formate zu wandeln, ist Pandoc mein persönlicher Favorit. Allerdings habe ich damit bisher nur nach PDF (über LaTeX), HTML5 und Plain Text konvertiert, und Bilder nur in der HTML Konvertierung benutzt. Mit EPUB und Bildern in anderen Formaten habe ich dagegen keine Erfahrung, auch Emojis habe ich bisher nicht benutzt.

Generell kann man in Pandoc eine ganze Reihe von Erweiterungen an- und abschalten. Dazu gehören LaTeX im Markdown, was dann aber nur im LaTeX / PDF Format berücksichtigt wird, und HTML im Markdown, das dann aber nur z.B. in EPUB und HTML berücksichtigt wird, nicht im PDF. Wenn man beides will, bleibt nur reines Markdown als "kleinster gemeinsamer Nenner", oder man muss beides einbauen, was aber gerade einem gemeinsamen Quellenformat widerspricht.

[Schotty]

Generell kann man in Pandoc eine ganze Reihe von Erweiterungen an- und abschalten. Dazu gehören LaTeX im Markdown, was dann aber nur im LaTeX / PDF Format berücksichtigt wird, und HTML im Markdown, das dann aber nur z.B. in EPUB und HTML berücksichtigt wird, nicht im PDF. Wenn man beides will, bleibt nur reines Markdown als "kleinster gemeinsamer Nenner", oder man muss beides einbauen, was aber gerade einem gemeinsamen Quellenformat widerspricht.

Genau deshalb hatte ich u.a. hier (https://forum.fhem.de/index.php/topic,109982.msg1039802.html#msg1039802) eine weitere Möglichkeit ins Spiel gebracht, die aus dem md-files sowohl html (als Vorstufe für die epub-Generierung) als auch PDF erstellt (entspr Beispielfiles siehe im Anhang des verlinkten Beitrags). Da ist nur eben das Thema mit den teilweise nicht funktionierenden internen Links ein Problem, aber vielleicht könnte da ein Experte ja eine Lösung finden.

[Beta-User]

So,

vielleicht mal an der Stelle ein paar Bausteinchen mehr zu dem, was hinter der Umstrukturierung hin zu "refs_pdf.md" gestern steckt.

Vorab:
- Ob das der Weisheit letzter Schluß war, weiß ich auch noch nicht, denn dass das die Preview-Möglichkeiten incl. Bilder zerschießt, war klar. Vorher hatte ich das jeweils am Dokument-Ende zusammengefasst, weiß aber nicht, ob damit alle Viewer umgehen könnten.
- Der "look" weder des pdf noch des epub sind bisher optimal. Die pdf-Fassung, die wikito-converter erzeugt, sieht auch imo besser aus, aber kaputte interne Links "gehen gar nicht". epub ist im Moment wie gesagt aber eigentlich eher von untergeordneter Bedeutung, aber auch da hatte ich ein "Schlüsselerlebnis", das vermutlich auch und v.a. bei der Mediawiki-Konvertierung helfen könnte...

Wegen der kaputten internen Links: Vor allem deswegen kommt letztendlich wikito-converter nicht wirklich in die engere Wahl, genauso wenig wie überhaupt der Weg über html, den man übrigens auch via pandoc nehmen könnte (ich meine, dazu schon was geschrieben zu haben, weiß allerdings nicht mehr wo bzw. über welchen Kanal). pandoc kann auch was anderes nicht, nämlich html-Style eingebundene Bilder ohne html als Zwischenformat (!) erkennen; das kommt schlicht als Text raus, genau so, wie man das eingegeben hatte...

Jetzt also mal die "pandoc-Route":
Der Ausgangspunkt meiner Überlegungen ist im Prinzip hier zu finden:https://www.xaprb.com/blog/how-to-style-images-with-markdown/. Das ist imo bzgl. der Bilder-Frage eine "extended version" von "testfile.md", allerdings etwas schwerer zu erkennen, weil da nur kurz auf "Use Standard HTML" eingegangen wird. Ich hatte mit einigen Varianten dort rumgespielt, dto. mit dem Versuch, das ganze in Tabellen zu packen.
Via pandoc Tabellen hinzubekommen, ist allerdings tricky, und mit Bildern darin ist es mir bisher schlicht nicht gelungen.

ABER: Je nachdem, WO man bestimmte Flags hinsetzt (unter "Use CSS And Special URL Parameters" zu finden), bekommt man sehr unterschiedliche Ergebnisse, unter anderem ist es mir (ich meine, mit der "img[src*="#thumbnail"]"-Variante) "gelungen", im pandoc-pdf einen _Text_ zu produzieren (nämlich den html-style Link, *staun*)...
Reste dieser Versuche findet ihr in der pandoc.css.

Damit war die Idee geboren, je nach End-Format unterschiedliche "Flags" zu setzen, um damit das passende Ergebnis zu erzeugen . Damit man das aber auch schnell wiederfindet, braucht es eben einen (relativ) zentralen Ort, und da das Setzen der passenden flags vermutlich tricky ist, macht es auch wenig Sinn, die  einzelnen Mitwirkenden rumrätseln zu lassen, was denn jetzt das passende "setting" ist. Volles WYSWIG ist zwar sehr komfortabel, aber es geht notfalls mMn. auch ohne.

Einen weiteren Netzfund will ich euch auch nicht vorenthalten:
https://cmichel.io/how-to-create-beautiful-epub-programming-ebooks/. Darin findet man u.A. unter Hinweis auf http://bbebooksthailand.com/bb-CSS-boilerplate.html eine "nette" css-file, die einen bestimmten Zweck hat: "Falsche" Vorgaben aus der epub-Konvertierung rauszufischen . Ausgetestet, und siehe da: das E-Book sieht via pandoc generiert gleich viel besser aus (es hat dann andere Mängel, insbesondere viel zu viele leere Seiten und die Sprungmarken sind jeweils "davor"...).

Bzgl. TeX und pdf gibt es an zwei Stellen auch noch Fortschritte zu verzeichnen:
- Bild auf Titelseite (dafür paßt der Text nicht, das war aber vorher schon...)
- Code "rot auf grau"

Lösung zu Punkt 1:
Titelpage als tex (siehe Anhang) und anderer "bau-Befehl", was "--include-before-body" angeht

Code Auswählen Erweitern

--include-before-body=frontpage.tex

(Für die Fußzeile wäre es wohl ähnlich, WIP)

Lösung zu Punkt 2 wäre, das hier in die tex-formatting aufzunehmen (%=Kommentar):

Code Auswählen Erweitern

%Formatierung von Code
%https://stackoverflow.com/a/40975732
\usepackage{fancyvrb,newverbs,xcolor}

\definecolor{Light}{gray}{.90}
%\definecolor{Light}{HTML}{F4F4F4}

\let\oldtexttt\texttt
\renewcommand{\texttt}[1]{
  \colorbox{Light}{\color{red!90}{\oldtexttt{#1}}}
}
Sowas bräuchten wir vermutlich noch für andere Elemente, angefangen von den Schriften. Wer Vorschläge hat: tell me...

Anbei auch das pdf und das epub (Achtung: das bringt mir aber grade "weiter hinten" Calibre zum (Fast-Dauer-) "Sanduhrzeigen"...), damit ihr sehen könnt, wie das rauskommt... (@eventuelle Erstleser: da sind keine neuen Teile drin, das ist also wirklich nur aus optischen Gründen hier angehängt).

Kurz zusammengefaßt: Steinig, mühsam, ... aber im Ergebnis scheint mir zumindest für die pdf-Fassung pandoc weiter das Mittel der Wahl zu sein. Für die epub-Version evtl. nicht.
Auch für Wiki bin ich betr. pandoc optimistisch; evtl. kann man sogar direkt (!) via css die "richtigen" Textbausteinchen reinmischen, die man dafür braucht!

Was den "LaTeX-Restbestand" "\footnotesize" etc. angeht, wäre mein nächster Test, das iVm. passenden css-Einträgen in die Richtung zu versuchen: "[][#remarkstart]" und "[][#remarkend]".

(v.a.) @xenos1984:
Das ist jetzt alles eher LATeX-nahe. Paßt das soweit und hast du Vorschläge für die Schriftfrage? Hast du Erfahrung mit der .css-Geschichte und kannst mir verraten, ob ich damit auf dem richtigen Weg bin?

Hoffe, das ist jetzt etwas klarer?

(Das alles ist für mich ziemlich komplex, und  ich muß ehrlich zugeben, dass mir jetzt zwar manches etwas klarer ist, aber der "letzte Schliff" definitiv noch fehlt...)

[Schotty]

Sieht m.M.n. gut/besser aus @Beta-User! Vor allem die rote Schrift auf grauem Grund für die Codezeilen macht es imho viel übersichtlicher. Im PDF auf S.25 scheint die Schrift allerdings eine andere zu sein - nur für den Fall, dass das so nicht gewollt war..

Das epub zickt bei mir auch rum:
- Kap. 2 (FHEM-Grundlagen) wird nach wie vor leider überhaupt nicht angezeigt und
- früher oder später scheint sich der ganze Reader/das AddOn aufzuhängen, wenn ich im Inhaltsverzeichnis die Links anklicke
Zum Testen für die epub-Ansicht nutze ich derzeit nur schnell das "EPUB-Reader"-AddOn für Firefox, damit wir nicht alle mit den gleichen Tools (= Calibre ) testen.

[xenos1984]

Die LaTeX Umsetzung sieht schon recht gut aus. Die Formatierung der Code-Elemente finde ich auch recht gelungen. Ich persönlich benutze für Code in LaTeX Dokumenten ein Package namens "listings", mit dem man noch schöner formatieren kann, inkl. Syntax-Hervorhebung, allerdings ist das sicher nicht nach epub etc. portabel. Wobei ich nicht weiß, ob vielleicht Pandoc einen "fenced code block" in ein listing-kompatibles Ergebnis umwandeln kann...

Mit epub kenne ich mich generell wenig aus, bzw. mit CSS nur in Kombination mit reinem HTML5. Von daher kann ich dazu leider wenig sagen.

Ich benutze zum epub lesen FBReader, aber scheinbar fehlen dabei Seiten / Abschnitte. Ich wollte mir die Code-Beispiele in Abschnitt 2.3 ansehen, aber der fehlt komplett...

[xenos1984]

Um noch einmal eine ganz andere Idee einzuwerfen: Beim Stöbern bin ich über DocBook gestolpert, das dafür dienen soll, Dokumentation u.a. als PDF, EPUB und HTML zu erstellen. Das klingt so ziemlich wie das, was hier gesucht wird. Genauer mit den verfügbaren Programmen habe ich mich noch nicht befasst. Auch ist die Syntax (XML) klobiger als bei Markdown. Dafür hat es mehr Formatierungsmöglichkeiten.

Vielleicht besser geeignet: AsciiDoc. Die Syntax ist einfacher, es unterstützt Textformatierung und man kann es scheinbar ebenfalls in HTML, PDF, EPUB konvertieren. Getestet habe ich es noch nicht.

[xenos1984]

Ich habe einmal spaßeshalber ein Kapitel von Markdown nach AsciiDoc konvertiert (mittels Pandoc, und dann von Hand weiter angepasst). Die entsprechende Datei habe ich angehängt, ebenso das Ergebnis folgender Umwandlungen:

Code Auswählen Erweitern

asciidoc -b html5 -o test.html test.txt
a2x -f pdf test.txt
a2x -f epub test.txt

Noch nicht probiert habe ich Bilder, auch Textformatierung nur rudimentär. Da kann man sicher noch mehr machen - es ist eher ein "proof of concept", dass man diese verschiedenen Formate rausbekommt und der Quelltext lesbar bleibt.

[Beta-User]

 
Das sieht auch brauchbar aus, und auch der Quelltext ist "easy" zu verstehen, halt nochmal anders, aber das wäre an sich kein Problem...

(Woher wußtest du, dass ich gerne Boxen haben will?)

Das als Fußnote (?) zu formatieren, wäre auch mit Markdown kein Problem, es scheint @AsciiDoc halt noch ein paar mehr "Grundtypen" für Anmerkungen oä. zu geben, so dass wir da schneller zum Ziel kämen (dafür aber englische Begrifflichkeiten am Rand stehen, die man vermutlich auch irgendwie in beliebige andere Sprachen bekommt; nur eben wieder: wie...?).

Vielleicht noch eine Anmerkung zu LaTeX: Ich habe kein grundsätzliches Problem damit, das da an verschiedenen Stellen "die Keule" rausgeholt werden muß. Ich selbst habe mich in die ganze Thematik nur soweit eingedacht, wie es notwendig war, und mir würde es auch reichen, wenn wir für die pdf-Generierung eben noch die paar "Schalter" ergänzen, die es braucht, um das auf "gefühlte 80%" zu bringen - eine "ideale Positionierung von Bildern" gehört da für mich schon nicht mehr unbedingt dazu.
Unschön ist halt, dass "man" - je nach "Schalter"/eingebundenem Package - eben "einiges LaTeX braucht, um das pdf zu backen, aber das sehe ich nicht als wirkliches Hindernis.
Von daher würde mich tendenziell die Feinheiten zu "listings" mehr interessieren als noch ein Format...
(Was das fenced code block angeht, würde ich tippen, dass man in der epub.css die richtigen Einstellungen finden muß, und code sieht an der Stelle direkt "ordentlich" aus, zum Rest: siehe html gleich.)

Was die "kaputten internen Links" bei der pandoc-html-Variante angeht, wäre meine Vermutung, dass sich das in Luft auflöst, sobald man alle (md-) files erst in eine einzige "Groß-md" piped und die dann "verhtml't" (dann bekommt man aber nicht mehr das seitliche Inhaltsverzeichnis mit Schotty's Variante hin).

Was epub (remember: Prio 5) angeht: Das dürfte auf Basis von html-code besser funktionieren, kann dann noch sein, dass man zum einen etwas aufpassen muß, was Sonderzeichen in Überschriften angeht, und zum anderen, wie man mit Bildern umgeht (lokal einbinden, vorrendern...); denn dass es "ewig dauert", dann aber am Ende zumindest in Calibre doch dargestellt wird, muss ja einen Grund haben...

Mal schauen.

Jedenfalls: Wenn wir bei Bildern keine Fortschritte haben, würde ich eher die "pure Markdown" (ohne html)-Variante weiter verfolgen und nicht das Format wechseln - md "kennen" tendenziell eben  schon ein paar Leute mehr.

[Schotty]

Was die "kaputten internen Links" bei der pandoc-html-Variante angeht, wäre meine Vermutung, dass sich das in Luft auflöst, sobald man alle (md-) files erst in eine einzige "Groß-md" piped und die dann "verhtml't" (dann bekommt man aber nicht mehr das seitliche Inhaltsverzeichnis mit Schotty's Variante hin).

Also mit einem fehlenden seitlichen Inhaltsverzeichnis hätte ich persönlich jetzt nicht so das Problem..

[xenos1984]

Das als Fußnote (?) zu formatieren, wäre auch mit Markdown kein Problem, es scheint @AsciiDoc halt noch ein paar mehr "Grundtypen" für Anmerkungen oä. zu geben, so dass wir da schneller zum Ziel kämen (dafür aber englische Begrifflichkeiten am Rand stehen, die man vermutlich auch irgendwie in beliebige andere Sprachen bekommt; nur eben wieder: wie...?).

Indem man den drei Befehlen oben noch eine Option gibt:

Code Auswählen Erweitern

-a lang=de

Vielleicht noch eine Anmerkung zu LaTeX: Ich habe kein grundsätzliches Problem damit, das da an verschiedenen Stellen "die Keule" rausgeholt werden muß. Ich selbst habe mich in die ganze Thematik nur soweit eingedacht, wie es notwendig war, und mir würde es auch reichen, wenn wir für die pdf-Generierung eben noch die paar "Schalter" ergänzen, die es braucht, um das auf "gefühlte 80%" zu bringen - eine "ideale Positionierung von Bildern" gehört da für mich schon nicht mehr unbedingt dazu.
Unschön ist halt, dass "man" - je nach "Schalter"/eingebundenem Package - eben "einiges LaTeX braucht, um das pdf zu backen, aber das sehe ich nicht als wirkliches Hindernis.

Das kann man natürlich machen, wobei man sich damit natürlich auch noch stärker an LaTeX bindet und eine mögliche Konvertierung in andere Formate (Wiki, HTML) schwieriger wird. Da stellt sich dann auch die Frage, ob man nicht gleich komplett mit LaTeX arbeitet und die anderen Formate verwirft, statt eine Mischung aus Markdown + LaTeX zu benutzen, die dann nur noch von Kennern beider Sprachen wartbar ist.

Von daher würde mich tendenziell die Feinheiten zu "listings" mehr interessieren als noch ein Format...
(Was das fenced code block angeht, würde ich tippen, dass man in der epub.css die richtigen Einstellungen finden muß, und code sieht an der Stelle direkt "ordentlich" aus, zum Rest: siehe html gleich.)

Damit (listings) ist es sicher machbar, Perl zu formatieren, aber auch für FHEM lässt sich eine Syntax erstellen. Das kann ich, falls gewünscht, auch gerne tun. Aber auch hier gilt, dass das dann komplett LaTeX-spezifisch und nicht auf andere Formate portabel wäre, womit man sich komplett auf ein Ausgabeformat binden würde.
Details: http://texdoc.net/texmf-dist/doc/latex/listings/listings.pdf

AsciiDoc scheint auch hier eine portable Lösung anzubieten: http://asciidoc.org/source-highlight-filter.html

Was die "kaputten internen Links" bei der pandoc-html-Variante angeht, wäre meine Vermutung, dass sich das in Luft auflöst, sobald man alle (md-) files erst in eine einzige "Groß-md" piped und die dann "verhtml't" (dann bekommt man aber nicht mehr das seitliche Inhaltsverzeichnis mit Schotty's Variante hin).

Hier habe ich mich noch nicht ganz in die Umsetzung der Formate eingelesen. Meine Erfahrung aus LaTeX ist die, dass es sich anbietet, Anker / Verweisziele mit deskriptiven Kürzeln zu benennen, wenn das Format dies unterstützt (z.B. sec:intro), statt mit der vollen Überschrift eines Abschnitts, weil man erfahrungsgemäß letztere doch mal ändert, und dann in der übrigen Doku alles ersetzen muss.

Jedenfalls: Wenn wir bei Bildern keine Fortschritte haben, würde ich eher die "pure Markdown" (ohne html)-Variante weiter verfolgen und nicht das Format wechseln - md "kennen" tendenziell eben  schon ein paar Leute mehr.

Auch hier die Frage: Wie hättest du es denn gerne? Ich habe mich inzwischen etwas in AsciiDoc eingefuchst, und es scheint auch für Bilder eine flexiblere und möglicherweise portable Formatierung zu bieten:
http://asciidoc.org/userguide.html#X9
Eine Möglichkeit wäre es, einfach mal damit herumzuprobieren, um sich etwas hübsches und portables damit erstellen lässt, und ob das besser aussieht / einfacher umzusetzen ist als mit Markdown.

[Beta-User]

 
Ich glaube, da hat mich jemand überzeugt, doch nochmal (teilweise) die Pferde zu wechseln und auf AsciiDoc zu setzen...

Zur Vorgehensweise:
@xenos1986, könntest du dann das komplette layouten übernehmen?
Ich (oder du?) würde dann nur "auf die Schnelle" via pandoc alle Files nach AsciiDoc konvertieren? Die Nacharbeit in Kap. 1 ist ja schon gemacht, wenn ich das richtig interpretiere geht es vorrangig darum, die Links wieder zu dezentralisieren (geht evtl. automatisch, wenn man beim Konvertieren die Link-md mit einbindet?) und dann eben v.a. die "für später"-Teile entsprechend zu kennzeichnen, oder?

Bei den Bildern schwebte mir vor, das meiste jeweils nach rechts zu pinnen bei ca. 50% Seitenbreite, ausgenommen die ganz kleinen Bildchen bzw. die ganz großen. Dabei Textumlauf links, den Text aber nicht zu gedrängt an die Bilder dranpinnen, evtl. einen Rahmen drumrum, und tendenziell eigentlich keine Beschriftungen. (Aber wenn du das Layout übernimmst, halte ich mich im wesentlichen raus, wenn gewünscht!)

Was Schriften usw. angeht, würde ich als Grundtype eher eine Serifenlose nehmen, das könnte sogar die sein, die hier im Forum genutzt wird, die ist eigentlich ganz gut lesbar und bietet etwas mehr Orientierung als z.B. Arial.
Zeilenabstand darf gerne etwas größer sein, wie von andies bereits angemerkt.

Paßt das so für Dich?

Danke für's Nachbohren!

[xenos1984]

@xenos1986, könntest du dann das komplette layouten übernehmen?

Ich kann es versuchen, muss aber zugeben, dass ich nicht der große Layout-Experte bin Mit der technischen Umsetzung bin ich versierter als mit der Begutachtung, ob es "gut" aussieht.

Ich (oder du?) würde dann nur "auf die Schnelle" via pandoc alle Files nach AsciiDoc konvertieren? Die Nacharbeit in Kap. 1 ist ja schon gemacht, wenn ich das richtig interpretiere geht es vorrangig darum, die Links wieder zu dezentralisieren (geht evtl. automatisch, wenn man beim Konvertieren die Link-md mit einbindet?) und dann eben v.a. die "für später"-Teile entsprechend zu kennzeichnen, oder?

Falls du die automatische Konvertierung mit pandoc (dabei habe ich das gleiche -f Attribut benutzt wie bei deinem Beispiel und -t asciidoc) und die erste Nacharbeit wie von dir beschrieben übernehmen könntest, würde ich die Feinarbeit machen und die Dinge, wo es "klemmt", insbesondere die Formatierung der Bilder und vielleicht manches, das etwas mehr Einarbeitung erfordert.

Bei den Bildern schwebte mir vor, das meiste jeweils nach rechts zu pinnen bei ca. 50% Seitenbreite, ausgenommen die ganz kleinen Bildchen bzw. die ganz großen. Dabei Textumlauf links, den Text aber nicht zu gedrängt an die Bilder dranpinnen, evtl. einen Rahmen drumrum, und tendenziell eigentlich keine Beschriftungen. (Aber wenn du das Layout übernimmst, halte ich mich im wesentlichen raus, wenn gewünscht!)

Ich denke, sowas lässt sich hinbekommen. Meine Werke haben normalerweise selten Bilder, deshalb frage ich lieber nach

Was Schriften usw. angeht, würde ich als Grundtype eher eine Serifenlose nehmen, das könnte sogar die sein, die hier im Forum genutzt wird, die ist eigentlich ganz gut lesbar und bietet etwas mehr Orientierung als z.B. Arial.
Zeilenabstand darf gerne etwas größer sein, wie von andies bereits angemerkt.

Das denke ich auch. Ich nehme meistens DejaVu Sans oder Liberation Sans.

Paßt das so für Dich?

Klingt gut!

Danke für's Nachbohren!

Nichts zu danken! Wenn es zu weniger Arbeit und einem schöneren Ergebnis führt, lohnt es sich ja

[Beta-User]

So, jetzt habe ich das mal probiert und bin etwas ratlos; meine Ergebnisse sehen erst mal etwas anders aus als deine (Vorschau gibt's unter Okular auch keine), von daher: Geht das in die richtige Richtung bzw. brauchst du mehr als das, was jetzt im svn zu finden ist?
https://svn.fhem.de/trac/browser/branches/epdf2020
(lokale Kopie sollte gem. https://svn.fhem.de/ so klappen:

Code Auswählen Erweitern

svn co https://svn.fhem.de/fhem/branches/epdf2020 <directory>

Wenn das paßt, würde ich den Rest auch in die Richtung anpassen, aber das sieht eigentlich erst mal nach sehr viel mehr Anpassung aus, was in kap01.txt als Muster drin war.

Code Auswählen Erweitern

a2x -f pdf intro.txt

liefert zwar ein Ergebnis, aber wenn ich die drei files erst mit cat zusammenklebe und dann den pdf-Konverter anwerfe, kommt erst mal nichts raus. Aber immerhin sind die Bilder-Links (als Text-Link) wieder "an Ort und Stelle", und sogar Formatierungsanweisungen wären zu finden.
Für kap02 (bzw. auch das zusammengeklebte File) bekomme ich folgende Meldung:

Code Auswählen Erweitern

a2x: ERROR: "xmllint" --nonet --noout --valid " [...] Doku/branches/epdf2020/pdf.xml" returned non-zero exit status 4


Wie jetzt am besten weiter?

[xenos1984]

Ich werde mal schauen, was da los ist. Meine Vermutung sind "leere" Kapitel. DocBook (was als Zwischenformat bei der Konvertierung von AsciiDoc nach PDF benutzt wird) wirft dann einen Fehler. Deshalb hatte ich unter jeder Überschrift ein tbd ergänzt, falls dort noch kein Text war.

Die Dateien konnte ich auch mit SVN auschecken.

[Beta-User]

Hallo zusammen,

habe jetzt eine "verpdf-bare" AsciiDoc-Variante ins svn geschubst. Da paßt hinten raus noch was mit den Zeilenumbrüchen (bzw. deren Zahl) nicht, die Überschriften sind teils nicht auf der richtigen Ebene usw., aber immerhin kann man alles mit cat in eine Datei packen und dann kommt wieder was raus...

Kleinere Korrekturen sind auch drin, aber nix großes, hauptsächlich Quotes...

just for your info.

[Schotty]

@Beta-User: Ich habe mir mal kap02.txt zur Brust genommen und ein paar Korrekturen, Umformulierungen und Anmerkungen (im Text mit "(ANMERKUNG v. Schotty: ...)" gekennzeichnet) vorgenommen. Rudi hat mir zwar Schreibrechte fürs SVN erteilt, aber ich hänge die Datei jetzt erstmal lieber hier an. Wie du siehst habe ich sie auch etwas umbenannt, damit du lokal bei dir nicht durchn Tüddel kommst - falls es dadurch Probleme beim Erzeugen eines Diffs gibt, sag bescheid, dann belasse ich die Dateinamen in Zukunft so, wie sie sind. Kannst es dir ja mal ansehen, ob es so für dich Sinn macht und auch mit den (ANMERKUNGEN ...) so gangbar und deutlich genug ist.
Hinsichtlich des Zusammenhangs zwischen dem Geschriebenen und den Screenshots habe ich jetzt noch nicht weiter nachgesehen, da warte ich, bis du ein 'fertiges' PDF zur Verfügung stellst (macht m.A.n. mehr Sinn).
Gruß

[Beta-User]

Hi Schotty,

ich schau mir das nochmal im Detail an, aber mal vorneweg einfach das feedback: sehr hilfreich!

Damit andere das zum einen Nachvollziehen können und zum anderen ein paar Dinge drin sind, die ich gerne "als Linie" geklärt hätte, einfach mal der Reihe nach die "Anmerkungen":



ANMERKUNG v. Schotty bzgl 'Cinema': Vielleicht anders formulieren, bspw "(..)"nach FHEM" und dann in den neu zu erstellenden 'Raum' namens "Cinema" zu bringen"
Im Testsystem gibt es den Raum schon, und es wird vorher auf die "Einträge" links Bezug genommen. Müßte also passen, wenn man das Bild vor Augen hat, oder?



ANMERKUNG v. Schotty: Der Begriff taucht hier zum ersten Mal auf - evtl vorher einmal drauf eingehen, was ein 'Modul' ist?!?
- Der Hinweis ist berechtigt, aber die Lösung nicht so einfach... Generell war mein Gedanke, nicht allzuviel Theorie usw. "nach vorne" zu packen, sondern das eher "intuitiv" zu versuchen. Aber die weiteren Anmerkungen in diese Richtung zeigen, dass es wohl etwas "too much" ist und wir uns für das Grundproblem was überlegen müssen.
- War erst am überlegen, ob man hier konkret einfach den Modulbegriff meiden sollte und stattdessen "commandref"-Eintrag schreiben, aber nachdem ich den Text nochmal etwas mehr im Zusammenhang gelesen habe, sollte man wohl wirklich etwas (hier wohl sogar deutlich) ausführlicher erläutern, was da grade passiert ist... (tbd.)


ANMERKUNG v. Schotty: Evtl noch einen Hinweis einfügen, wo die Dateien zu finden sind?
(zu fhem.cfg und statefile) Für fhem.cfg.demo ist es m.E. klar (bzw. es ist ok, wenn der Leser darüber nachdenkt), wir kommen ja aus der Kommandozeile. Für statefile wäre die Frage, ob man ganz dürre Worte verliert, oder bei sowas generell einfach einen Link setzt, wo das dann zu finden ist (gehört zu "global", auf das wir nochmal intensiver eingehen werden (fehlt noch), siehe https://fhem.de/commandref_modular_DE.html#global. Tendenziell würde ich einen einfachen Link auf die pdf-Erklärung zu global setzen?).


ANMERKUNG v. Schotty: Welche Anführungszeichen? Hier im Text habe ich diesbzgl keine entdeckt
...die sind meiner Schnellkorrektur zum Opfer gefallen => auch der Klammerzusatz kann weg.

ANMERKUNG v. Schotty: Dann vielleicht direkt auf die Sonderzeichen beim alias verzichten und darauf hinweisen, dass eine Verwendung von Sonderzeichen generell unterlassen werden sollte?
Nun ja, an der Stelle geht es ja... Denke, dass wir einerseits zu Demo-Zwecken _nicht_ darauf verzichten und andererseits vielleicht darauf hinweisen, dass auch der Gebrauch von Sonderzeichen usw. in alias-Attributen nicht so toll ist. Zudem fehlt, dass alias nicht "unique" sein muß...

ANMERKUNG v. Schotty: Welche direkteren Formen? Wenn du hier noch nicht darauf eingehst, dann diese Anmerkung in der Klammer evtl ganz weglassen
CommandSet, z.B.. Und darauf einzugehen, führt tatsächlich (viel) zu weit. Andererseits muß einem nicht beim ersten Lesen alles klar sein, und für den Experten-Leser wird so eher klar, dass das eben eine Vereinfachung ist und mehr Möglichkeiten bestehen. Neige dazu, das so zu lassen.

ANMERKUNG v. Schotty: Der Satz ist irgendwie sehr verschachtelt ...
Berechtigter Hinweis. So einfacher:
"Die mit setstate beginnenden Zeilen brauchen wir nicht, aber das sind die Zeilen, die in der oben bereits erwähnten *statefile* gespeichert werden. Dir fällt vielleicht auf, dass hier statt des _define_, das du eingegeben hattest, die Schreibweise _defmod_ verwendet wird? Zum Unterschied zwischen beiden kommen wir gleich. Jedenfalls wird das _define_ sowie die Attribute in der Konfigurationsfile (zuerst meistens _fhem.cfg_) gespeichert."

ANMERKUNG v. Schotty: Diesen Hinweis bzgl Nicht-Speichern der Demo-Konfig vielleicht direkt am Anfang des Umgangs mit dem Demo-System bringen...
Kann sein, habe da auch immer mal wieder überlegt, wo der richtige Ort für den Hinweis ist. An sich ist es nicht wirklich wichtig, im schlimmsten Fall ist eben ein Shelly oder Receiver in der demo-config. Richtig doof wird das erst, wenn der Port geändert ist...
Vielleicht am einfachsten noch einen Zusatz machen wie: "Falls du das doch schon gespeichert hattest: nicht schlimm, aber ab jetzt bitte erst wieder, wenn es ausdrücklich dasteht und dann genau so wie angegeben!"

ANMERKUNG v. Schotty: Wie weiter oben schon geschrieben wäre es m.E. ratsam, auf den Unterschied diesbzgl bereits weiter oben einzugehen.
(bezieht sich auf "defmod"). Hat sich mit der Änderung oben erübrigt, oder?

ANMERKUNG v. Schotty: Der Befehl 'help' sollte m.A.n. ebenfalls schon vorher, ansonsten aber nochmal gesondert explizit genannt werden, auch mit dem Hinweis auf die Verfügbarkeit der Hilfe-Funktion hinsichtlich Modulen. Dort ist dann ja auch entnehmbar, in welchem Board/Unterforum Fragen bzgl des Moduls gestellt werden können etc.
Das mit "Wie bekomme ich Hilfe im Forum" hätte ich nach hinten geschoben, der Platzhalter war u.A. dafür gedacht. Aber auch hier war ich vermutlich "zu schnell". Etwas langsamer?

"Da auch das `save`-Kommando ein paar Optionen kennt, schauen wir uns das erst mal etwas genauer an. Du könntest jetzt wieder den Eintrag _commandref_ aus dem Menü links aufrufen, aber es gibt eine weitere, direktere Variante, an diese Informationen zu kommen. Versuch's mal mit `help save`.



ANMERKUNG v. Schotty: Im Satz vorher steht, dass "die aktuell laufende Sitzung mit dem Demo-System beschäftigt ist" - wenn dem so ist, warum muss es dann jetzt nochmal neu gestartet werden?
Da ist mir beim Verschieben von Textblöcken bzw. nachträglichen Änderungen im Vorgehen was durcheinandergeraten, muß korrigiert werden!


ANMERKUNG v. Schotty: Der letzte Satz ist m.A.n. ebenfalls 'unklar'..
(bezieht sich auf Alternativen zu fhem.cfg = configDB). Würde hier auch einen (kommentarlosen) Link auf einen noch fehlenden Teil einfügen?


ANMERKUNG v. Schotty: Was ist der Unterschied zw "save" und "save minimal.cfg"? Das ist/wird hier nicht deutlich, eine Erklärung wäre sicherlich hilfreich.
An sich ist gewollt, dass der Leser sich diese Frage stellt... Ist aber vermutlich wirklich noch zu schwierig, wie wäre es mit einer Erweiterung?
"Wie wäre es also jetzt mit einem schnellen `save minimal.cfg`? Dann haben wir noch eine vierte Konfigurationsdatei _minimal.cfg_ im fhem-Verzeichnis liegen, mit der wir FHEM starten können."


Du siehst also: Diese Art des kritischen Durchsehens hilft.

Wäre schön, wenn ihr (ggf. einfach per Stichwort) kurz was dazu sagen könntet, auch zu den Geschmacksfragen.

Das diff im Detail sehe ich mir nochmal gesondert an.

[Schotty]

Im Testsystem gibt es den Raum schon, und es wird vorher auf die "Einträge" links Bezug genommen. Müßte also passen, wenn man das Bild vor Augen hat, oder?

Yupp, wird wohl so sein - wie gesagt, den 'Zusammenhang' zw Geschriebenem und den Grafiken habe ich jetzt noch nicht gecheckt, das gucke ich mir dann lieber mit einer (ersten) PDF-Version an, dann bekomme ich auch einen besseren Eindruck hinsichtlich Layout.

Generell war mein Gedanke, nicht allzuviel Theorie usw. "nach vorne" zu packen, sondern das eher "intuitiv" zu versuchen. Aber die weiteren Anmerkungen in diese Richtung zeigen, dass es wohl etwas "too much" ist und wir uns für das Grundproblem was überlegen müssen.

Yupp, intuitiv ist so eine Sache, denn bei 'Euch Experten' ist die Intuition in dem Fall eine gaaanz andere als bei 'uns n00bs'
Auch wenn manche Dinge dadurch für versierte User evtl 'langweilig/langatmig' werden, so ist die Zielgruppe m.E. aber ja eine andere, nämlich Anfänger mit null Plan vom Ganzen. Und für die können gewisse Dinge erfahrungsgemäß nicht 'einfach' genug erklärt sein. Also lieber einen Satz zuviel, als einen zuwenig..

- War erst am überlegen, ob man hier konkret einfach den Modulbegriff meiden sollte und stattdessen "commandref"-Eintrag schreiben, aber nachdem ich den Text nochmal etwas mehr im Zusammenhang gelesen habe, sollte man wohl wirklich etwas (hier wohl sogar deutlich) ausführlicher erläutern, was da grade passiert ist... (tbd.)

Imho sind GERADE Dinge wie 'Modul' etc unabdingbar erklärungsbedürftig für einen Einsteiger. Zum einen kommt das auch im Forumsbereich immer wieder als Antwort auf bestimmte Fragen ("da gibt's ein Modul für" -> öhm, ja, danke, aber wie/wo/was muß ich suchen? Ich habe doch keinen Plan?! ), und zum anderen könntest du auf das ganze Einsteiger-PDF verzichten, wenn letztlich doch (immer wieder) 'nur' auf die commandref oder das Wiki verwiesen wird (was ja grundsätzlich nicht der Fall ist, also bitte nicht falsch verstehen! ).

Bitte versteht mich hier nicht falsch - commandref und Wiki sind gute und wichtige Infoquellen, aber (Hand auf's Herz) nunmal nicht immer gerade einsteigerfreundlich formuliert (was ja auch vollkommen i.O. ist!). Selbst erfahrenere User haben da z.T. Verständnisprobleme, wenn ich mir diverse Forenbeiträge so ansehe.
Hinzu kommt, dass manche Beschreibungen in der commandref nur auf Englisch vorzuliegen scheinen (gerne auch mal mitten im deutschen Text) - allerdings spricht heutzutage nunmal noch immer nicht jeder Englisch und ist spätestens da aufgeschmissen. Was Google-Translator in einem solchen Fall draus macht, möchte ich gar nicht wissen.. (..hmm, oder vielleicht doch? Da kommen bestimmt lustige Sachen bei raus..  )

(zu fhem.cfg und statefile) Für fhem.cfg.demo ist es m.E. klar (bzw. es ist ok, wenn der Leser darüber nachdenkt), wir kommen ja aus der Kommandozeile.

Klar ist es ok, wenn der Leser nachdenkt - soll er ja auch - aber manche Dinge erschließen sich einem Einsteiger mangels Vor- oder Hintergrundwissen nunmal auch bei dem x-ten Lesen nicht (hermeneutischer Zirkel hin oder her), da kann er u.U. nachdenken, so viel er will. Logisch kannst/willst du nicht zeitgleich einen Windows/Linux/whatever-Basiskurs draus machen, aber wie gesagt: Eine Doku für Einsteiger/Anfänger zu erstellen ist eine andere Baustelle und erfordert m.A.n. andere Vorgehens- und auch Beschreibungsweisen, als eine Doku für versierte oder gar professionelle User.   

Für statefile wäre die Frage, ob man ganz dürre Worte verliert, oder bei sowas generell einfach einen Link setzt, wo das dann zu finden ist (gehört zu "global", auf das wir nochmal intensiver eingehen werden (fehlt noch), siehe https://fhem.de/commandref_modular_DE.html#global. Tendenziell würde ich einen einfachen Link auf die pdf-Erklärung zu global setzen?).

Wenn du 'später' im PDF eh drauf eingehst: Klar, dann bitte immer zusätzliche Links zu den entsprechenden (nachfolgenden) Kapiteln hinzufügen. Wenn du zusätzlich auch noch die passenden Links für den jeweiligen commandref- und/oder Wiki-Eintrag dazu packst - noch besser! Nur eben 'reine' Verweise auf cr/Wiki sind wie oben erwähnt m.E. nicht (immer) gerade zielführend.

ANMERKUNG v. Schotty: Dann vielleicht direkt auf die Sonderzeichen beim alias verzichten und darauf hinweisen, dass eine Verwendung von Sonderzeichen generell unterlassen werden sollte?
Nun ja, an der Stelle geht es ja... Denke, dass wir einerseits zu Demo-Zwecken _nicht_ darauf verzichten und andererseits vielleicht darauf hinweisen, dass auch der Gebrauch von Sonderzeichen usw. in alias-Attributen nicht so toll ist. Zudem fehlt, dass alias nicht "unique" sein muß...

Klar, dann so, wie du schreibst. Mir ging nur durch den Kopf, dass es vielleicht (erstmal) 'einfacher' für alle wäre, dazu zu raten, Sonderzeichen generell eher zu meiden.

ANMERKUNG v. Schotty: Welche direkteren Formen? Wenn du hier noch nicht darauf eingehst, dann diese Anmerkung in der Klammer evtl ganz weglassen
CommandSet, z.B.. Und darauf einzugehen, führt tatsächlich (viel) zu weit. Andererseits muß einem nicht beim ersten Lesen alles klar sein, und für den Experten-Leser wird so eher klar, dass das eben eine Vereinfachung ist und mehr Möglichkeiten bestehen. Neige dazu, das so zu lassen.

Selbstverständlich muss und kann einem beim ersten Lesen nicht alles klar sein, das Textverständnis ändert sich ja immer wieder mit dem neu erworbenen Wissen (wieder Stichwort 'hermeneutischer Zirkel'). Aber auch hier nochmal meine 2ct: Das ist/wird ein Einsteiger-PDF - "Experten-"Leser sind dabei (erstmal) eine andere Zielgruppe. Aber lass es ruhig so.

ANMERKUNG v. Schotty: Der Satz ist irgendwie sehr verschachtelt ...
Berechtigter Hinweis. So einfacher:
"Die mit setstate beginnenden Zeilen brauchen wir nicht, aber das sind die Zeilen, die in der oben bereits erwähnten *statefile* gespeichert werden. Dir fällt vielleicht auf, dass hier statt des _define_, das du eingegeben hattest, die Schreibweise _defmod_ verwendet wird? Zum Unterschied zwischen beiden kommen wir gleich. Jedenfalls wird das _define_ sowie die Attribute in der Konfigurationsfile (zuerst meistens _fhem.cfg_) gespeichert."

Yupp, so ist's besser!

ANMERKUNG v. Schotty: Diesen Hinweis bzgl Nicht-Speichern der Demo-Konfig vielleicht direkt am Anfang des Umgangs mit dem Demo-System bringen...
Kann sein, habe da auch immer mal wieder überlegt, wo der richtige Ort für den Hinweis ist. An sich ist es nicht wirklich wichtig, im schlimmsten Fall ist eben ein Shelly oder Receiver in der demo-config. Richtig doof wird das erst, wenn der Port geändert ist...
Vielleicht am einfachsten noch einen Zusatz machen wie: "Falls du das doch schon gespeichert hattest: nicht schlimm, aber ab jetzt bitte erst wieder, wenn es ausdrücklich dasteht und dann genau so wie angegeben!"

Klar, geht prinzipiell auch - aber was spräche dann dagegen, einfach ganz am Anfang des Doks einen Hinweissatz dieser Art unterzubringen? So à la "Bevor wir anfangen, uns mit der Einrichtung und Konfiguration von FHEM auseinander zu setzen, noch ein kurzer Hinweis, was das Speichern der (geänderten) Konfiguration angeht: Bitte speichere erst, wenn im Text ausdrücklich darauf hingewiesen wird und tue dies dann auch bitte exakt so, wie es beschrieben sein wird." Man muss ja nicht warten, bis das Kind in den Brunnen gefallen ist

ANMERKUNG v. Schotty: Wie weiter oben schon geschrieben wäre es m.E. ratsam, auf den Unterschied diesbzgl bereits weiter oben einzugehen.
(bezieht sich auf "defmod"). Hat sich mit der Änderung oben erübrigt, oder?

Yupp, alles schick

Das mit "Wie bekomme ich Hilfe im Forum" hätte ich nach hinten geschoben, der Platzhalter war u.A. dafür gedacht. Aber auch hier war ich vermutlich "zu schnell". Etwas langsamer?

"Da auch das `save`-Kommando ein paar Optionen kennt, schauen wir uns das erst mal etwas genauer an. Du könntest jetzt wieder den Eintrag _commandref_ aus dem Menü links aufrufen, aber es gibt eine weitere, direktere Variante, an diese Informationen zu kommen. Versuch's mal mit `help save`.

Ja, ginge natürlich, und wenn das Thema 'help' später nochmal explizit behandelt wird, dann kannst du auch wieder zusätzlich den Link zu dem entspr Kap im PDF setzen.

Vielleicht sollten wir aber für so zentrale Punkte generell auch noch einen kleinen Index am Dokumentenende erstellen, je nachdem, wie 'verschachtelt' am Ende gewisse Themen im Text oder auch im Inhaltsverzeichnis sind. Aber da können wir ja zum Schluss nochmal drüber nachdenken.

ANMERKUNG v. Schotty: Der letzte Satz ist m.A.n. ebenfalls 'unklar'..
(bezieht sich auf Alternativen zu fhem.cfg = configDB). Würde hier auch einen (kommentarlosen) Link auf einen noch fehlenden Teil einfügen?

Ah ok, ja, dann passt es wieder.

ANMERKUNG v. Schotty: Was ist der Unterschied zw "save" und "save minimal.cfg"? Das ist/wird hier nicht deutlich, eine Erklärung wäre sicherlich hilfreich.
An sich ist gewollt, dass der Leser sich diese Frage stellt... Ist aber vermutlich wirklich noch zu schwierig, wie wäre es mit einer Erweiterung?
"Wie wäre es also jetzt mit einem schnellen `save minimal.cfg`? Dann haben wir noch eine vierte Konfigurationsdatei _minimal.cfg_ im fhem-Verzeichnis liegen, mit der wir FHEM starten können."

Yupp, die Erweiterung finde ich besser.

Bevor jetzt von irgendeiner Seite ein Aufschrei kommt: Logisch soll dem Einsteiger nicht alles 1:1 vorgekaut und präsentiert werden (Konfuzius und seine Fische), ist schon klar - aber es bringt (dem unbeleckten Leser) nicht viel, wenn man am Ende mit Fragen vor dem Dok sitzt, deren Antwort sich einem Einsteiger nunmal nicht erschließt oder (mangels Vor-/Hintergrundwissen) erschließen kann.
"Es ist gewollt, dass der Leser sich diese Frage stellt" ist verständlich und ja grundsätzlich auch richtig - es darf imho nur eben nicht so sein, dass sich die Antwort auf diese Frage durch das Lesen des Textes nicht klärt und der Leser damit allein gelassen wird.
Schließlich soll die Lektüre am Ende ja Spaß machen und dazu motivieren, sich auch über das Einsteiger-PDF hinausgehend in FHEM einzuarbeiten. Es bringt ja nichts, wenn der einsteigende Leser am Ende frustriert das Dok in den Papierkorb verschiebt und sich einem anderen HA-System zuwendet (wo er dann vermutlich vor ähnlichen Problemen steht - keine Ahnung, ich habe andere vielgelobte Systeme selbst nicht getestet), nur weil er im Grunde noch verwirrter und mit mehr Fragezeichen auf der Stirn dasitzt, als es ohnehin der Fall ist.

Von einer Anleitung für einen Einsteiger erwarte ich persönlich, dass selbiger damit wirklich einen guten und gangbaren Einstieg in die Benutzung -in diesem Fall von FHEM- erhält - das beinhaltet nunmal (leider?) auch, dass gewisse 'Selbstverständlichkeiten' erklärt werden. Notfalls auch mal an irgendeiner Stelle doppelt und anders formuliert.

Wenn es dann für ein gewisses Publikum zu einfach oder langweilig/langatmig wird - sorry guys, dann bitte bis zum nächsten Abschnitt querlesen oder direkt in die commandref abtauchen..

[Beta-User]

...das mit dem pdf muß erst mal noch warten, bin auch erst am Spielen mit der AsciiDoc-Syntax bzw. warte auch mal drauf, was xenos1984 daraus macht...

Die Bilder an sich sind aber vorhanden/kann man ansehen (ist aber "mühsam", klar) oder die Befehle auch "nachmachen" (an einem Testsystem).

Zum eigentlichen: Ist völlig ok, wenn du mich da auf eine erträgliche Geschwindigkeit einbremst, alles bestens, und ich hoffe, deine Anmerkungen auch "gut" eingearbeitet zu haben...

Bin noch nicht ganz fertig, aber zumindest sind die soweit erst mal "vorverarbeitet", und hoffe, dass du nach Lektüre etwas weniger Sorge hast, dass das "zu schnell" gehen soll . (manchmal steht nur "link" da; das sollte in der Regel ein "interner" sein, es ist nicht geplant, die Leser bei den "basics" auf irgendwelche externe Doku zu verweisen (es sei denn, die sei auf dem passenden Niveau oder kann dahin gebracht werden)). Und die eine oder andere Gelegenheit läßt sich vielleicht auch "konstruktiv nutzen" - bin mal gespannt, ob und wie ihr das findet, worauf ich grade anspiele )

[Schotty]

Ich will dich weder ein- noch ausbremsen, aber ich lese es wie gewünscht mit der 'DAU'-Brille und dementsprechend sind meine Anmerkungen/Vorschläge auch zu verstehen

Und die eine oder andere Gelegenheit läßt sich vielleicht auch "konstruktiv nutzen" - bin mal gespannt, ob und wie ihr das findet, worauf ich grade anspiele )

Ostereiersuchen ist vorbei 
Bzgl der 'Gelegenheiten' verstehe ich gerade nicht, was du meinst, aber vielleicht klärt sich das ja beim Lesen..

Noch eine generelle Anmerkung:
Wenn du die Änderungen o.ä. übernommen hast, würde ich es sinnvoller finden, wenn du das in die jeweilige Datei im SVN übernimmst und dort aktualisierst. Sonst haben wir hier ruck-zuck ein Kuddelmuddel (mit deiner neuen Version existieren jetzt bspw zwei Versionen der von mir angehängten Datei, das kann schnell unübersichtlich werden). Ich hatte es nur hier eingestellt, weil ich a) gucken wollte, ob das so ein gangbarer Weg ist, ich b) nichts 'zerschießen' wollte (bin noch nicht so firm mit SVN) und c) es so auch andere User machen könn(t)en, die keine SVN-Schreibrechte haben.

[Beta-User]

ist jetzt auch im svn, damit die Ostereiersuche einfacher wird (noch sind mancherorts Ferien...) .

[Schotty]

Sorry, hab's jetzt erst gesehen aber die angehängte Datei vorhin schon in der Mangel gehabt, korrigierte und kommentierte (nur in einem Fall, ich glaube ca Zeile 72, jetzt mit "(->2CHECK)" gekennzeichnet, das war dir vorhin wohl durchgerutscht) Fassung im Anhang.

Falls die (Haupt-)Ostereier mit M wie Modul und D wie define/defmod anfangen, dann habe ich sie gefunden und finde sie gut

EDIT: Stimmt nicht,hatte doch mindestens zwei anmerkungen gemacht,die o.g. und noch eine weitere..

[Beta-User]

So, das sollte jetzt weitestgehend in https://svn.fhem.de/trac/changeset/21705/ enthalten sein.

Das Hauptosterei war aber eher was anderes: Anleitungen genau befolgen .

[Schotty]

..gerade noch n typo entdeckt: abschnitt "save", erster block,letzte zeile: "Echtsysstem" -> ein s zuviel.

Falls du mit "anleitungen genau befolgen" meinst,dass ich alles schritt für schritt nachstellen soll: sorry,aber das schaffe ich zeitlich derzeit absolut nicht - bin froh,dass ich heute schonmal kap02 bis hierhin geschafft habe.. 

[Schotty]

Hier kap01.txt, gekennzeichnet als kap01_Schotty_v1.txt.

Generelle Anmerkungen/Fragen:
- Wörter wie firmware, zip, update, links etc schreibst du klein. Es sind zwar 'englische' Wörter, werden aber in der 'deutschen' Verwendung imho trotzdem groß geschrieben (die Firmware, das Zip, das Update etc). Ich habe es jetzt noch nicht durchgehend geändert, schlage es aber hiermit vor.
EDIT: Sehe gerade, dass du bspw "Interface" in kap09 auch großgeschrieben hast - würde ich wie gesagt dann durchgängig so empfehlen..
- An zwei Stellen bereits im Text gekennzeichnet, aber hier auch nochmal: M.A.n verwendest du etwas zu häufig Anführungszeichen für bestimmte Worte (s. Anmerkung im Text). Kam von anderer Seite hier auch schonmal als Anmerkung glaube ich (xenos?). Gerade, wenn du diejenigen Worte noch mit asciidoc-Syntax hervorherbst oder krusiv schreibst o.ä., dann ist es zuviel des Guten und macht den Text m.E. eher unleserlicher.
- Hatte ich bereits mal per Email nachgefragt, aber da wolltest du nochmal drüber nachdenken: "Du" oder "du"? Gestern in kap02 war es bereits klein geschrieben, hier in kap01 habe ich es jetzt auch geändert. Wenn du dennoch "Du", "Dein" etc groß schreiben willst, sag bitte bescheid, dann erspare ich mir und dir die Änderungen
EDIT: Ich sehe gerade, dass es in kap03 & kap09 auch klein geschrieben ist - werde ich dann jetzt erstmal so beibehalten..

Ansonsten: Hinweis von gestern Abd bzgl Typo in kap02 hattest du gesehen? (s. Beitrag über diesem)

[Schotty]

kap03

[Beta-User]

Vielleicht aus gegebenen Anlaß ein paar Anmerkungen zum "opus operandi":

(war zu langsam, hat sich teils überschnitten).

..gerade noch n typo entdeckt: abschnitt "save", erster block,letzte zeile: "Echtsysstem" -> ein s zuviel.

Bei sowas ist es m.E. am einfachsten, das direkt ins svn zu schubsen. Als Kommentar reicht es mir, dass es einen commit gibt...

Generell wären in meiner Wahrnehmung bisher alle Anmerkungen und Änderungen ganz gut im svn aufgehoben gewesen, man sieht da auch in der Regel sehr schnell, ob es größere oder kleinere Änderungen waren usw.. (und ich gehe davon aus, dass das bei den Vorschlägen zu kap01 auch nicht anders sein wird!)

Wenn man (kurze) Schlüsselwörter für Fragen oder Anregungen verwendet ("Schotty: " "xenos: ", "xxxx: ", "link" ...), ist das sogar gut, weil ich die dann ggf. auch als Merkposten länger "mitschleifen" kann, und ihr seht in den svn-diffs auch gleich, wann es ggf. wie gelöst wurde?

Falls du mit "anleitungen genau befolgen" meinst [...]

Nochmal: Kein Stress! Das war nicht an dich addressiert, sondern an dich ging die Frage: "Ist es eine gute Idee, den Leser ggf. erst mal in diese 'Falle' laufen zu lassen, um bei der Gelegenheit das Thema 'Anleitungen befolgen' auch gleich zu abzuräumen?".

Natürlich wäre es wünschenswert, wenn sich irgendwann mal noch irgendjemand an eine 1:1 Umsetzung machen würde, aber das eilt im Moment nicht und gehört eher in die Kategorie "Feinschliff".

Was fertiger ist, ist gut, was noch nicht: kein Problem. Wichtiger ist das mit den Anmerkungen gewesen!

Muß mir am WE mal die Zeit nehmen, die Bausteinchen zu sortieren und ggf. an kap02 weiterzuarbeiten (Tendenz da: global und fhem.pl). Von daher wäre von deiner Seite (@Schotty) ein (überschlägiger) review von kap03 und kap09 evtl. mal ganz gut (wenn Zeit dafür ist) - wobei je weiter hinten desto mehr zu erwarten ist, dass sich da noch einiges ändern wird.

@xenos1984: das "kontroll-pdf" hatte ich mit a2x erstellt. Das kann aber scheinbar mit den remote-Bildern nicht umgehen (ich habe die manpage noch nicht angesehen, ist evtl. einfach). Das würde mich im Moment jedenfalls von "deiner Seite" am meisten "drücken"... (auch nicht eilig!)

Generelle Anmerkungen/Fragen:
- Wörter wie firmware, zip, update, links etc schreibst du klein. Es sind zwar 'englische' Wörter, werden aber in der 'deutschen' Verwendung imho trotzdem groß geschrieben (die Firmware, das Zip, das Update etc). Ich habe es jetzt noch nicht durchgehend geändert, schlage es aber hiermit vor.

Akzeptiert!

- An zwei Stellen bereits im Text gekennzeichnet, aber hier auch nochmal: M.A.n verwendest du etwas zu häufig Anführungszeichen für bestimmte Worte (s. Anmerkung im Text). Kam von anderer Seite hier auch schonmal als Anmerkung glaube ich (xenos?). Gerade, wenn du diejenigen Worte noch mit asciidoc-Syntax hervorherbst oder krusiv schreibst o.ä., dann ist es zuviel des Guten und macht den Text m.E. eher unleserlicher.

andies hatte das kritisiert, ich habe das nebenbei ebenfalls in diese Richtung verändert. Würde vorschlagen, Anführungszeichen auf "eigene" (erfundene oder auf spezielle Weise verwendete) Begriffe zu reduzieren?
(Ich habe nur noch keine wirkliche Linie gefunden, wie man das am besten markiert, gehe aber davon aus, dass kursiv in der Mehrzahl der Fälle die beste Wahl ist. => nach Gutdünken so ändern).

- Hatte ich bereits mal per Email nachgefragt, aber da wolltest du nochmal drüber nachdenken: "Du" oder "du"? Gestern in kap02 war es bereits klein geschrieben, hier in kap01 habe ich es jetzt auch geändert. Wenn du dennoch "Du", "Dein" etc groß schreiben willst, sag bitte bescheid, dann erspare ich mir und dir die Änderungen
EDIT: Ich sehe gerade, dass es in kap03 auch klein geschrieben ist - werde ich dann jetzt erstmal so beibehalten..

Ja, wir wollen "auf den letzten Stand der Dinge" kommen, auch wenn mir du kleingeschrieben nur hier im Forum einigermaßen leicht von der Hand geht...

Bild wieder klarer?

[Schotty]

Generell wären in meiner Wahrnehmung bisher alle Anmerkungen und Änderungen ganz gut im svn aufgehoben gewesen, man sieht da auch in der Regel sehr schnell, ob es größere oder kleinere Änderungen waren usw.. (und ich gehe davon aus, dass das bei den Vorschlägen zu kap01 auch nicht anders sein wird!)

Hmpf, nun bin ich schon mit kap01, kap03 und fast mit kap09 durch - deswegen hatte ich doch gestern bei der ersten kap02-Fassung das hier geschrieben:

@Beta-User: Ich habe mir mal kap02.txt zur Brust genommen und ein paar Korrekturen, Umformulierungen und Anmerkungen (im Text mit "(ANMERKUNG v. Schotty: ...)" gekennzeichnet) vorgenommen. Rudi hat mir zwar Schreibrechte fürs SVN erteilt, aber ich hänge die Datei jetzt erstmal lieber hier an. Wie du siehst habe ich sie auch etwas umbenannt, damit du lokal bei dir nicht durchn Tüddel kommst - falls es dadurch Probleme beim Erzeugen eines Diffs gibt, sag bescheid, dann belasse ich die Dateinamen in Zukunft so, wie sie sind. Kannst es dir ja mal ansehen, ob es so für dich Sinn macht und auch mit den (ANMERKUNGEN ...) so gangbar und deutlich genug ist.

Aber egal, ich hänge kap09 jetzt gleich auch nochmal hier an und melde mich privat nochmal bei dir..

Wenn man (kurze) Schlüsselwörter für Fragen oder Anregungen verwendet ("Schotty: " "xenos: ", "xxxx: ", "link" ...), ist das sogar gut, weil ich die dann ggf. auch als Merkposten länger "mitschleifen" kann, und ihr seht in den svn-diffs auch gleich, wann es ggf. wie gelöst wurde?

Ok, dann in Zukunft nur noch 'Schotty:', also ohne 'ANMERKUNG v.'..

an dich ging die Frage: "Ist es eine gute Idee, den Leser ggf. erst mal in diese 'Falle' laufen zu lassen, um bei der Gelegenheit das Thema 'Anleitungen befolgen' auch gleich zu abzuräumen?".

Hmm, in die 'Falle' laufen zu lassen finde ich nicht so gut, ich könnte mir vorstellen, dass es User gibt, die da erstmal schwer wieder rauskommen... Also wenn es 'klar' ohne 'Falle' geht, dann imho lieber so..

Von daher wäre von deiner Seite (@Schotty) ein (überschlägiger) review von kap03 und kap09 evtl. mal ganz gut (wenn Zeit dafür ist)

kap03 ist schon oben im Anhang, kap09 kommt gleich/heute noch.

[Schotty]

kap09

[Beta-User]

Hab's gesehen, dass das mit dem svn Einchecken geklappt hat!

Grade habe ich noch was nettes gefunden: asciidoctorjs-live-preview - eine Extension für Firefox. Bin geneigt, die Dateien alle umzubenennen, da das bestimmte Dateiendungen braucht: "Render AsciiDoc (.ad, .adoc, .asciidoc) as HTML inside Firefox!"

Irgendwelche Einwände oder Vorlieben?

[Schotty]

Meinst du mich mit dem 'Einchecken hat geklappt'? 

Ich habe vorhin mit https://asciidocfx.com/ gearbeitet, da hat man gleich eine entspr Ansicht inklusive der Grafiken rechts neben dem Editor-Fenster (wenn man bei 'Doctype' oben asciidoc auswählt). Außerdem Icons für die Schriftgestaltung und Buttons, um direkt PDF, epub etc zu generieren - habe ich aber noch nicht getestet.. 

[Beta-User]

Mist, da hat mir meine app einen Streich gespielt...

Aber der Hinweis auf asciidocFX war auch was wert. Das mag aber auch lieber eine passende Dateiendung, wenn ich das auf die Schnelle richtig interpretiert habe...
.adoc?

[Schotty]

Nope, geht wie gesagt auch so, wie es derzeit vorliegt (als als .txt) - man muss nur oben bei 'Doctype' Asciidoc auswählen.

[Beta-User]

...da will die Win-Version nicht mitspielen, was den preview angeht. Ist aber kein Beinbruch, muß ich halt auch noch etwas svn üben...

Da es für alle anderen dann ggf. einfacher ist, das Ergebnis im Browser mit der extension (sowas gibt's u.a. auch für chrome) anzuzeigen, mache ich das bei Gelegenheit.

[Schotty]

Sorry, vergessen: Nach dem Auswählen von "Asciidoc" musst du dann rechts im Preview-Fenster einen Rechtsklick ausführen und 'reload page' auswählen..

[Beta-User]

Puh, überall Neuland, Danke für den Tipp!

wg. svn: Ich puste das bei Gelegenheit rein, kein Stress damit!

Aktueller Plan wäre, dass ich das erst reinschubse, mir dann die vorgeschlagenen Änderungen zur Brust nehme und das dann auch gleich mit dem Preview checke, ob alles optisch paßt und ggf. die Bilder plaziere. Will sagen: Wenn dann ein file als ".ad" im svn erscheint, ist diese Übung durch...

[Schotty]

wg. svn: Ich puste das bei Gelegenheit rein, kein Stress damit!

Gut und schön, aber prinzipiell wäre es ja erstrebenswert, wenn das auch von meiner Seite aus ginge..

[Schotty]

Als Beispiel - in kap02.txt steht:

=== FHEM starten und weitere _basics_

Jetzt kann es also richtig losgehen, du startest jetzt endlich dein "richtiges FHEM". Dazu ziehst du bitte zuerst alle nicht erforderlichen USB-Geräte (vor allem Interfaces!) aus dem Raspberry Pi (auf anderen Systemen ist das nicht erforderlich), wechselst wieder auf die Linux-Kommandozeile und erweckst aus der heraus FHEM mit `sudo service FHEM start` zum Leben - das ist der gegenläufige Befehl zu dem, mit dem wir vorhin das automatisch beim Start des Raspberry (bzw. unmittelbar nach der Installation) ausgeführte FHEM gestoppt hatten.

Da ich gerade folgenden Kommentar von @CoolTux entdeckt habe und nicht weiß, ob/inwiefern das 'wichtig' ist, wollte ich hier nur mal eben kurz drauf hinweisen:

https://forum.fhem.de/index.php/topic,110377.msg1044396.html#msg1044396
Verwende bitte nicht mehr service sondern systemcrl servivename command

[Beta-User]

Als Beispiel - in kap02.txt steht:
Da ich gerade folgenden Kommentar von @CoolTux entdeckt habe und nicht weiß, ob/inwiefern das 'wichtig' ist, wollte ich hier nur mal eben kurz drauf hinweisen:

"Wichtig" ist, dass es so aktuell ist, wie es geht. Wenn es also zukünftig (verläßlich) dieser unschöne neue Command ist, dann ist das halt so (ich bin da lazy und nutze, was ich kenne *grins*). Nur getestet sollte er sein (das kommt in Start- und stop-Varianten mind. noch an einer weiteren Stelle vor; wenn, dann einheitlich!).

[xenos1984]

@xenos1984: das "kontroll-pdf" hatte ich mit a2x erstellt. Das kann aber scheinbar mit den remote-Bildern nicht umgehen (ich habe die manpage noch nicht angesehen, ist evtl. einfach). Das würde mich im Moment jedenfalls von "deiner Seite" am meisten "drücken"... (auch nicht eilig!)

Die letzte Woche war etwas arbeitsreich bei mir, aber jetzt bin ich endlich wieder dazu gekommen, mich um das Projekt zu kümmern

Ja, in der Tat scheint das dblatex, mit dem a2x normalerweise arbeitet, keine als URL eingebundenen Bilder zu verarbeiten. Allerdings gibt es stattdessen auch FOP, und das kann es scheinbar. Ich habe nun diesen Befehl benutzt:

Code Auswählen Erweitern

a2x -a lang=de -f pdf --fop frame.adoc

Das gibt mir ein PDF mit Bildern (auch wenn die noch nicht richtig formatiert sind, aber eins nach dem anderen).

Die .adoc Endung wird seltsamerweise nicht im user Guide benutzt, sondern .txt - aber VIM erkennt .adoc als AsciiDoc, also scheint es wohl doch ein verbreiteter Standard zu sein. Also macht es wohl Sinn, alle Dateien so zu benennen.

[Beta-User]

Kein Ding.

Vielleicht noch ein paar Anmerkungen zu dem, was ich zwischenzeitlich mal ausgetestet hatte:
- Es gibt dieses "Rahmendokument", aus dem raus grade alles rausreferenziert wird. Schaut man das in firefox mit installiertem asciidoctor-preview-plugin an (link), sieht das eigentlich ganz hübsch aus, allerdings: Ohne Bilder, und interne Referenzierungen passen auch nicht bzw. nur beim toc...
- Nimmt man für die "include::"-Anweisungen adoc-Dokumente, gibt es scheinbar nur einen klickbaren Link auf das Teildokument - dafür sind dann aber in diesem dann Bilder zu sehen (Formatierung: im Moment unklar).
Das war der Grund, warum ich das eine erst mal wieder umbenannt hatte. Es könnte aber sein, dass das Problem nur in der Art der Referenzierung liegt (einfacher Doppelpunkt vs. doppelter Doppelpunkt?)

Irgendwie ist das ganze jedenfalls etwas "verheddert" und ich bin unschlüssig, wie wir das am besten angehen. Kann eigentlich nur eine Kleinigkeit sein.

Meine aktuellen Gedanken:
- Super wäre es, wenn es mit dem Rahmendokument klappt. Dann hätten wir einen "live-preview" für das ganze Dokument.
- Macht aber vor allem dann Sinn, wenn wir auch die internen Links bekommen und Bilder angezeigt. Würde also erst mal checken, wie man das aufbauen/referenzieren muß, dass das geht (nächster try wäre Teildokumente aber nur mit einfachem Doppelpunkt?, Dann dasselbe mit adoc-Elementen).
- Wenn nein, sollten es in jedem Fall adoc werden, dann hat man wenigstens den "live-Preview" dieser Teile.

- Was Links angeht, ist und bleibt es schwierig. Da habe ich im Moment noch keine rechte Idee, wie das gehen kann. Vermutlich ist es auch hier so, dass man den Anker und die Quelldatei angeben muß. Wie das aber ggf. dann beim Export nach Wiki oder pdf rauskommt, wäre die Frage...

[xenos1984]

- Es gibt dieses "Rahmendokument", aus dem raus grade alles rausreferenziert wird. Schaut man das in firefox mit installiertem asciidoctor-preview-plugin an (link), sieht das eigentlich ganz hübsch aus, allerdings: Ohne Bilder, und interne Referenzierungen passen auch nicht bzw. nur beim toc...

Kurzer Kommentar / teilweiser Testbericht dazu: Hast du es auch mal mit der lokalen frame.adoc Datei im Firefox versucht? Da scheinen zumindest die Bilder zu funktionieren. Ganz durchgetestet habe ich es aber noch nicht.

[xenos1984]

Inzwischen bin ich etwas weiter:

• Die Form mit den zwei Doppelpunkten bei Links und Bildern steht wohl für ein Block-Element, im Gegensatz zu einem Inline-Element mit nur einem Doppelpunkt. Block-Elemente müssen mit Leerzeilen oder AsciiDoc-Blöcken abgetrennt sein.
• Mit AsciiDoctor in Firefox funktioniert die Live-Vorschau, wenn man das lokale frame.adoc öffnet, mit Bildern und internen Links, und das auch mit eingebundenen *.adoc Dateien.
• Interne Links funktionieren auch zwischen verschiedenen Dokumenten mittels xref: <<anker>> erzeugt einen Link auf [[anker]].
• Manche Attribute von Bildern (wie z.B. align) funktionieren scheinbar nur bei Block-Elementen (zwei Doppelpunkte).
• Die mit FOP erzeugte PDF-Variante wertet scaledwidth="XX%" aus und skaliert Bilder entsprechend; allerdings nicht die HTML-Variante. Letztere wertet dagegen width=XX bzw. height=XX aus. Dieses wird aber ebenfalls von FOP ausgewertet und hat dann scheinbar Vorrang, also wird scaledwidth dann ignoriert. Deshalb sehe ich (noch) keine Möglichkeit, Bilder so zu formatieren, dass es für beides gut aussieht.

Ich habe das ganze einmal ins SVN geladen. Im AsciiDoctor sehe ich allerdings keinen Unterschied, wenn ich die frame.adoc öffne, d.h. ich bekomme die gleiche ausgewertete Seite angezeigt, egal ob die eingebundenen Dokumente .adoc oder .txt sind... Allerdings wird bei mir in beiden Fällen nur das erste Kapitel richtig formatiert, der Rest streikt. Mit der lokalen Datei klappt es dagegen.

[Beta-User]

Danke für's update. Habe jetzt noch nicht intensiver da reingeschaut, aber das mit den Bildern scheint bei mir nur lokal und nur in der Teildatei zu funktionieren.

Wie "weit" der Preview "gut" ist, scheint teils auch von den Formatierungen und Zeilenumbrüchen abzuhängen, denke also, das bekommen wir gefixt.

Ich hoffe, dass ich die kommende Woche etwas Zeit finde, mich wieder intensiver damit zu beschäftigen.

adoc ist auf alle Fälle "richtiger", weil es im Browser (mit Extension) und in asciidocFX gleich ordentlich angezeigt wird - allerdings erzeugt das frame.adoc bei mir unter Linux tatsächlich im Preview nur eine Linkliste.

[xenos1984]

Hm... Vielleicht hängt das mit verschiedenen Versionen zusammen? Ich benutze AsciiDoctor Live Preview 2.3.1 / Firefox 75.0 / Ubuntu 20.04.

[Beta-User]

ff ist hier auch 75.0, 64Bit,
asciidoctor  Version 2.3.1.

Nur @Kubuntu ist @18.04...