java-aktuell / javaaktuell-asciidoc-template

Java aktuell Artikelvorlage im Asciidoc Format

⚠️	Diese Vorlage ist noch im Beta-Stadium! Bevor du sie benutzt, spreche das bitte mit Marcus Fihlon ab. Möglichkeiten zur Kontaktaufnahme: E-Mail: [email protected] Matrix: @mcpringle:matrix.org Mastodon: @[email protected] Vielen Dank!

Informationen für Autoren

• Die eigentliche Vorlage befindet sich in der Datei article.adoc. Alle anderen Dateien kannst du ignorieren.

• Benutze bitte keine Funktionen von Asciidoc, die nicht bereits in der Vorlage gezeigt werden! Vermisst du etwas, erstelle bitte einen Issue auf GitHub oder nehme mit Marcus Fihlon Kontakt auf.

• Wenn du zusammen mit einem oder mehreren anderen Autoren am Artikel arbeitest, so kannst du diese in Zeile 2 mit Semikolon ; getrennt aufführen. Bitte nicht auf mehrere Zeilen verteilen!

• Wenn du möchtest, kannst du für deine Bilder ein eigenes Verzeichnis anlegen. Passe dann das Attribut :imagesdir: entsprechend an. Verwende immer relative Verzeichnisangaben, niemals absolute.

• Vergiss nicht, beim Einreichen alle nötigen Dateien (Bilder, Quelltext, etc.) mitzuschicken. Sende dazu entweder eine ZIP-Datei per E-Mail an Marcus Fihlon (Verschlüsselung per GnuPG möglich) oder verwende ein GitHub-Repository. Ist das GitHub-Repository privat, lade bitte Marcus Fihlon mit entsprechenden Berechtigungen in das GitHub-Repository ein.

Informationen für die Redaktion

Ausgabe-Dateien generieren

Um aus einer Asciidoc-Datei die verschiedenen Ausgabe-Dateien (HTML, PDF, XML, Word) zu generieren, werden die Kommandozeilen-Tools Asciidoctor mit der Erweiterung asciidoctor-lists und Pandoc benötigt. Die entsprechenden Aufrufe befinden sich im Shell-Skript compile.sh. Das Skript konvertiert die Datei article.adoc im aktuellen Verzeichnis. Um die automatisch erzeugten Dateien wieder zu löschen, kann das Skript clean.sh aufgerufen werden.

javaaktuell-asciidoc-template's Issues

Automatische Syntaxprüfung per GitHub Actions

• Enthält das Dokument valides Asciidoc?
• Zwischenüberschriften müssen alle auf der gleichen Ebene sein
• Alle Bilder müssen eine Bildunterschrift haben
• Alle Listings müssen eine Listingunterschrift haben
• Alle Tabellen müssen eine Überschrift haben
• Die Autoreninfo darf 600 Zeichen nicht überschreiten
• Es dürfen keine Admonitions verwendet werden

Wie verweist man auf die automatisch vergebene Nummer eines Listings?

Listings werden augenscheinlich mit einer automatisch vergebenen Nummer beziffert. Ist es möglich, auf diese automatisch vergebene Nummer Bezug zu nehmen?

PDF zeigt erste Zeile des Abstract in Fettdruck, zweite Zeile aber nicht

Wenn man einen mehrzeiligen Abstract verwendet, erscheint dessen erste Zeile im PDF in Fettdruck, während seine Folgezeilen nicht fettgedruckt sind.

Verweise gehen bei Word-Konvertierung verloren

Hi @McPringle ,

erstmal auf diesem Wege nochmal Danke für die Vorlage, es schreibt sich in asciidoc einfach besser. Allerdings bin im Rahmen meines Artikels auf zwei Probleme beim weg adoc -> docbook -> word gestoßen.

1. Die Caption Title (Listing etc) werden nicht übernommen und der xrefstyle wird nicht beachtet
2. Verweise auf Listings funktionieren nicht.

Ich bin auf folgende upstream issues gestoßen:

• jgm/pandoc#8666
• asciidoctor/asciidoctor#3736

Das sieht dann in Word leider so aus jeweils. Das ist kein Beinbruch aber braucht ein wenig manuelle Nacharbeit in Word. Vermutlich können wir hier aber nicht direkt was machen sondern müssen auf upstream warten.

Admonitions gehen bei Word-Konvertierung verloren