Dieses Dokument führt Sie auf direktem Weg, möglichst einfach in die Arbeit mit adoc Studio ein. Sie erfahren, wie die App aufgebaut ist, lernen die wichtigsten Befehle kennen und erhalten viele Hinweise, wo Sie tiefer in die Dokumentation mit adoc Studio einsteigen können. Zusätzlich gibt Ihnen der Quelltext dieser Dokumentation ein Beispiel für den Aufbau eines Projekts in adoc Studio. Rufen Sie es im Hauptmenü über Hilfe  Benutzerhandbuch auf.

Diese Dokumentation basiert auf der Beta-Version von adoc Studio. Bitte informieren Sie uns im Forum über auftretende Fehler und Probleme.

Notation in dieser Dokument

Sie finden im Text einige Hinweise, die Ihnen eine besondere Hilfe geben.

Ergänzende Anmerkungen werden als Notiz dargestellt.
Wann immer sich die Chance für einen besonderen Hinweis ergibt, erhalten Sie einen Tipp.
Die Glocke erscheint, um Sie auf Besonderheiten hinzuweisen.
Wann immer Sie vor einer Aktion besondere Aufmerksamkeit walten lassen müssen erscheint dieser Hinweis zur Vorsicht.
Achtung, hier versuchen wir Sie auf bestehende Gefahren, Schäden oder Konsequenzen hinzuweisen.

Menübefehle erkennen Sie an der Struktur des Menüs: Ablage  Export  Produkte…. Sollte es eine Tastaturabkürzung geben, erkennen Sie die an dieser Darstellung ++E.

1. Rechtliche Hinweise

Bitte beachten Sie, dass Betriebsanleitungen, Handbücher und Software urheberrechtlich geschützt sind. Das Kopieren, Vervielfältigen, Übersetzen oder Umsetzen in irgendein elektronisches Medium oder maschinell lesbare Form im Ganzen oder in Teilen ohne vorherige schriftliche Genehmigung von ProjectWizards ist nicht gestattet. Alle weiteren Rechte an der Software sind in den mitgelieferten Lizenzbestimmungen festgelegt. Die Rechte an anderen in diesem Handbuch erwähnten Marken und Produktnamen liegen bei ihren Inhabern und werden hiermit anerkannt. Die Nennung von Produkten, die nicht von ProjectWizards sind, dient ausschließlich Informationszwecken und stellt keine Werbung dar. ProjectWizards übernimmt hinsichtlich der Auswahl, Leistung oder Verwendbarkeit dieser Produkte keine Gewähr.

adocstudio

2. Was ist adoc Studio?

Wir sprechen bei adoc Studio von einer integrierten Schreibumgebung, die auf Basis der Auszeichnungssprache AsciiDoc, Dokumente im HTML, PDF erzeugt (später kommen weitere Formate wie ePub hinzu). So haben wir schon einige Begriffe, die erläutert werden wollen, weil sie mögliche Weise nicht jedem bekannt sind.

Auszeichnungssprache

Wohl jeder kennt Microsoft Word oder einen anderen WYSIWYG-Editor. Als Kontrast dazu haben sich in den letzten Jahren einige Auszeichnungssprachen, wie zum Beispiel Markdown, stark verbreitet. Diese zeigen nicht mehr (wie MS Word oder Pages von Apple) das Ergebnis in einer Druckähnlichen Vorschau an, sondern müssen übersetzt werden – mal mit mehr, mal mit weniger Aufwand.

AsciiDoc

Die Basis für adoc Studio ist AsciiDoc, die als einer der älteren Vertreter der Auszeichnungssprachen gilt. Nicht zuletzt ist die Tatsache, dass die Eclipse-Foundation den Sprachumfang von AsciiDoc standardisieren will, ist für Sie ein Garant für eine zukunftssichere Entscheidung. Wir haben uns aber vor allem für AsciiDoc entschieden, weil es für den Einsteiger sehr leicht zu lernen ist und dem Profi gleichzeitig einen umfangreichen Befehlsumfang gibt.

Integrierte Schreibumgebung

Damit alles einfach bedient werden kann, braucht man ein Programm, in dem alle notwendigen Funktionen enthalten sind. Hier geben Sie Texte ein, organisieren diese in Projekten, nutzen die Vorschau für einen ersten Überblick und exportieren schließlich die Dokumente einzeln, oder als fertige Produkte.

Natürlich kann adoc Studio als integrierte Schreibumgebung nach Ihren Wünschen eingestellt werden. Sie bestimmen das Aussehen des Editors und wählen einen Ausgabe-Stil. Wir liefern einige Stile mit und veröffentlichen regelmäßig weitere auf unserer Webseite.

In adoc Studio konzentrieren Sie sich ausschließlich auf die Struktur und die Inhalte in Ihrem Dokument. Natürlich werden Sie starke Aussagen treffen und hervorheben, was einer besondere Betonung bedarf. Und Emojis gibt es in unserer App selbstverständlich auch 😀

2.1. Was ist eine Auszeichnungssprache?

Historisch kommt der Begriff Auszeichnung aus der Typographie. Die Drucker – also die Menschen des druckenden Handwerks – meinten mit dem Begriff das Hervorheben von Textteilen z. B. durch von der Grundschrift abweichende Schriftvarianten, wie kursive und fette Schriftschnitte oder Kapitälchen, durch Versalien (Großbuchstaben), durch Sperren, Unterstreichen oder Einfärben des Textes, aber auch durch andere Schriftgrößen und -arten. Auch (handschriftliches) Kenntlich machen entsprechender Stellen im zugehörigen Manuskript gehört dazu (aus Wikipedia). Und das wurde sinngemäß in die Computerzeit und Software übernommen. Und da ist unsere Auszeichnungssprache.

Sie haben vielleicht schon von der Sprache Markdown oder einen Satz wie „der Text ist in Markdown geschrieben" gehört. Sie sind damit auf dem richtigen Weg. Zum einen haben wir reinen Text – also Buchstaben ohne Formatierung. Und zum anderen haben wir Markierungen, die den Text besonders auszeichnen: was eine Überschrift ist, was fett, kursiv oder ein Link ist und so weiter.

Es gibt viele Auszeichnungssprachen, nicht zu verwechseln mit Textverarbeitungen wie MS Word. Die drei bekanntesten Vertreter von Auszeichnungssprachen sind:

  • HTML, die Sprache des Internets, aber auch sehr geschwätzig.

  • TeX oder LaTeX, wohl das populärste Satzsystem für wissenschaftliche Artikel, aber im Geschäftsleben eher selten und schwer zu erlernen.

  • Markdown, sehr einfach – zu simpel, es mangelt an vielen Funktionen für technische Dokumentation. Hier ist ein detaillierter Vergleich von Markdown und AsciiDoc.

Aufgrund der Nachteile der oben aufgeführten Sprachen haben wir uns für AsciiDoc als Auszeichnungssprache entschieden. Bei ProjectWizards schreiben wir seit 2007 alle Handbücher und öffentlichen Dokumente in diesem Format.

AsciiDoc ist eine ausgereifte, leichtgewichtige und semantische Auszeichnungssprache, die Natürlich kann sie für alle strukturierten Texte ideal eingesetzt werden. hauptsächlich zum Erstellen technischer Dokumentation entwickelt wurde. Und mal ehrlich, bei über 10 Millionen Downloads (Quelle: Asciidoctor History) gibt es immer jemanden, der helfen kann. Diese Ehre gebührt selbstverständlich Asciidoctor, dem ersten Parser von AsciiDoc-Texten.

2.2. Und was ist mit Word, Pages oder Google Docs?

Es gibt viele Gründe, warum man sich für adoc Studio anstelle von WYSIWYG-Textverarbeitungen wie Microsoft Word, Apple Pages oder Google Docs entscheiden sollte:

Die Abkürzung ist seit den 90ern in vieler Munde: WYSIWYG – oder in langer Form: „What you see is what you get“. Das beschreibt die Ausgabe der Dokumente, die so erfolgen soll, wie sie am Bildschirm dargestellt ist. Also; Was du sieht ist das, was du bekommst.
  1. Trennung von Inhalt und Darstellung: Textbasierte Markup-Sprachen ermöglichen es, Inhalt und Darstellung zu trennen. Dies ermöglicht eine konsistente Formatierung über verschiedene Dokumente hinweg und macht es einfacher, das Aussehen von Dokumenten auf einmal zu ändern. Ein Dokument, das in einer Markup-Sprache geschrieben ist, kann auf jedem Computer ohne spezielle Software geöffnet werden.

  2. Portabilität: Textbasierte Markup-Sprachen sind universell und plattformübergreifend. Sie können auf jedem Gerät und Betriebssystem geöffnet und bearbeitet werden. Word-Dateien können auf verschiedenen Computern schon sehr unterschiedlich aussehen.

  3. Versionskontrolle: Markup-Sprachen sind mit Versionskontrollsystemen wie Git kompatibel, was die Zusammenarbeit und Nachverfolgung von Änderungen in großen Dokumenten erleichtert. Auch wenn Word mittlerweile ein XML-Format eingeführt hat, weigern sich noch viele Administratoren, diese Dateien in ein Git einchecken zu lassen.

  4. Wiederverwendbarkeit: Sie können ein Dokument in einer Markup-Sprache erstellen und es dann in verschiedene Formate konvertieren, z.B. HTML für eine Website, PDF für den Druck, EPUB für E-Books usw. In Word sind die Ergebnisse oft sehr überraschend.

  5. Anpassungsfähigkeit: Textbasierte Markup-Sprachen ermöglichen eine sehr hohe Anpassungsfähigkeit. Sie können das Aussehen und Verhalten Ihrer Dokumente auf eine Art und Weise anpassen, die in Standard-Textverarbeitungsprogrammen oft nicht möglich ist.

  6. Automatisierung: Sie können automatisierte Skripte und Tools verwenden, um Dokumente in textbasierten Markup-Sprachen zu generieren, zu verarbeiten und zu manipulieren. Dies kann bei großen Dokumenten Zeit sparen und Fehler reduzieren.

  7. Stabilität und Beständigkeit: Textbasierte Markup-Sprachen sind in der Regel stabil und beständig, im Gegensatz zu proprietären Dateiformaten, die sich mit der Zeit ändern können.

2.3. Installation

Die Beta-Version von adoc Studio wird ausschließlich via TestFlight verteilt. Gehen Sie auf unsere Webseite und laden dort kostenlos die aktuelle TestFlight-Version.

Systemanforderungen

Die minimalen Systemanforderungen für adoc Studio sind:

  • Auf dem Mac: macOS 13 (Ventura)

  • Auf dem iPad: iPadOS 16

  • Auf dem iPhone: iOS 16

3. adoc Studio kennenlernen

In diesem Kapitel entdecken Sie die App und die Konzepte, die Ihnen die Bedienung erleichtern.

3.1. Die Benutzeroberfläche

Nach dem Start von adoc Studio sehen Sie in etwa ein solches Bild. Wir haben hier das Benutzerhandbuch – das selbstverständlich mit adoc Studio erstellt wurde – aus dem Hilfe-Menü aufgerufen.

100%

Das Fenster-Layout in adoc Studio ist dreigeteilt:

Am oberen Fensterrand gibt es natürlich die obligatorische Symbolleiste mit diesen Funktionen:

  • Die Seitenleiste ein- & ausblenden (Tastaturkürzel: +0)

  • Eine neue Komponente anlegen (oder per: ++N)

  • Die Zurück- & Vorwärts-Button für die Navigation (auch via ++< und ++>)

  • Der Verzeichnisbaum als Popup-Liste

  • Die Inhaltsstruktur als Popup-Liste

  • Optional, eine Liste aller Produkte

  • Den Editor ein- & ausblenden (mit pencil oder ++E)

  • Die Vorschau ein- & ausblenden – (mit eye oder ++E) inkl. der Einstellungenn

Jeder Bereich kann einzeln ein- und ausgeblendet werden, so dass für jede Bildschirmgröße ein perfektes Setup gefunden werden kann. Hierzu finden Sie in den Menüs Darstellung, Editor und Vorschau die entsprechenden Funktionen.

3.2. Der Projektnavigator

In adoc Studio arbeiten Sie projektorientiert, aber was heißt das? Im einfachsten Fall ist das Ihr Text und – sofern verwendet – auch die Bilder im Text. Aber je länger ein Text wird, um so problematischer wird der Überblick. Daher teilt man einen Text gerne in kleinere Texte auf. Diese liegen dann in vielen einzelnen Dateien, bunt gemischt mit den Bildern. Das endet unweigerlich im Chaos; denn der Überblick geht natürlich irgendwann verloren. Damit Ihnen das nicht passiert, bieten wir in adoc Studio das Sammeldokument an.

Dieses Kapitel behandelt den Umgang mit Projekten, Dateien und allem was dazugehört.

Ein neues Projekt anlegen

Erstellen Sie in adoc Studio ein neues Projekt (über das Menü Ablage  Neu  Projekt), finden Sie in der Seitenleiste zunächst zwei Objekte:

new project
  • einen Ordner für Medien

  • eine Datei für das Dokument

Ob die Dateiendung .adoc wie im Bild rechts dargestellt wird, entscheiden Sie in den Einstellungen im Menü adoc Studio (+,).

Natürlich können alle Objekte (Dateien & Ordner) in der Seitenleiste bewegt werden. Sie können ineinander verschachtelt, oder auch wieder neu strukturiert und angeordnet werden.

Medien und Bilder können an jeder Position im Projekt abgelegt werden. Wir empfehlen sie im Medienordnern zu sammeln. Falls der automatisch angelegte Medienordner nicht ausreicht, können Sie beliebig viele in Ihrem Projekt erstellen.

Alleinstehende Dokumente

new project 2

Im nächsten Schritt erweitern wir unser Projekt und fügen ein alleinstehendes Dokument hinzu. Sie nutzen das Menü Ablage  Neu, +N oder den + Button oben, in der Seitenleiste. Beides sind voneinander unabhängige Dokumente, die nur für sich selber existieren. Der Ablauf ist so einfach wie logisch:

  1. Sie klicken auf ein Dokument,

  2. Das wird im Editor zur Bearbeitung dargestellt

  3. In der Vorschau sehen Sie den stets aktuellen Stand

Klicken Sie auf ein anderes Dokument, wird dieses im Editor dargestellt usw.

Das heißt Sie sehen die Inhalte von zweiten Dokument mehr.adoc nicht in Dokument.adoc. Natürlich gibt es in AsciiDoc Techniken, um Inhalte in anderen Dokumenten anzuzeigen; die Includes. Aber dazu kommen wir später.

Sammeldokumente

Sammeldokumente stehen im Kontrast zu den alleinstehenden Dokumenten. Der Begriff beschreibt es; Sie sammeln ihre Dokumente zu einem großen Dokument. Demzufolge heißen die neu angelegten Dateien in einem Sammeldokument nicht mehr Dokument.adoc sondern Kapitel.adoc.

In einem Sammeldokument können Sie ebenfalls Ordner für die Strukturierung verwenden, auch wieder beliebig tief. Klicken Sie aber nun auf einen Ordner, werden alle darunter enthaltenen Kapitel zusammenhängend in der Vorschau angezeigt. Je weiter Sie in der Hierarchie nach oben gehen, werden die dargestellten Inhalte in der Vorschau umfangreicher. Da der Fokus in der Seitenleiste nun auf einem Ordner steht, kann im Editor nichts dargestellt werden. Um ein Kapitel zu bearbeiten, wählen Sie das entsprechende gezielt aus. Dann wechselt die Vorschau auch sofort wieder zu der Darstellung des Textes im Editor.

Ordner für die Struktur

Wenn Sie nach und nach neue, unabhängige Dateien anlegen, ist irgendwann die Seitenleiste voll. Natürlich können Sie zum schnellen Auffinden einer Datei den Filter am unteren Ende der Seitenleiste nutzen. Aber der ist nur temporär und nach dem Neustart von adoc Studio wieder leer.

Daher kommt jetzt das nächste Strukturinstrument zum Einsatz; der Ordner. Wie im Betriebssystem können Sie in adoc Studio Ordner anlegen. Den benennen Sie nach den Regeln im Betriebssystem. In einem Ordner können Sie viele Dokumente ablegen. Natürlich Sie können auch Ordner in anderen Ordnern anlegen.

Das Konzept der einzelnen Dokumente bleibt aber. Auch wenn Sie viele Ordner angelegt und darin viele Dateien abgelegt haben, sind alle voneinander getrennt. Ist das so gewünscht, sind Sie hier fertig. Falls Sie aber ein Buch mit vielen Kapiteln schreiben, brauchen Sie ein anderes Dokument; das Sammeldokument.

Medienordner

Der Medien-Ordner hat eine besondere Aufgabe. Hier können Sie im Standard alle Medien (Bilder, Videos etc.) ablegen. adoc Studio sucht im Projekt nach einer festgelegten Reihenfolge nach den Medien.

Suchreihenfolge für Bilder

Die Zeile images::bild.jpg[]

  1. sucht die Datei bild.jpg zuerst in der gleichen Ebene, wo auch die .adoc-Datei liegt.

  2. Danach geht die App eine Ebene höher und sucht hier das Bild.

  3. Wird es nicht gefunden, werden die Medien-Ordner von oben nach unten durchsucht.

  4. Wird immer noch kein Bild gefunden, markiert der Editor den Dateiname rot und im Problemnavigator der Seitenleiste ein Eintrag hinzugefügt.

error image
Bilder mit Pfadangaben
  • Die Zeile images::/bild.jpg[] sucht das Bild im Projektverzeichnis (wo die .adocproject liegt).

  • Die Zeile images::/Ordner/bild.jpg[] sucht das Bild im Unterverzeichnis Ordner, ausgehend vom Projektverzeichnis.

  • Die Zeile images::../bild.jpg[] sucht das Bild eine Ebene über der Textdatei, in der es angesprochen wird.

Im Grunde lassen sich alle Pfade wie im Betriebssystem angeben. Die Wurzel ist dabei immer das Projektverzeichnis, dort wo Ihre .adocproject liegt.

Für die AsciiDoc-Profis: Das Konzept von imagesdir gibt es auch in adoc Studio. Wenn Sie in bestehenden (externen) Projekten das Attribut verwenden, steht das intern immer vor den Bildern und evtl. Pfadangaben. Es wird aber nicht automatisch gesetzt!

So wird dann:

image::Ordner/bild.jpg[]

zu

image::{imagesdir}/Ordner/bild.jpg[]

Hierzu gibt es natürlich noch viele Details auf der AsciiDoc-Webseite.

Sie können viele Medien-Ordner haben. Hier ein paar Beispiele:

  • Ein Ordner mit generellen Bildern

  • Ein Ordner mit Bildern einer speziellen Sprache

  • Ein Ordner mit Bildern einer speziellen Plattform

In diesem Projekt haben wir zum Beispiel die Bilder für das iPad in einem eigenen Medienordner abgelegt und den Aufruf über das Attribut iPad in den Produkten gesteuert.

Bei externen Projekten gibt es noch einige Besonderheiten mehr. Die Details dazu finden Sie dort.

Neue Komponente einfügen

neu componente

Über den plus Button in der Symbolleiste oder dem Tastenkürzel ++N fügen Sie eine neue Komponente in Ihr Projekt ein. Der Dialog reagiert dabei ausgehend von der Selektion in der Dateiliste unterschiedlich:

  • Ist ein alleinstehendes Dokument ausgewählt, können Sie ein neues alleinstehendes Dokument oder ein Sammeldokument anlegen.

  • Ist ein Sammeldokument oder ein Kapitel davon selektiert, können Sie neue Kapitel anlegen.

In jedem Fall können Sie neue Ordner, Medienordner oder auch bestehende Dateien einfügen.

Ziehen Sie bestehende Dateien auch einfach aus dem Finder in die Dateiliste, um sie in Ihr Projekt einzufügen.

Bestehende Dateien einfügen

In adoc Studio gibt es aber nicht nur Sammeldokumente mit ihren Kapiteln, sondern auch alleinstehende Dokumente.

Ein alleinstehendes Dokument übernimmt keine Attribute aus anderen Dokumenten in der Dateiliste. Sie müssen in diesen Dokumenten alle Werte explizit setzen. Auch die Medien-Ordner, die sich in Sammeldokumenten befinden, werden nicht von einem alleinstehenden Dokument gefunden; nur die Medien-Ordner, die ausserhalb von Sammeldokumenten liegen, werden gefunden.

Nun ist es Ihrer Kreativität überlassen, wie Sie diese in Ihr Projekt einfügen. Hier die Möglichkeiten.

Doppelklick im Finder

Jede .adoc-Datei kann im Finder doppelt angeklickt werden. Sollte sich nicht ein anderes Programm nach der Installation für die Dateiendung .adoc registriert haben, nimmt sich adoc Studio dieser Dateien an. Es erscheint der unten dargestellte Dialog, in dem Sie das Zielprojekt für die Datei auswählen, oder ein neues Projekt anlegen. Diese Datei wird dann in das gewählte Projekt kopiert – nicht verschoben!

NeuesDokument
Drag & Drop aus dem Finder

Ein weiterer Weg, Dateien in ein Projekt zu kopieren, ist das bekannte Drag & Drop. Ziehen Sie die gewünschte Datei direkt an die gewünschte Position. adoc Studio macht sie automatisch zu einem Bestandteil eines Sammeldokuments, falls das Ziel ein solches ist.

Dateioperationen direkt im Finder

Natürlich können Dateien auch direkt im Finder in das Projektverzeichnis kopiert oder verschoben werden. adoc Studio erkennt sie automatisch und nach einem kurzen Moment scheint sie direkt in der Dateiliste in Ihrem Projekt. Die App nicht neu gestartet werden.

Menüfunktion

Schlussendlich gibt es auch eine Menüfunktion, um Dateien in Ihre Projekte einzufügen. Mit Ablage  Neu  Dateien hinzufügen … oder dem Shortcut ++A öffnen Sie die Dateiauswahl. Die ausgewählte(n) Datei(en) werden unterhalb der Selektion in der Dateiliste eingefügt. Sie können diese danach mit der Maus auch an einen anderen Ort verschieben.

Wenn Sie eine Datei in ein Sammeldokument ziehen, wird diese automatisch zu einem Kapitel des entsprechenden Sammeldokuments.

Datei-Informationen

Manchmal soll eine Datei in einem Sammeldokument liegen, aber nicht ausgeben werden. Dafür haben wir eine elegante Lösung:

file inspector

Mit einem Rechtsklick auf die Datei im Dateiverzeichnis der linke Seitenleiste rufen Sie das Kontextmenü auf. Hier findet sich der Eintrag Informationen …, der den rechts dargestellten Dialog aufruft.

Sie deaktivieren Sie einfach den Schalter Teil des Sammeldokuments und schon wird die Datei nicht mehr eingebunden. Wenn sie dann trotzdem verwendet werden soll, muss sie via include-Befehl eingebunden werden.

Weitere Informationen

Die meisten Dateien und alle Ordner in der Seitenleiste können über die Informationen … modifiziert werden. Neben der Umbenennung einer Datei oder eines Ordners gibt es folgende Möglichkeiten.

  • Für Dateien:

    • Teil eines Sammeldokuments

  • Für Ordner:

    • Sammeldokument

    • Medienverzeichnis

    • Ordner

3.3. Ein Projekt sichern

saveProject
Der traditionelle Weg

Früher war es immer eine gute Idee, ein neues Projekt im ersten Schritt zu sichern. Sie legen aktiv den Ort fest, an dem das Projekt angelegt wird. Das erfolgt über das Ablage  Sichern … oder dem Tastenkürzel +S.

Es bleibt dabei Ihnen überlassen, ob Sie die Dateien von adoc Studio auf Ihrem lokalen Rechner sichern oder sie auf einen Server oder einen Cloud-Speicher legen. Auch der Einsatz eines Versionskontrollsystems, wie zum Beispiel Git oder Github, ist möglich.

Der neue Weg

Aber auch ohne initiales Sichern müssen Sie keine Angst vor Datenverlust haben. Sollten Sie das letzte Projektfenster schließen, fragt Sie adoc Studio ob das Projekt gesichert werden soll. Sie können entscheiden nun ob und wo das Projekt abgelegt wird.

Auch wenn es zuerst ungewohnt ist; in adoc Studio müssen Sie sich nicht mehr über das regelmäßige Sichern der .adoc-Dateien kümmern. Das übernimmt die App für Sie in sehr kurzen Abständen. Für das gute Gefühl können Sie natürlich stets den gewohnten Shortcut +S drücken. Aber seinen Sie versichert, der Computer war schneller.

3.4. Weitere Fenster für ein Projekt

Ein Projekt kann – mittels dem Menü Fenster  Neues Fenster – in mehreren Fenstern geöffnet werden. Das ist insbesondere im Zwei-Monitor-Betrieb sehr hilfreich, falls Sie die Vorschau in einem eigenen Fenster sehen möchten.

Klicken Sie auf Ihrem Mac mit der Maus bei gedrückter - Taste auf den Fenstertitel, erhalten Sie ein Menü mit dem Pfad des aktuellen Projekts im Finder.

4. Externe Projekte

Die externen Projekte sind noch nicht beschrieben. Wir arbeiten daran, das sobald wie möglich nachzuholen.

Der zweite Tab in der Seitenleiste stellt die Struktur der Überschriften als Gliederung dar.

Für Sammeldokumente wird stets das gesamte Inhaltsverzeichnis ausgegeben, gleich in welchem Kapitel Sie zur Zeit arbeiten.

Bei alleinstehenden Dokumenten erscheint nur das eigene Inhaltsverzeichnis.

Möchten Sie im Text ein Inhaltsverzeichnis ausgeben, nutzen Sie das Attribut :toc:, was hier beschrieben wird.
search context menu

Um Texte im gesamten Projekt zu finden, nutzen Sie den dritten Tab der Seitenleiste, den Such-Navigator.

Im Kontextmenü hinter der Lupe schalten Sie das Ersetzen dazu. Möchten Sie nicht nach

  • Groß-/Kleinschreibung oder

  • Akzente/Umlaute

unterscheiden, finden Sie Schalter hier ebenfalls. Die Treffer werden gruppiert nach den Dateien im Projekt zusammengefasst.

Besonderheiten

Wenn Sie gefundenen Text auch ersetzen wollen, bietet adoc Studio einige praktische Ergänzungen:

  • Selektieren Sie einzelne Treffer in der Liste (eine Mehrfachauswahl per -Taste ist möglich), werden die Ersetzungen nur für die selektierten Stellen vorgenommen.

  • Selektieren Sie eine Datei in der Trefferliste, werden die Ersetzungen nur in dieser Datei vorgenommen.

Das Konzept für AsciiDoc und auch adoc Studio ist es, stets einen Text auszugeben. Unabhängig davon, ob und wie viele AsciiDoc-Fehler sich im Text befinden. Es geht hier also nicht um die grammatikalischen und orthographischen Fehler.

Sollte ein Problem mit einem AsciiDoc-Befehl im Text auftreten, erscheint das Symbol der Fehlerliste in roter Farbe: errorlist

Da nicht jeder Fehler gleich gewichtig ist, werden kleinere Probleme, also Warnungen in gelb dargestellt.

Die Liste selbst ist nach dem Auftreten sortiert. Klicken Sie auf eine Meldung springt der Editor an die entsprechende Stelle, so dass Sie den Fehler beheben können.

4.4. Text schreiben und darin navigieren

Wählen Sie nun in der Dateiliste eine Textdatei aus. Sollte anschließend der Cursor nicht im Editor-Fenster blinken; mit einem beherzten Mausklick in den mittleren Bereich des Fensters (oder einmal +TAB) setzten Sie den Cursor und schon geht es los: Sie schreiben Ihren Text. Hinweise zu AsciiDoc erhalten Sie im nächsten Kapitel.

Der eingegebene Text erscheint sofort in der Vorschau. Bei längeren Texten wird sogar die Positionen der beiden Fenster synchronisiert. Das heißt, Sie sehen rechts immer in der Vorschau den links geschriebenen Text auf der gleichen Höhe. Genauer gesagt wird die Position der Schreibmarke mit der mit der Position in der Vorschau synchronisiert.

Auch wenn der Reiz, die Vorschau auf PDF umzuschalten groß ist: Bei langen Texten empfehlen wir bei HTML als Vorschau zu bleiben. Da ein PDF-Dokument immer komplett gesetzt werden muss, wird das in der Praxis bei großen Dokumenten schnell sehr zäh. Die Vorschau in HTML kann dagegen schrittweise aktualisiert werden, was deutlich schneller ist.

Der Editor selbst kann nach Ihren persönlichen Vorlieben (Farbempfinden, Dioptrienstärke etc.) eingestellt werden. Der Tab EEditorstile in den Programmeinstellungen bietet Ihnen fast endlose Möglichkeiten der Gestaltung.

Zusatznavigation

Über dem Editor finden Sie ein besonderes Bedienungselement: Die Zusatznavigation.

Diese beginnt mit den Navigationspfeilen nach links arrow left und rechts arrow right . Die Funktion ist – wie bei Ihrem Browser – die Navigationen; also vor und zurück.

Danach folgt ein grafischer Block:

zusatz navigation

Dieses Element ist ganz besonders auf kleinen Bildschirmen Gold wert – aber nicht nur dort. Von links nach rechts gelesen, erkennen Sie, wo sich die Datei befindet, in der Sie gerade schreiben. Ganz rechts haben Sie ein kleines Inhaltsverzeichnis der Struktur, die aber auch den Gesamtkontext zeigt. Und darüber hinaus können Sie mit jedem Element zu jeder beliebigen Datei springen.

Zeilennummern

Am rechten Rand des Editors erscheint eine einzelne Zeilennummer zur persönlichen Orientierung. Falls Sie nicht mit anderen über eine Textposition kommunizieren müssen, reicht das in den meisten Fällen aus. Bevorzugen Sie die Anzeige aller Zeilennummern, stellen Sie das in den Einstellungen ein.

Ein Klick auf eine Zeilennummer (oder +L) gibt Ihnen die Möglichkeit zu einer bestimmten Zeile zu springen.
Auch Texte werden sofort gesichert

So wie die Projektdateien, werden auch die Änderungen in den Texten umgehend gesichert. So müssen Sie auch hier keine Sorgen vor Datenverlust haben!

Den Cursor bewegen

Natürlich wollen wir beim Schreiben nicht so oft die Hand von der Tastatur nehmen, um den Cursor mit der Maus zu positionieren. Daher haben wir die bekannten Shortcuts (um mal das englische Wort zu nutzen) der Textbearbeitung vom macOS und iPadOS übernommen und bieten sie genau so in adoc Studio an.

Tabelle 1. Verwendete Modifizierungstasten

Command- oder Befehl-Taste

Option- oder Wahl-Taste

Control- oder Kontroll-Taste

Shift- oder Umschalt-Taste

Enter-Taste

Return-Taste

Backspace- oder Lösch-Taste

Vorwärts-Lösch-Taste (nur auf der erweiterten Tastatur)

Tabelle 2. Bewegung im Dokument

Ein Zeichen nach links

Ein Zeichen nach rechts

Eine Zeile nach oben

Eine Zeile nach unten

+

Ein Wort nach links

+

Ein Wort nach rechts

+

Zum Anfang der Zeile

+A

Zum Anfang der Zeile

+

Zum Ende der Zeile

+E

Zum Ende der Zeile

+

Zum Anfang des Dokument

+

Zum Ende des Dokuments

Tabelle 3. Selektionen im Dokument

+

Selektion nach links erweitern

+

Selektion nach rechts erweitern

+

Selektion nach links erweitern

+

Selektion nach rechts erweitern

++

Selektion zum Wort nach links erweitern

++

Selektion zum Wort nach rechts erweitern

++

Selektion zum Anfang des Dokuments erweitern

++

Selektion zum Ende des Dokuments erweitern

Tabelle 4. Im Dokument löschen

+K

Löscht die aktuelle Zeile rechts vom Cursor

+

Löscht die aktuelle Zeile links vom Cursor

+

Löscht das Wort links vom Cursor

+

Löscht das Wort links vom Cursor

Aber es gibt in adoc Studio noch einen weiteren Shortcut, den Sie regelmäßig verwenden möchten: die ESC - Taste. Und damit betreten wir den großen Bereich der Eingabehilfen.

4.5. Eingabehilfen

Die Sprachumfang von AsciiDoc ist sehr umfangreich. Daher kann es selbst Profis passieren, dass der eine oder andere Befehl vergessen wurde, ein Makro unerkannt bleibt. Oder man erinnert sich schlicht weg nicht mehr an eine bestimmte Syntax. Darum ist in adoc Studio eine intelligente Eingabehilfe eingebaut.

Während Sie schreiben, schaut die App immer nach Möglichkeiten, Ihnen zu helfen. Oft erkennt sie nach dem zweiten oder dritten Zeichen verschiedenen Möglichkeiten und bietet diese in einem Vervollständigungsmenü an. Dabei achten versucht adoc Studio aber, Ihren Schreibfluss so wenig wie möglich zu stören.

Wenn benötigt, können Sie das Menü mit den Eingabehilfen jederzeit über die ESC-Taste aufrufen.

completion images

So binden Sie ein Bild im Text ein

  1. Sie tippen am Zeilenanfang: ima

  2. Es erscheint ein kurzes Menü:

    completion image

  3. Mit den Tasten oder navigieren Sie in der Liste

  4. Mit der wählen Sie den gewünschten Eintrag aus (hier: ob es ein Bild als Block oder in der Textzeile werden soll).

  5. Nach der Auswahl erscheint gleich ein weiteres Menü:

    completion image adoc

    Praktischerweise werden die Bilder gleich als kleine Vorschau dargestellt.

  6. Und es geht weiter. Nach Auswahl des passenden Bildes mit der -Taste erscheint das Bild in der Vorschau in voller Breite.

  7. Setzen Sie den Cursor zwischen die beiden eckigen Klammern nach dem Bildnamen ([]) um die passenden Optionen für das Bild einzugeben.

  8. Als erstes möchten wir die Breite des Bildes korrigieren, also tippen Sie: wi und spätestens jetzt erscheint wieder das Menü. Nun sind alle verfügbaren Optionen für Bilder aufgelistet, die mit wi enthalten.

  9. Sie wandern mit den Cursortasten zu width= und betätigen wieder die Taste.

  10. Jetzt sehen Sie folgendes: completion image placeholder

  11. Überschreiben Sie den Platzhaltertext mit einer Zahl (z. B. 200), sehen Sie in der Vorschau sofort die Skalierung des Bildes.

  12. Setzen Sie den Cursor nun erneut zwischen die beiden eckigen Klammern nach dem Bildnamen ([]) – es spielt keine Rolle ob vor der Option width oder danach. Wichtig ist, dass alle Optionen durch ein Komma getrennt werden.

  13. Nun betätigen Sie die ESC-Taste damit das Vervollständigungsmenü mit den weiteren Optionen für das Bild erscheint. Angenommen wir möchten das Bild rechts neben einen Text platzieren.

  14. Dazu brauchen wir die Option float. Also beginnen Sie zu schreiben: flo und das Vervollständigungsmenü schrumpft auf die Begriffe zusammen, in denen flo vorkommt: completion image float

  15. Sie wählen nun float=right.

Schon haben wir ein Bild eingefügt, es wird skaliert und rechts neben dem Text positioniert. Gratulation! Hier ist der entstandene Text (inkl. etwas „lorem ipsum“ Platzhaltertext):

image::adocstudio.png[width=200, float=right]

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Und hier das Ergebnis:

completion image example
So wie in dem Beispiel ein Bild (also image::) verwendet wurde, steht Ihnen für jeden AsciiDoc-Befehl und alle Attribute das Vervollständigungsmenü zur Seite. Im Zweifel hilft einfach ein beherzter Druck auf die ESC-Taste.

5. Programmeinstellungen

In adoc Studio können viele Bereiche individuell einstellt werden.

5.1. Allgemein

Über das Hauptmenü adoc Studio  Einstellungen … oder das Tastenkürzel +, öffnen Sie das Fenster mit den Einstellungen.

Hier finden Sie die auf dem Allgemein Tab wichtigsten Einstellungen für Ihren Editor:

settings general.de
Zeilennummern

Sie definieren hier, ob alle Zeilennummern, oder nur die der aktuellen Zeile dargestellt werden.

Schaltflächen zum Zuklappen von Abschnitten

Aktivieren Sie hier die Dreiecke zum Ein- & Ausklappen der Abschnitte im Texts.

Zeige Dateiendungen

Möchten Sie, dass alle Dateiendungen im Projektnavigator der Seitenleiste eingeblendet werden? Ist das deaktiviert, erscheint die Dateiendung nur für die gerade selektierte Datei.

Zeilenbreite

Geben Sie mit der Zeilenbreite vor, wie viele Zeichen in eine Zeile des Editors eingegeben werden können, bevor dieser sie umbricht. Ist der dargestellte Bereich zu klein, wird aber in jedem Fall umgebrochen.

Abschnitts-Einrückung

Sie geben vor, wie viel Platz soll für den linken Einzug der Gleichheitszeichen der Überschriften frei bleiben soll. Sie bestimmen mit einem Wert zwischen 0 und 6 den linken Freiraum. So erreichen Sie für den Fließtext ein schöne linke Ausrichtung. Nur die = Zeichen laufen weiter nach Links raus.

Tabulatorbreite

Ihre Vorgabe der Breite eines Tabulators im Text. Hier bestimmen Sie mit einem Wert zwischen 1 und 100 die Zeichenbreite eines Tabulators. In der Praxis haben sich Werte zwischen 3 und 5 bewährt.

Einrücken mit

Wie möchten Sie den Platz beim Einrücken füllen? Mit Tabulatoren oder Leerzeichen.

5.2. Dateizugriff

settings fileaccess.de

Ein großes Thema bei modernen Betriebssystemen wie macOS und iOS ist die Sicherheit. Hier gilt es, schädliche Programme vom Zugriff auf die Tiefen des Betriebssystems fern zu halten. Aus diesem Grund hat Apple unter macOS und iOS das Konzept des Sandkastens (engl. Sandbox) eingeführt.

Jede App hat ihren eigenen Sandkasten und darf nur darin arbeiten. So gibt es auf dem Computer viele Apps, die jeweils aber nur in Ihren eigenen Sandkästen laufen dürfen. Wenn eine App ausserhalb des Sandkastens arbeiten will, muss es die Erlaubnis von der Benutzerin oder Benutzer einholen.

Das gilt auch für adoc Studio, auf dem macOS und iOS. Da adoc Studio zum Verarbeiten von Projekten auf sämtliche enthaltenen Text- und Mediendateien zugreifen muss, benötigt es eine explizite Freigabe von Ihnen.

Alle erlaubten Dateizugriffe werden in einer Liste eingetragen, die auf diesem Tabulator in den Einstellungen eingesehen und mit Hilfe der + und - Buttons verwaltet werden. Öffnen Sie ein neues Projekt, das hier noch nicht eingetragen ist, fragt die App nach und trägt die Erlaubnis selbstständig ein.

Aus Bequemlichkeit kann man auch Ordner einer höheren Ebene in der Dateistruktur eintragen. Dann wird nicht so oft nachgefragt.

5.3. EEditorstile

settings editorstyles.de

Hier definieren Sie das Aussehen des Editors. Klicken Sie sich auf der linken Seite mit der Maus durch die Liste der benannten Stile. Die meisten Stile gibt es für den Hell-Modus (mit einem ○ am Ende gekennzeichnet) und dem Dunkel-Modus (durch ein ● am Ende gekennzeichnet). Suchen Sie sich einen Stil aus, der Ihnen gefällt, oder Ihrem Geschmack am nächsten kommt. Dann geht es weiter.

Die mittlere Liste bietet Ihnen alle Elemente, Attribute und Funktionsnamen, die im Text verwendet werden. Hier folgen Sie einer einfachen Regel: Beginnen Sie mit dem Eintrag „Allgemein“ und stellen Sie dort die Schrift und deren Größe, sowie viele weitere gewünschte Attribute ein.

Wenn Ihr System auf einen automatischen Wechsel für Hell- oder Dunkelmodus eingestellt ist, merkt sich adoc Studio jeweils den zuletzt gewählten Stil, so dass die App dem automatischen Wechsel des Systems folgen kann.

5.4. Produktstile

Ebenfalls in adoc Studio  Einstellungen … (Shortcut: +,) finden Sie auf dem vierten Tab die Produkt-Stile.

Wie zuvor schon beschrieben, sind in adoc Studio Text und Gestaltung voneinander getrennt. Jede Gestaltung kommt aus einer Stildatei: den Produktstilen. In adoc Studio liefern wir bereits eine Reihe von Produktstilen mit aus, Sie können aber auch eigene erstellen. Der besondere Charm dieser Produktstile liegt in der verwendeten Technologie. Ob Sie die Ausgabe als Text, HTML oder PDF wählen ist gleich, die Gestaltung erfolgt über Cascading Style Sheets (CSS).

Ja, Sie haben richtig gelesen; mit einem CSS-Stil formatieren Sie alle Dokumente, sogar für PDF!

In diesem Tab der Einstellungen verwalten Sie Ihre Produktstile.

settings productstyles.de

Im linken Bereich werden zunächst die eigenen, und dann nach einem Trenner die enthaltenen Produktstile aufgelistet. Auf der rechten Seite werden Beispiele in dem zuvor selektierten Produktstil dargestellt. Under der Vorschau können Sie verschiedene Beispiele (links) und das Ausgabeformat (rechts) wählen.

Eigene Produktstile installieren

Produktstile sind Dateien mit der Endung .adocstyle. Neue Produktstile können im Finder per Doppelklick auf die Datei installiert werden. Oder Sie ziehen diese einfach in die Liste auf der linken Seite derEinstellungen. Schließlich finden sie unter der Liste der vorhandenen Produktstile auch einen +-Button, über den Sie neue hinzufügen können.

Produktstile entfernen

Es können nur eigene Produktstile entfernt werden. Klicken Sie mit der rechten Maustaste auf den gewünschten Produktstil, und wählen Sie im Kontextmenü den Eintrag Löschen.

Eigene Produktstile erstellen

Für die Erstellung oder Modifikation von Produktstilen benötigen Sie CSS-Kenntnisse. Hier beschreiben wir Ihnen, wie Sie möglichst einfach einen Produktstil auf Basis eines vorhandenen Produktstils erstellen:

  • Um einen eigenen Stil anzulegen, selektieren Sie den gewünschten Produktstil, der als Basis dienen soll.

  • Nun klicken Sie mit auf das ellipsis.circle - Menü und wählen den Eintrag duplizieren. Alternativ können Sie auch das Kontextmenü direkt auf dem Namen des Produktstils aufrufen.

  • Der duplizierte Stil erscheint anschließend als neuer Stil im oberen Bereich der Liste.

  • Nach einem Doppelklick auf den Namen können Sie diesen verändern.

Einen Stil bearbeiten

Um den Produktstil zu bearbeiten, benötigen Sie einen Text-Editor. In unserem Fall verwenden wir gerne BBEdit. Sie können natürlich jeden anderen Editor verwenden, solange dieser CSS-Dateien im Format UTF-8 speichern kann.

  • Selektieren Sie nun den neu erstellten Produktstil.

  • Im ellipsis.circle - Menü oder im Kontextmenü finden Sie jetzt den Eintrag Bearbeiten in.

  • In der Liste wählen Sie ihren favorisierten Editor.

  • Die gewählte App startet und der Produktstil wird in der App geöffnet.

  • Nun können Sie alle gewünschten Änderungen am Produktstil vornehmen.

Stellen Sie sicher, dass adoc Studio im Hintergrund läuft und der gerade bearbeitete Stil auch für die Vorschau eingestellt ist. So wird die Vorschau in adoc Studio umgehend aktualisiert und Ihre Änderungen im externen Editor sichern.

6. Die Auszeichnungssprache AsciiDoc

Wie bereits erklärt, verwendet adoc Studio die Markup-Sprache AsciiDoc als Grundlage. In diesem Kapitel geben wir dem Einsteiger einen ersten Überblick des Befehlsumfangs von AsciiDoc. Anschließend erhielten Sie Links, auf die entsprechende Seite der offiziellen Dokumentation.

AsciiDoc-Profis können dieses Kapitel gerne überspringen. Statt dessen haben wir eine Bitte: Auf der Roadmap für adoc Studio finden Sie die Liste der noch nicht implementierten AsciiDoc-Funktionen. Bitte priorisieren Sie dort Ihren persönlichen Bedarf. In unserem Forum laden wir Sie ein, mit uns und anderen darüber zu diskutieren.

6.1. Was ist AsciiDoc?

AsciiDoc ist eine vereinfachte Auszeichnungssprache, die dazu dient, Texte in verschiedenen Dokumentenformaten zu veröffentlichen. AsciiDoc-Dateien können in verschiedene Formate konvertiert werden, z. B. HTML, PDF, ePub und andere. Im Vergleich zu XML-basierenden Dokumentenformaten wie DocBook haben auf die auf reinen Text basierende leichte Auszeichnungssprachen wie AsciiDoc den Vorteil, mühelos erlernbar zu sein. Außerdem sind sie auch unverarbeitet (als Quelltext) sehr gut lesbar. Mehr dazu auf Wikipedia.

In diesem Kapitel verweisen wir ergänzend auf die AsciiDoc-Dokumentation. Zur Zeit liegt diese Webseite nur in englischer Sprache vor. Wir arbeiten mit dem amerikanischen Kollegen an einer deutschen Übersetzung. Bitte haben Sie etwas Geduld.

6.2. Text schreiben

Sie verfassen Ihren Text so, wie Sie es gewohnt sind. Alles direkt hintereinander schreiben, genauso wie Sie es auch in anderen Programmen machen – gerne auch Fließtext genannt. Sie können aber auch den Text Zeile für Zeile schreiben. Also jeden Satz in eine neue Zeile. Das ist Ihre Entscheidung. Der gesetzte Text sieht immer gleich aus.

Ein neuer Absatz entsteht durch eine Leerzeile zwischen den Absätzen.

So einfach ist das.

Die Präambel

Der erste Absatz eines Dokuments ist die Präambel oder auch machmal Abstrakt genannt. Dieser Absatz wird automatisch etwas größer als der normale Text gesetzt. Das wird gerne als Einleitung für das Dokument genutzt.

Sie können aber auch beliebige andere Absätze größer setzen, wenn ein [.lead] vorangestellt wird.

Beispiel 1. Ein Abstrakt oder Präambel mitten im Text einbinden
[.lead]
Dieser Absatz wird etwas größer als alle anderen Absätze dargestellt. Und mit dem Produktstil „Optima“ bekommt der Absatz sogar ein Initial (also einen Großbuchstaben als dekoratives Element.
Ergebnis:

Dieser Absatz wird etwas größer als alle anderen Absätze dargestellt. Und mit dem Produktstil „Optima“ bekommt der Absatz sogar ein Initial (also einen Großbuchstaben als dekoratives Element.

Möchten Sie diesen Effekt im ersten Absatz nicht nutzen und Ihren Text sofort in der regulären Schriftgröße beginnen, stellen Sie ein [.nolead] voran.

Mehr Informationen zu den Absätzen finden Sie auf der AsciiDoc-Webseite.

6.3. Formatierungen

Wie in jeder Auszeichnungssprache können Sie auch einzelne Worte fett, kursiv oder anders setzen. So ist der Umstieg sehr einfach. Das Editor-Menü in adoc Studio liefert Ihnen darüber hinaus alle wichtigen Formatierungen für den schnellen Zugriff mit der Maus oder der Tastatur.

Tabelle 5. Direkte Formatierungen im Editor-Menü
Befehl Tastaturkürzel Auszeichnung im Text Resultat in der Vorschau

Fett

+B

*fett*

fett

Kursiv

+I

_kursiv_

Kursiv

Markiert

+#

#markiert#

markiert

Feste Laufweite

++#

`feste Laufwxeite`

feste Laufwxeite

Unterstrichen

+U

[.underline]#unterstrichen#

unterstrichen

Durchgestrichen

++X

[.line-through]#durchgestrichen#

durchgestrichen

Überstrichen

+++X

[.overline]#überstrichen#

überstrichen

Hochgestellt

++++

^hochgestellt^

hochgestellt

Tiefgestellt

+++-

~tiefgestellt~

tiefgestellt

Aber AsciiDoc kann noch viel mehr. Sie kombinieren diverse Auszeichnungen nach belieben. Der Text:

**##Super##cali[underline]##fragilist__isch##[red]##expialige__tisch##** 😀

wird zu:

Supercalifragilistischexpialigetisch 😀

Mehr Informationen zu den Formatierungen im Text finden Sie auf der AsciiDoc-Webseite.

6.4. Überschriften

Überschriften – oder genauer – Überschriftsebenen können mit einer Anzahl von = oder # gesetzt werden. Letzteres vereinfachen Ihnen einen Umstieg von Markdown zu AsciiDoc. Aber besser ist es, Sie gewöhnen sich gleich an das =-Zeichen; denn das kann deutlich mehr.

Hier alle Überschriften im Quelltext:

= Dokumenttitel
== Überschrift 1
=== Überschrift 2
==== Überschrift 3
===== Überschrift 4
====== Überschrift 5
Weitere Überschriften

Wenn die sechs Ebenen plus Dokumenttitel nicht ausreichen, kann vor einer Zeile ein . als Absatzüberschrift gesetzt werden:

.Weitere Überschriften
Mehr Informationen zu den Überschriftsebenen finden Sie auf der AsciiDoc-Webseite.

6.5. Inhaltsverzeichnis

Wenn man Überschriften – oder auch Section Title in AsciiDoc-Sprache – definiert, kommt automatisch ein Inhaltsverzeichnis in den Sinn. Und automatisch ist genau der Punkt!

Tragen Sie in den Dokumentkop :toc: ein, erhält das Dokument automatisch ein Inhaltsverzeichnis. Dieses enthält zwei Überschriftsebenen und steht über dem Dokument. Es wird permanent aktualisiert.

Das Attribut :toc: kann aber auch Parameter aufnehmen:

  • left: Das Inhaltsverzeichnis wird links vom Text positioniert.

  • right: Das Inhaltsverzeichnis wird rechts vom Text positioniert.

  • preamble: Das Inhaltsverzeichnis wird nach der Präambel positioniert.

  • macro: Das Inhaltsverzeichnis wird durch das Makro `toc::[]' an der gewünschten Stelle eingefügt.

  • auto: Die gleiche Funktion wie auch ohne Parameter.

In diesem Zusammenhand ist noch ein weiteres Attribut interessant: :toclevels: 3. Durch die Ziffer nach dem Attribut toclevels geben Sie die Anzahl der Ebene vor, die im Inhaltsverzeichnis erscheinen. Das Attribut muss im Dokument-Kopf gesetzt werden. Im Standard sind zwei Ebenen vorgegeben.

Mehr Informationen zu Inhaltsverzeichnissen finden Sie auf der AsciiDoc-Webseite.

Bei den Verlinkungen unterscheiden wir:

  • Hyperlinks ins Internet

  • Querverweise im Dokument

Der einfachste Link ist eine ausgeschriebene Adresse, die in der Vorschau sofort zu einer URL wird, die auch geklickt werden kann. Die entsprechende Seite öffnet sich im Browser: https://adoc-studio.app. Das funktioniert für die wichtigsten URL-Schema:

  • http

  • https

  • ftp

  • irc

  • mailto

Jeder Link kann aber auch als Makro ausgegeben werden: https://www.adoc-studio.app[]. Zwischen den Klammern geben Sie optional einen Text ein, der anstelle der URL angezeigt werden soll:

https://www.adoc-studio.app[adoc Studio-Webseite] wird zu adoc Studio-Webseite.

Mehr Informationen zu Hyperlinks finden Sie auf der AsciiDoc-Webseite.

Querverweise im Dokument

Um zu anderen Positionen im gleichen Dokument (alleinstehendes Dokument und Sammeldokument) zu springen, fügen Sie einen Querverweis ein.

<<Referenz>>

Die Referenz ist dann eine automatische ID einer Überschrift oder ein Anker.

Verwenden Sie die automatischen IDs so sparsam wie möglich; denn wenn Sie eine Überschrift ändern, auf die Sie per Querverweis zugreifen, geht dieser sofort kaputt.

Besser ist es immer, wenn Sie einen Anker vor einer Überschrift setzen.

[#mein_anker] 
== Meine Überschrift

Nun setzen Sie den Querverweis im Text per:

<<mein_anker>>

setzen. Im gesetzten Dokument erscheint dann die Überschrift. Optional können Sie anschließend auch noch einen Text setzen, der anstelle der Überschrift ausgegeben wird:

<<mein_anker, Springe hier hin>>
Mehr Informationen zu Querverweisen finden Sie auf der AsciiDoc-Webseite.

Fußnoten

Fußnoten werden automatisch generiert, wenn das Makro footnote:[] eingesetzt wird.1 Der Text der Fußnote steht dabei zwischen den eckigen Klammern:

footnote:[Hier ist der Text der Fußnote]
AsciiDoc kann zur Zeit nur Fußnoten generieren, die als Endnoten dargestellt werden. Darum haben wir sowohl footnote und endnote implementiert. Für die Kompatibilität zu bestehenden Dokumenten können Sie das Attribut :footnotes-position: verwenden.
Mehr Informationen zu Fußnoten finden Sie auf der AsciiDoc-Webseite.

6.7. Bilder

In der Einführung haben wir das Thema Bilder und deren Pfade bereits einmal kurz angesprochen. Jetzt gehen wir auf die Einbindung der Bilder im AsciiDoc-Text ein.

Bei den Bildern gibt es zwei Anordnungen, einmal als Blockbild und einmal als Bild im Fließtext.

Blockbilder

Die grundsätzliche Schreibweise ist:

image::bild.png[]

Dabei muss der Text in einer eigenen Zeile stehen. Nun kann die Klammer sehr viele Optionen aufnehmen. Hier hilft das Vervollständigungsmenü von adoc Studio, wie im Beispiel "So binden Sie ein Bild im Text ein" gezeigt. Die drei wohl wichtigsten Optionen sind:

  • width: Die Breite des Bildes.

  • align: Die Ausrichtung eines Bildes.

  • float: Der Umfluss um ein Bild.

Inline-Bilder

Die Syntax ist zu den Blockbildern sehr ähnlich, es wird nur ein : weggelassen:

image:bild.png[]

ein Bild, dass sich im Fließtext einfügt. Beispiel:

Drücken Sie bitte image:reload.svg[], um die Seite neu zu laden.

Ergibt:
Drücken Sie bitte reload , um die Seite neu zu laden.

Aber auch nebeneinander gestellte Bilder lassen sich mit Inline-Bildern schnell realisieren:

hello hello hello hello hello

Mehr Informationen zu Bildern finden Sie auf der AsciiDoc-Webseite.

6.8. Listen

Starten wir mit der ungeordneten Liste:

  • Eine Liste beginnt mit einem *

    • mit ** setzen sie diese eine Ebene tiefer.

      • Und mit jedem zusätzlichen Stern,

        • geht es eine weitere Ebene tiefer

      • oder

    • auch

  • umgekehrt.

Wenn Sie von Markdown kommen, funktioniert auch folgendes:

  • Markdown-Listen mit einem - beginnen

  • funktioniert

  • natürlich auch

Geordnete Liste sind ebenso einfach:

  1. eins

  2. zwei

  3. drei

Sie können aber auch gerne eine Zahl mit angeben:

  1. eins

  2. zwei

  3. drei

  4. eine fehlerhafte Nummerierung (hier) wird ignoriert und somit keine 7. (wie im Editor), sondern 4. ausgegeben

adoc Studio erstellt immer die automatische Nummerierung!

Sollen die Listen etwas komplexer werden, ist das Konzept wie schon bei der ungeordneten Liste.

  1. Schritt 1

    1. Schritt 1 a

    2. Schritt 1 b

  2. Schritt 2

  3. Schritt 3

Es gehen sogar Checklisten:

  • zu erledigen

  • erledigt

  • auch erledigt

  • und sogar kombiniert mit anderen Einträgen

Mehr Informationen zu Listen finden Sie auf der AsciiDoc-Webseite.

6.9. Blockelemente

Ein Blockelement (auch Block genannt) ist die Allzweckwaffe in AsciiDoc. Hier gibt es unzählige Darstellungsformen und Verwendungen.

Wichtig ist zu wissen, dass Blöcke – sofern sie nicht wie z. B. die Hinweise auf einer Zeile abgebildet werden – immer zwischen zwei Begrenzern stehen; dem Blockstart und -ende. Hier gibt es eine ganze Reihe von unterschiedlichen Zeichen. Wie zum Beispiel hier bei dem folgenden Zitat:

Zwei Dinge sind unendlich: das Universum und die menschliche Dummheit. Und bei dem Universum bin ich mir nicht sicher.

— Albert Einstein
Mehr Informationen zu Text- und anderen Blöcken finden Sie auf der AsciiDoc-Webseite.

6.10. Hinweise

Insbesondere dieser Bereich ist es wert, ihn in unterschiedlichen Stilen anzusehen. Wir haben uns sehr viel Mühe bei den Bildchen gegeben.

Achten Sie darauf, dass zu Beginn Ihres Dokuments das Attribut :icons: font gesetzt ist. Ansonsten erscheint anstelle der Symbole nur ein Text.

NOTE gibt der Leserin oder dem Leser ergänzende Hinweise.
TIP schlägt der Leserin oder dem Leser einen Kniff oder eine Besonderheit vor.
WARNING weist die Leserin oder den Leser auf eine Gefahr hin.
CAUTION weist die Leserin oder den Leser auf einen Fallstrick hin.
IMPORTANT weist die Leserin oder den Leser auf einen wichtigen Umstand hin.

Und hier gleich ein praktischer Hinweis:

Mehr Informationen zu Hinweise finden Sie auf der AsciiDoc-Webseite.

6.11. Tabellen

Ähnlich umfangreich wie die Blöcke sind die Tabellen. Es beginnt mit einfachen tabellarischen Darstellungen wie hier:

Eins

 Zwei

Drei

Als nächstes kommt eine Kopfzeile zur Tabelle, die einfach durch eine Leerzeile hervorgehoben wird:

Titel 1 Titel 2 Titel 3

Eins

 Zwei

Drei

Vier

 Fünf

Sechs

Aber auch komplexe Beispiele (von der AsciiDoc-Webseite) sind möglich:

Spalte 1 Spalte 2

Dieser Inhalt wird über zwei Spalten (2*) dupliziert und am rechten Rand der Zelle ausgerichtet (>).

Es wird mit einer Monospace-Schriftart gerendert (m).

Diese Zelle erstreckt sich über 3 Zeilen (3+). Der Inhalt wird horizontal zentriert (+^+), vertikal am unteren Rand der Zelle ausgerichtet (.>) und als stark formatiert (s) dargestellt.

Dieser Inhalt wird kursiv dargestellt (e).

Dieser Inhalt wird mit einer Monospace-Schriftart dargestellt (m).

Dieser Inhalt ist fett (s), außer dem Wort Inhalt.

Ende.

Mehr Informationen zu Tabellen finden Sie auf der AsciiDoc-Webseite.

6.12. Benutzerschnittstelle

Gerade in der technischen Dokumentation sind Beschreibungen der GUI (Graphical User Interface) oder kurz der UI (User Interface) an der Tagesordnung. Hier gibt es vor allem drei wichtige Bereiche:

Tastaturkürzel

Mit dem kbd:[]- Makro erstellen Sie Tastenkappen in Ihrer Dokumentation. So führt ein +S schnell zum Sichern des Dokuments.

Eine Besonderheit bei den kbd:[]- Makros zeigen wir bei den Cursortasten in diesem Dokument.

Menüs

Das menu:[]- Makro hilft bei der Beschreibung der Menüeinträge. Zum Beispiel starten Sie den Produktexport via Ablage  Export  Produkte …

Schaltflächen und Button

Das Makro  ist für die Ausgabe aller Arten von Schaltflächen zuständig. So haben Sie immer einen OK Button zur Hand.

Mehr Informationen zu UI-Makros finden Sie auf der AsciiDoc-Webseite.

6.13. Kommentare

Insbesondere wenn Sie sich dieses Dokument als Quelltext in adoc Studio ansehen, lohnt sich der Blick in den Editor. Schließlich werden Kommentare nur hier dargestellt.

Zu Beginn einer Zeile können Sie den dann folgenden Text mit // als Kommentar markieren.

// Dieser Text ist ein Kommentar und wird nicht in dem Dokument ausgegeben.

Natürlich lassen sich ganze Abschnitte auch als Kommentar definieren. Dann müssen Sie einfach nur am Anfang und Ende des Blocks per //// einen Kommentarblock definieren.

In diesem Zusammenhang darf auch die Frage gestellt werden, warum jemand in einem Text Kommentare einfügen möchte, die nicht im Dokument ausgegeben werden. Hier eine kleine Sammlung von Ideen:

  • Das berühmte // TODO: Noch zu erledigende Aufgaben für den Text: Optimierungen, Verbesserungen, Korrekturen etc.

  • Anweisungen für die Formatierungen.

  • Begründungen, warum ein Inhalt so ist, wie er ist.

  • Interne Versionshinweise die nicht öffentlich gemacht werden sollten.

  • Hinweise für Lektoren

  • et cetera

Mehr Informationen zu Kommentaren finden Sie auf der AsciiDoc-Webseite.

6.14. Attribute

Jetzt kommen wir zu dem Bereich, den wir intern als absoluten Game-Changer betrachten. Mit den Attributen heben Sie Ihre Dokumentation auf eine komplett neue Ebene!

Der Begriff Attribute wird in adoc Studio unterschiedlich genutzt. Im Wesentlichen kann man damit:

  • Werte definieren und diese dann im Text nutzen

  • Einstellungen im Dokument vornehmen

Attribute im Sinne einer Variable nutzen

Bestimmte Worte, URLs und andere Informationen werden ständig und wiederholt gebraucht. Manche Begriffe ändern sich für jede Version eines Dokument. Und manche Begriffe – wie z. B. eine URL – sin so lang, dass man sie nur einmal eintippen möchte – alleine schon, um Fehler zu vermeiden. Setzen Sie diese einfach in ein Attribut. Das können dann an jeder Stelle eines Dokuments beliebig oft verwenden.

Beispiel 2. Ein Attribut als Variable nutzen
Definition
:app-version: 1.2.3.4
Eingabe
Dieses Dokument basiert auf der Version {app-version}.
Ausgabe

Dieses Dokument basiert auf der Version 1.2.3.4.

Alleine damit haben Sie schon sehr umfangreiche Möglichkeiten. In dieser Dokumentation verwenden wir jedes Mal, wenn der Name adoc Studio auftritt, das Attribut {app-name}. Hier sind ein paar in diesem Dokument von uns verwendete Attribute:

:app-name: adoc Studio
:lang: de
:url-website: https://www.adoc-studio.app
:url-roadmap: https://adoc-studio.canny.io 
:url-styles: https://styles.adoc-studio.app 
:url-forum: https://forum.adoc-studio.app

Es gibt in adoc Studio eine Reihe von Standard-Attributen, die bereits fest vorbereitet sind, da sie in (fast) jedem Dokument vorkommen. Diese müssen aber zu Beginn Ihres Dokument – im Dokumentenkopf eingetragen werden:

  • Autoreninformationen (:author:)

  • Versions-Attribute (:revnumber:, :revdate: und :revmark:)

  • Metadaten (:description:, :keywords:)

Ein Beispiel für dieses Dokument könnte wie folgt aussehen:

:author: Frank Blome
:revnumber: 1.0
:revdate: {docdate}
:description: Dieses Dokument führt Sie in die Arbeit mit {app-name} ein.
:keyword: {app-name}, AsciiDoc, Technische Dokumentation, Handbücher und mehr

Einen Standardtitel kann man sogar folgendermaßen abkürzen:

= Das Handbuch für {app-name}
Frank Blome <frank@projectwizards.net>
1.0, {docdate}

In dem Fall wird die Information für :author: , :email: und :revnumber: sowie :revdate: automatisch aus dem Kontext nach dem Dokumenttitel (=) gezogen und kann später als Attribut mit {} ausgegeben werden.

Attribute als Dokumenteinstellung

Der nächste Einsatzzweck von Attributen dient den Einstellungen Ihres Dokuments. Jedes Dokument enthält eine Reihe von Name-Wert-Paaren, die als Dokumentattribute bezeichnet werden. Diese Attribute ermöglichen es, den Backend-Prozessor zu konfigurieren, Dokument-Metadaten zu deklarieren. Dabei können Sie auf eingebaute Attribute zurückgreifen oder auch eigene definieren.

Dokumentattribute müssen immer am Zeilenanfang gesetzt werden!
Eingebaute Attribute

Eingebaute Attribute helfen das Dokument zu konfigurieren und zu steuern. Dabei werden viele eingebaute Attribute nur dann wirksam, wenn sie am Anfang des Dokuments in einer Zeile definiert werden.

Attribute können:

  • Zugang zu den Dokumenten-Informationen gewähren

  • Dokument-Metadaten definieren

  • Integrierte Funktionen ein- oder ausschalten

  • Integrierte Funktionen konfigurieren

  • Den Speicherort von Assets, wie z.B. Bildern, angeben

  • Speichern von Inhalten zur Wiederverwendung in einem Dokument

Beispiele
  • Attribute werden entweder nur durch den reinen Eintrag gesetzt: :beta:.

  • Attribute werden durch Zusätze gesetzt: :beta-version: 23.

  • Attribute werden durch ein Ausrufezeichen umgesetzt oder deaktiviert: :!beta: oder :beta!:.

In adoc Studio funktioniert der Aufruf aller eingebauten Attribute sehr elegant. Drücken Sie einfach am Zeilenanfang die ESC- Taste und wählen im Menü der Textvervollständigungen den Eintrag :Attribute:. In dem darauf folgenden Menü finden Sie alle eingebauten Attribute.

text menu text menu attributes

Mehr Informationen zu den eingebauten Attributen finden Sie auf der AsciiDoc-Webseite.
Benutzerdefinierte Attribute

Ein benutzerdefiniertes Attribut ist jedes Attribut, das der Autor setzt und das nicht von der AsciiDoc-Sprache oder einer Erweiterung reserviert ist. Meistens werden benutzerdefinierte Attribute zur Textersetzung verwendet. Diese Attribute ermöglichen es dem Autor, benannte und wiederverwendbare Inhalte zu definieren. Anstatt Text im gesamten Dokument zu wiederholen, wie z. B. einen Produktnamen, kann dieser Text in einem Attribut definiert und stattdessen durch seinen Namen referenziert werden. Diese Technik hilft dabei, das Dokument DRY zu halten, was für „Don’t Repeat Yourself“ (Wiederhole dich nicht) steht.

Ein Beispiel, das wir in der Dokumentation für mp 32 Merlin Project regelmäßig anwenden:

:mp-mpe-features: https://www.projectwizards.net/merlin-project/features
:not-in-mpe: CAUTION: Diese Funktion ist in Merlin Project Express nicht enthalten. +
             Bitte vergleichen Sie Ihre Anforderungen mit der Tabelle +
             der {mp-mpe-features}[Funktionsvergleiche].

Wird dann zu:

Diese Funktion ist in Merlin Project Express nicht enthalten. Bitte vergleichen Sie Ihre Anforderungen mit der Tabelle der Funktionsvergleiche.

Das ist eine große Arbeitserleichterung, da der Text nicht jedes Mal mit Copy & Paste wiederverwendet werden muss. Auch eine Änderung dieses Textes muss so nur ein Mal im Dokument erfolgen!

Mehr Informationen zu den Dokumentattributen finden Sie auf der AsciiDoc-Webseite.

6.15. Bedingte Anweisungen

Eine bedingte Anweisung ist eine Kontrollstruktur in der Programmierung. Ein Programmabschnitt wird dabei nur unter einer bestimmten Bedingung ausgeführt. Genau so gilt das für unsere Texte in adoc Studio. Mit den folgenden bedingten Anweisungen können Sie Textzeilen in Ihr Dokument aufnehmen oder ausschließen:

  • ifdef: Der Inhalt wird nur einbezogen, wenn das angegebene Attribut gesetzt ist

  • ifndef: Der Inhalt wird nur einbezogen, wenn das angegebene Attribut nicht gesetzt ist.

  • ifeval: Der Inhalt wird nur einbezogen, wenn der Ausdruck innerhalb der eckigen Klammern der ifeval-Direktive als wahr ausgewertet wird.

Wenn der Prozessor auf eine dieser Bedingungen stößt, wertet er die angegebene Bedingung aus. Die Bedingung basiert auf dem Vorhandensein oder dem Wert eines oder mehrerer Dokumentattribute. Wenn die Bedingung als wahr bewertet wird, werden die von der Bedingung eingeschlossenen Zeilen einbezogen. Andernfalls werden die Zeilen übersprungen.

Mehr Informationen zu den bedingten Anweisungen finden Sie auf der AsciiDoc-Webseite.

6.16. Includes

Eine der Kernmerkmale von AsciiDoc ist der Umgang mit aufgeteilten Dateien. Also nicht eine endlos lange Datei schreiben. Sondern teilen Sie den Text in viele einzelne Dateien auf und ihn dann nach gewissen Regeln zusammenzubauen.

In adoc Studio haben wir im Abschnitt Der Projektnavigator unser eigenes Konzept dazu bereits vorgestellt.

Arbeiten Sie beispielsweise mit Autoren zusammen, die adoc Studio nicht verwenden können, empfehlen wir den include-Befehl zu nutzen. Über diese Befehle fügen Sie nacheinander die Kapitel, die auch im AsciiDoc-Format vorliegen, ein:

The file “kapitel-1.adoc” couldn’t be opened because there is no such file.
The file “kapitel-2.adoc” couldn’t be opened because there is no such file.
The file “kapitel-3.adoc” couldn’t be opened because there is no such file.
Includes in adoc Studio

Aber auch innerhalb unserer App kann include nützlich sein. Angenommen Sie wissen, dass für Ihr Produkt nicht alles auf einmal dokumentiert werden kann. So brauchen Sie einen Platzhalter.

Wir haben in diesem Projekt in der Dateiliste einen solchen Platzhalter definiert: comingSoon.adoc. Damit diese Datei im Sammeldokument nicht ausgegeben wird, wurde in den Dateiinformationen die Checkbox deaktiviert (weitere Details dazu siehe hier). Wann immer eine Funktion noch nicht beschrieben ist, platzieren Sie folgenden Text:

:feature: wichtigen Funktionen
include::comingSoon.adoc[]

Dieser wird dann wie folgt ausgegeben:

Die wichtigen Funktionen sind noch nicht beschrieben. Wir arbeiten daran, das sobald wie möglich nachzuholen.

Der Trick ist der Inhalt der Datei comingSoon.adoc:

  1. Wenn diese Datei über den include-Befehl aufgerufen wird, erfolgt zuvor die Zuweisung eines Text zum Attribut feature – in diesem Fall „wichtigen Funktionen“.

  2. Die Datei comingSoon.adoc wird nun an der aktuellen Position inkludiert.

  3. Das Feature wird zunächst überprüft, ob in dem Attribut ein Text enthalten ist.

  4. Wenn das der Fall ist, wird die Warnung ausgegeben.

  5. Anschließend wird das Attribut geleert.

Mehr Informationen zu Includes finden Sie auf der AsciiDoc-Webseite.

7. Dokumente ausgeben

Beim Export unserer Dokumente haben wir uns etwas Neues einfallen lassen, das Sie insbesondere bei umfangreichen Projekten sehr unterstützen wird. Wir unterscheiden zwischen dem normalen Export eines Dokuments und der Ausgabe von Produkten. Aber vorher zu einer wichtigen Zwischenstufe der Ausgabe; die Vorschau.

7.1. Die Vorschau

Rechts neben dem Editor finden Sie die Vorschau. Ist diese nicht dargestellt, klicken Sie auf das eye oder verwenden das Tastaturkürzel ++P um sie einzublenden.

Die Vorschau verhält sich je nach eingestelltem Ausgabeformat unterschiedlich. Mal ist sie wie ein Browser, der eine HTML-Seite darstellt, mal wie die PDF-Vorschau und mal eine Anzeige im RTF-Format. Das Ausgabeformat finden Sie in dem Dialog hinter dem chevron.down -Symbol nach dem eye . Genauso finden Sie dort zusätzliche Schalter, um weitere Einstellungen vorzunehmen. Diese könne sich je nach Ausgabeformat unterscheiden.

HTML-Vorschau & Einstellungen

previewOptions

Stellen Sie das Ausgabeformat auf HTML, wird das Dokument im Editor als ein langes HTML-Dokument ausgegeben. Wir nennen das gerne scherzhaft einen langen Lappen.

  • Der Stil, oder genauer; in welchem Produkt-Stil Sie das Dokument in der Vorschau sehen wollen.

  • Die Erscheinung bezieht sich auf die helle oder dunkle Darstellung (gerne auch als Darkmode und Brightmode bezeichnet). Bei automatischer Einstellung verwendet adoc Studio, die in der Systemsteuerung Ihre Betriebssystems vorgegebene Einstellung.

  • Die Attribute, mit denen Sie das Dokument steuern. Die Besonderheit ist: Neben den Attributen, die im Dokument vergeben werden, können hier weitere Attribute in einem Dialog vergeben werden. Details erfahren Sie dazu in der Beschreibung der Produkte.

Text-Vorschau & Einstellungen

Neben den Einstellungsmöglichkeiten für den Stil, die Erscheinung und die Attribute, entscheiden Sie hier zusätzlich über:

  • Das Textformat, welches formatiert (als RTF) oder als reiner Text ausgegeben wird. Bei letzterem findet der Stil natürlich keine Anwendung mehr. Auch Bilder werden nicht mehr dargestellt.

PDF-Vorschau & Einstellungen

pdfPreviewOptions

In dieser Vorschau sehen Sie das Dokument so, wie es beim Export in eine Datei geschrieben würde. Die Einstellungen hinter dem chevron.down -Symbol umfassen nicht nur den Stil, die Erscheinung und die Attribute, sondern zusätzlich:

  • Papier, wo Sie neben dem Papierformat auch den Drucker und die Seitenränder einstellen. Später, im Kapitel über die Produktstile gehen wir noch einmal genau auf die Details und Zusammenhänge ein.

  • Ausrichtung, wo Sie entscheiden, ob das Dokument im Hochformat (Portrait) oder im Querformat dargestellt wird.

Im Menü Vorschau finden Sie jetzt, wenn PDF als Ausgabeformat aktiv ist, einige Einträge, die auch schon in der Vorschau.app von Apple bekannt sind. Damit können Sie den benötigten Platz für die von Ihnen verwendete Bildschirmgröße optimieren:

  • Einzelseite

  • Doppelseite

  • Einzelseite scrollen

  • Doppelseite scrollen

7.2. Funktionen für Editor und Vorschau

Vorschau mit dem Editor koppeln

Im Standard scrollt die Vorschau immer so mit, dass sie auf der gleichen Höhe wie die aktuelle Zeile im Editor ist. So muss Ihr Auge nur nach rechts wandern, um den Text in der Vorschau zu finden.

Dieses Verhalten kann im Menü Vorschau  Mit Editor koppeln  Leseposition abgeschaltet werden. Das ist immer dann hilfreich, wenn Sie Texte aus der Vorschau eines anderen Dokuments kopieren und in den Editor einfügen möchten.

Aufklappzustand mit dem Editor koppeln

Sind in den Einstellungen die Schaltflächen zum Zuklappen von Abschnitten aktiviert, kann diese Kopplung auch hier genauso getrennt werden.

Der Aufklappzustand wirkt sich auf die Sektionen (also; die Überschriften 2 x == bis 6 x ======, aber nicht auf den Dokumenttitel). Klappen Sie eine Sektion im Editor zu, wird die entsprechende Sektion auch in der Vorschau zugeklappt.

Ist der Editor ausgeblendet, werden in der Vorschau ebenfalls die Aufklapp-Dreiecke sichtbar, so dass der Text weiterhin in der Vorschau ein- oder ausgeblendet werden kann.

Inhalt mit dem Editor koppeln

Über das Menü Vorschau  Mit Editor koppeln  Inhalt entscheiden Sie über das automatische Darstellen einer Datei im Editor und der Vorschau gleichzeitig. Alles, was Sie in der Seitenleiste auswählen, wird im Editor und gleichzeitig in der Vorschau dargestellt.

Klicken Sie auf eine Datei in der Seitenleiste mit gedrückter -Taste, wird die gewählte Datei vom Editor abgekoppelt in der Vorschau dargestellt. So kann man schnell eine Datei in der Vorschau anzeigen und eine andere im Editor bearbeiten.

7.3. Exportieren

Wann immer Sie eine Datei exportieren wollen, ist das Menü Ablage  Export  Auswahl – oder der Shortcut ++E – das, was Sie suchen. Zusätzlich finden Sie in der Symbolleiste rechts das share -Symbol. Jeder Weg öffnet den Dialog für den Export.

export

Sind Sie bereits mit der Darstellung in der Vorschau zufrieden, markieren Sie die Checkbox Wie Vorschau und drücken auf .

Ansonsten stehen Ihnen in diesem Dialog wieder die Optionen für die Ausgabe zur Verfügung, wie schon bei der Vorschau erklärt:

  • Format: Das Zielformat der Datei (Text, HTML oder PDF)

  • Stil: Die Gestaltung der Datei. Die Details finden dazu hier.

  • Aussehen: Vorgabe des Hell- oder Dunkelmodus, bzw. automatische Übernahme vom System

  • Attribute: Vorgabe bestehender oder eigener Attribute. Eine Einführung finden Sie hier.

  • Sowie die ausgabespezifischen Einstellungen.

  • Aktion: Ihre Entscheidung, was mit der Ausgabe erfolgen soll. Im Standard ist immer der Exportieren voreingestellt, den Sie nach dem Klick auf „Export“ wählen können. Sie können aber auch einen Export direkt per E-Mail oder Apple AirDrop oder eine andere Art mit anderen teilen.

Exportieren Sie im HTML-Format, stellen Sie zusätzlich Ausgabe der Ressourcen der HTML-Datei ein. Ressourcen einer HTML-Datei sind beispielsweise Medien und Stildateien. Folgendes Vorgaben sind möglich:

  • Separieren: Die Ressourcen werden als separate Dateien in einem Ordner neben die HTML-Datei gelegt.

  • Eingliedern: Die Ressourcen werden kodiert die HTML-Datei eingebettet.

  • Ohne: Die Ressourcen werden nicht exportiert.

  • Aus Attributen: Hier werden die Ressourcen nicht exportiert, aber die Attribute :stylesheet: und :stylender: beachtet. Sind die Attribute nicht vergeben, werden die Ressourcen exportiert.

Soll es für ein Dokument spezielle Attribute geben, steht Ihnen in den Einstellungen eine besondere Attributliste zur Seite. Klappen Sie die Liste auf, erscheint kleiner Dialog, in dem Sie neue Attribute anlegen, oder vorhandene Attribute auswählen können.

Alle Eingaben dieser Liste überschreiben die im Text eingegebenen Attribute und haben damit die höchste Priorität.

7.4. Produkte

Wir gehen davon aus, dass die Dokumente, die in adoc Studio erstellt werden, länger leben und damit dauerhaft gepflegt und ausgegeben werden. Wann immer Sie also mit komplexen Export-Konfigurationen arbeiten, oder oft zwischen unterschiedlichen Export-Einstellungen und besonderen Attributen wechseln müssen, brauchen Sie ein Werkzeug, dass alle unterschiedlichen Einstellungen aufnimmt, verwaltet und schnell abrufbar macht. Das übernehmen für Sie die Produkte.

produkte

Über das Menü Ablage  Export  Produkte … oder dem Shortcut ++E rufen Sie den Dialog für die Konfiguration der Produkte auf.

Rufen Sie die Produkte das erste Mal auf, ist die Liste auf der linken Seite noch leer. Ein Klick auf das + – Symbol zeigt Ihnen eine Liste aller Dokumente. Wählen Sie hier ein das gewünschte Dokument oder Sammeldokument.

Jetzt stehen auf der rechten Seite verschiedene Optionen bereit:

  • Produktname: Ein optionaler Name für Ihr Produkt.

  • Quelle: Die von Ihnen ausgewählte Quelle für das Produkt. Natürlich kann die hier auch geändert werden.

  • Dateiname: Das fertige Produkt wird mit diesem Dateinamen erzeugt. Bleibt das Feld leer, wird der Produktname oder – falls auch der nicht vergeben ist – der Dateiname der Quelle mit der Endung der gewählten Formats verwendet.

  • Unterordner: Ein optionales Unterverzeichnis, in dem das Produkt exportiert wird.

  • Nun können Sie die gleichen Export-Parameter, wie im vorherigen Abschnitt – dem Exportieren – vergeben.

Produkte in der Symbolleiste

productsList

Sobald Sie ein erstes Produkt erstellt haben, erscheint in der Symbolleiste links neben dem pencil der Produktname. Alle weiteren Produkte werden dieser Liste hinzugefügt.

Erstellen sich ein Produkt mit dem Ausgabeformat HTML und eines für PDF. So können Sie in der Symbolleiste sehr einfach zwischen dem blitzschnellen HTML und der etwas langsameren PDF-Generierung wechseln.

Produkte ausgeben

Um ein Produkt dann auszugeben, wählen Sie im Produkte-Dialog das gewünschte Ziel und klicken – je nach Ziel – auf Exportieren … oder Teilen.

Sie können aber auch viele Produkte auf einmal exportieren. Dazu wählen Sie im Produkte-Dialog das Kontext-Menü oder die ellipsis.circle und im Menü dann den Eintrag Export  Mehrere Produkte. Dann erscheint hinter allen Produkte eine Checkbox. Nun werden beim Exportieren … bzw. Teilen alle markierten Produkte exportiert.

Dabei teilen sich die einzelnen Produkte – bei HTML-Exporten – die Ressourcen. So haben Sie nach dem Export für jedes Produkt eine .html-Datei aber nur einen Ressourcen-Ordner mit Bildern, CSS-Dateien und so weiter.

8. Da fehlt doch noch etwas…

Wir sind mit adoc Studio am Anfang einer langen Reise. Für die erste, jetzt vorliegende Version, haben wir Funktionen herausgesucht, die 80% der Anwender ganz sicher benötigen. Natürlich wird es so sein, dass genau Ihnen die eine Funktion fehlt.

Gleich, ob Ihnen bei AsciiDoc oder in adoc Studio etwas fehlt, wir haben ein Onlinesystem bereitgestellt, in dem Sie uns aktiv unterstützen können. Bitte melden Sie sich kostenlos in diesem System an und stimmen Sie für fehlende Funktionen ab. Die Funktionen mit den meisten Stimmen werden von uns früher eingebaut. Natürlich können Sie auch eigenen Wünsche äußern oder Funktionen vorschlagen. Vielleicht werden die ja auch von anderen Anwenderinnen und Anwendern benötigt. So möchten wir sicherstellen, dass genau die von Ihnen benötigten Funktionen als nächste in adoc Studio erscheinen.

Freuen Sie sich mit uns auf das, was da noch kommt!

Anhang A: Support

Sie haben es geschafft! Bis hierhin haben wir uns auf die Beschreibung der Konzepte und Funktionen konzentriert. Nun sind Sie dran. Schreiben Sie und berichten Sie uns von Ihren Erfolgen. Wir freuen und darauf!

A.1. Systemanforderungen

Die minimalen Systemanforderungen Ihres Betriebssystems für adoc Studio sind:

  • macOS 13 Ventura

  • iOS 16

A.2. Erste Hilfe

Forum

Wir haben Ihnen ein kostenloses Forum eingerichtet, in dem Ihnen auch das Team der ProjectWizards mit Rat und Tat zur Seite steht.

Die adoc Studio Roadmap

Wir sind noch ganz am Anfang unserer Reise und haben noch viele Ideen. Damit Sie die weitere Entwicklung nicht nur sehen, sondern auch darauf einen Einfluss nehmen können, haben wir eine öffentliche Roadmap aufgesetzt. Fehlt Ihnen eine Funktion, tragen Sie die bitte hier ein, oder stimmen Sie für einen bereits geäußerten Wunsch, der Ihnen auch wichtig ist.

Die AsciiDoc-Befehlsreferenz

Hier finden Sie die stets aktuelle AsciiDoc-Befehlsreferenz. Diese liegt zur Zeit nur in englischer Sprache vor. Wir arbeiten aber an einer Übersetzung.

Eigene Erfahrungen mit AsciiDoc

Im Blog der ProjectWizards-Webseite gibt es eine ganze Reihe praktischer Artikel zum Thema AsciiDoc.

Weitere Tipps zu AsciiDoc

Auf Awesome Asciidoc(tor) finden Sie eine umfangreiche Sammlung verschiedenster Tipps & Tricks zu AsciiDoc.

A.3. Hilfe mit Vorlagen & Stilen

Wir bauen zur Zeit ein Partnernetzwerk auf, das Ihnen gerne beim Aufbaut Ihrer Vorlagen und der Gestaltung der Produktstile hilft. Die aktuelle Liste der Partner finden Sie stets auf der Webseite.

Im Laufe der Zeit werden wir dort auch ein Verzeichnis aller Stile aufbauen. Da wir aber gerade am Anfang der Produktstrategie für adoc Studio stehen, muss sich das alles noch entwickeln. Sollten Sie Lust haben, aktiv mitzuwirken, schreiben Sie uns gerne an: office@projectwizards.net.

Anhang B: Glossar

Viele Begriffe in adoc Studio kommen aus dem Vokabular von AsciiDoc und sind dem entsprechend englischsprachiger Natur. Da wir unsere App aber nicht nur in englischer Sprache herausgeben, haben wir uns entschieden, einige Begriffe zu übersetzen. Dadurch ergibt sich ein buntes Gemisch aus englischen und deutschen Begriffen. Das folgende Glossar soll Ihnen helfen, unfallfrei durch das Sprachengewirr zu finden.

In Zweifelsfällen gilt immer die (zur Zeit noch) vorläufige Spezifikation von AsciiDoc.

B.1. Inhalt

[ A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z ]


A

Abgegrenzte Blöcke

Ein abgegrenzter Block ist ein Bereich des Inhalts, der auf beiden Seiten von einem Paar kongruenter zeilenweiser Abgrenzungszeichen begrenzt wird. Ein abgegrenzter Block wird entweder verwendet, um andere Blöcke einzuschließen (z.B. mehrere Absätze) oder um das Inhaltsmodell des Inhalts festzulegen (z.B. wortwörtlich).

Absatz

In den meisten Dokumenten ist der Absatz der wichtigste Blocktyp. Deshalb müssen Sie keine speziellen Markierungen oder Attribute verwenden, um Absätze zu erstellen. Sie können einfach anfangen, Sätze zu tippen. Ob Sie für jeden Satz eine eigene Zeile verwenden, oder alles hintereinander weg schreiben, der Inhalt wird immer zu einem Absatz. Eine Leerzeile trennt Absätze voneinander.

Abschnitt

Unterteilt ein AsciiDoc-Dokument in eine Inhaltshierarchie. Ein Abschnitt wird durch einen Abschnittstitel definiert, dem ein oder mehrere Gleichheitszeichen vorangestellt sind. Der Abschnitt umfasst alle Inhalte, die auf dem Abschnittstitel folgen, bis zum nächsten geschwisterlichen oder übergeordneten Abschnittstitel oder bis zum Dokumentende.

Abschnittstitel

Kennzeichnet den Beginn eines Abschnitts und dient gleichzeitig als Überschrift für diesen Abschnitt. Anhand der vorangestellten Abschnittsmarkierung (Gleichheitszeichen) definieren Sie die Abschnittsebene. In adoc Studio können die Gleichheitszeichen im linken Rand des Editors angezeigt werden.

Abstrakt

Ein Abstrakt ist ein kurzer Überblick oder eine Zusammenfassung eines Dokuments. Manchmal wird es auch synonym zur Präambel verwendet.

Admonition

siehe Hinweis

adoc

Die Kurzform dieser App und gleichzeitig die Endung der Textdateien für AsciiDoc.

adoc Studio

Der Name dieser App.

Anhang

Der Abschnittsstil Anhang kann in Büchern und Artikeln verwendet werden und kann weitere Unterabschnitte haben. Obwohl die AsciiDoc-Struktur es erlaubt, Anhänge an beliebiger Stelle zu platzieren, ist es üblich, sie an das Endes eines Dokuments zu stellen.

Anker

Ist ein über das ID-Attribut definiertes Sprungziel.

Artikel

Ist der Standard-Doctype in adoc Studio. Dazu gehören die optionalen Abschnitte Anhang, Zusammenfassung, Bibliographie, Glossar und Index.

ASCII

Ist ein Akronym für American Standard Code for Information Interchange. Dieser Standard definiert 128 Zeichen, bestehend aus 33 nicht druckbaren sowie 95 druckbaren Zeichen und dem Leerzeichen. In AsciiDoc steht Ascii allerdings für „alles ist Text - sogar die Emoji“. AsciiDoc verwendet den vollen Unicode Zeichensatz.

AsciiDoc

Ist eine ausgereifte, leichtgewichtige und semantische Auszeichnungssprache, die hauptsächlich für die Erstellung von strukturierten Dokumenten entwickelt wurde. Sie konvertieren AsciiDoc-Dateien nach HTML oder PDF mit Programmen wie adoc Studio oder Asciidoctor. Die Sprache AsciiDoc wurde 2002 von Stuart Rackham entwickelt. Eine Neuimplementierung ist Asciidoctor, welches seit 2013 won Dan Allen entwickelt wird. Seit 2020 arbeitet die Eclipse Foundation, mit der AsciiDoc Working Group an der Standardisierung von AsciiDoc.

Asciidoctor

Ist ein Kommandozeilen-Werkzeug zum Parsen vonAsciiDoc-Dateien und deren Konvertierung in Ausgabeformate wie HTML, PDF usw. – im Grunde ein ähnliches Programm wie adoc Studio, aber ohne die Projektintegration, ohne Editor, ohne Textvervollständigung und ohne Vorschau. Asciidoctor ist OpenSource und wird seit 2013 von Dan Allen entwickelt und gepflegt.

Attribut

Werden in AsciiDoc verwendet, um Dokumente zu konfigurieren und Variablen zu speichern. Ein Dokumentattribut ist ab der Definition im Dokument verfügbar. Manche Attribute müssen aber am Anfang eines Dokuments stehen. Attributeinträge werden auch häufig zum Umschalten von Funktionen verwendet. Ein Attributeintrag besteht aus zwei Teilen: einem Attributnamen und einem Attributwert.

Attributliste (oder auch attrlist)

Die Definition von Attributen, die für ein Element verwendet wird, wird als attrlist bezeichnet. Eine Attributliste ist immer von einem Paar eckiger Klammern umgeben. Dies gilt sowohl für Elementattribute als auch für Attribute in einem Block oder Inline-Makro.

Auszeichnungssprache

Eine Auszeichnungssprache ist eine maschinenlesbare Sprache für die Gliederung und Formatierung von Texten und anderen Daten. Der bekannteste Vertreter ist die Hypertext Markup Language (HTML), die Kernsprache des World Wide Webs.

Autor

Der Verfasser eines Dokuments. Er kann in AsciiDoc Dokumenten unter dem Titel angegeben werden und wird automatisch im Attribut :author: gespeichert. Zusätzlich sind weitere Attribute im Zusammenhang mit dem Autor möglich.

B

Benutzerdefiniertes Attribut

Ist ein vom Autor definiertes Dokumentattribut, das zum Speichern wiederverwendbarer Inhalte und zur Steuerung der bedingten Einbindung verwendet wird.

Bibliografie (oder Bibliographie)

Ist ein eigenständiges Verzeichnis von Literaturnachweisen bzw. die Erstellung oder die Lehre von der Erstellung eines solchen Verzeichnisses. In adoc Studio kann sie im Büchern und Artikeln eingesetzt werden.

Block

Legen in einem AsciiDoc-Dokument die Struktur des Dokuments fest. Einige Blöcke können andere Blöcke enthalten, so dass die Dokumentstruktur von Natur aus hierarchisch ist (d.h. eine Baumstruktur). Sie können diese Blockstruktur in der Vorschau sehen, indem Sie z.B. das automatische Inhaltsverzeichnis aktivieren. Beispiele für Blöcke sind Absätze, Abschnitte, Listen, abgegrenzte Blöcke, Tabellen und Hinweise.

Blockname

Verweist auf benutzerdefinierte Blöcke, die einen beliebigen Namen einem oder mehreren Kontexten zuordnen können. Er hat eine ähnliche Funktion wie der Stil für einen eingebauten Block, z.B. einen Hinweis-Block.

Blockstil

Ist eine Zusatzinformation, die den Kontext eines Blocks spezialisiert. So kann ein Source-Block zusätzlich mit der Sprache des verwendeten Source ergänzt werden.

Bold

siehe Fett

Boolesches Attribut

Ist ein eingebautes Attribut, das wie ein Umschalter funktioniert. Es kann nur zwei Zustände angeben: wahr oder falschan oder aus. Der Nutzen besteht also darin, eine Funktion oder ein Verhalten zu aktivieren.

Buch

Baut auf dem Doctype Artikel auf und bietet zusätzlich die Möglichkeit, einen Top-Level-Titel als Teiltitel zu verwenden. Es enthält den Anhang, die Widmung, das Vorwort, die Bibliographie, das Glossar, den Index und das Kolophon. Ein Buch kann entweder nur Kapitel, oder zusätzlich verschiedene Teile enthalten, die wiederum ein oder mehrere Kapitel enthalten können.

C

CLI

Ist die Abkürzung für die Kommandozeile (engl.: command-line interface). Häufig wird diese auch als Befehlszeile, Konsole oder Terminal bezeichnet. Man versteht darunter einen Eingabebereich für die Steuerung einer Software. Dies findet typischerweise im Textmodus statt.

CSS (Cascading Style Sheets)

Ist ein Satz von Anweisungen oder eine Vorlage mit Einstellungen zur Gestaltung eines Dokuments. Durch unterschiedliche CSS kann ein Dokument oder eine Webseite gleichen Inhalts völlig anders dargestellt werden. In adoc Studio werden sowohl HTML als auch PDF mit CSS gestaltet. Zusätzlich können eigene .css-Dateien in ein Projekt übernommen und per :stylesheet: eingebunden werden.

D

DocBook

Ist ein Dokumentenformat, das in einer für SGML und XML vorliegenden Dokument-Typ-Definition (DTD) festgelegt ist. Es eignet sich zur Erstellung von Büchern, Artikeln und Dokumentationen im technischen Umfeld (Hardware oder Software). DocBook ist ein offener Standard, der von der Organization for the Advancement of Structured Information Standards (OASIS) gepflegt wird.

Dokument (oder auch alleinstehendes Dokument)

Eine Datei in adoc Studio nennen wir Dokument. Es liegt im reinen Textformat vor. Ein Dokument kann aus einem einzigen Satz (oder sogar einem einzigen Zeichen, um akademisch zu sein) bestehen.

Dokumentattribut

Werden verwendet, um entweder das Verhalten im Prozessor zu konfigurieren oder Informationen über das Dokument und seine Umgebung zu übermitteln. Eine Ergänzung zu den Dokumentattributen sind die Elementattribute. Es gibt eingebaute und benutzerdefinierte Attribute.

Docs as Code (Dokumentieren wie Programmieren)

Bezieht sich auf die Philosophie, dass man die Dokumentation mit den gleichen Mitteln wie den Programmcode einer Software schreiben sollte. Das bedeutet, dass die gleichen Arbeitsabläufe wie Entwicklungsteams zu befolgen und in das Produktteam zu integrieren sind. So wird eine Kultur ermöglicht, in der sich sowohl Autoren als auch Entwickler für die Dokumentation verantwortlich fühlen und gemeinsam daran arbeiten, sie so gut wie möglich zu gestalten.

Dokumentkopf (Document Header)

Ein AsciiDoc-Dokument beginnt mit einem Dokumentkopf. Der Dokumentkopf kann den Dokumenttitel, Autoren- und Revisionsinformationen, dokumentweite Attribute und andere Metadaten zum Dokument enthalten. Weiterhin müssen im Dokumentenkopf alle Dokumentattribute definiert sein.

Dokumententyp (Doctype)

Legt die erwartete Struktur eines AsciiDoc-Dokuments fest. In adoc Studio werden Artikel (als Standard) und Bücher angeboten.

E

Editor

Ist ein Programm(-teil) für die Erstellung und Modifikation von Texten. In adoc Studio ist der Editor im mittleren Fensterbereich angeordnet. Er bietet Spezialfunktionen, wie die intelligente Textvervollständigung, um beim Schreiben zu unterstützen. Der Editor kann in adoc Studio durch in einer Programm-Einstellung gestaltet werden.

Eingebautes Attribut

Ist ein Dokumentattribut für die Verarbeitung des AsciiDoc-Dokuments. Es kann die Integration, das Styling, die Lokalisierung und mehr steuern.

Element

Ist ein identifizierbarer Teil des Inhalts in einem Dokument. Ein AsciiDoc-Dokument ist immer eine Komposition aus allen darin enthaltenen Elementen.

Elementattribut

Definieren die integrierten und benutzerdefinierten Einstellungen und Metadaten. Sie können auf ein einzelnes Blockelement oder Inline-Element in einem Dokument (einschließlich Makros) angewendet werden.

Encoding

Die meisten AsciiDoc-Verarbeiter – wie auch adoc Studio – gehen davon aus, dass der Text in der Datei die Kodierung UTF-8 verwendet. Kodierungen in UTF-16 werden nur unterstützt, wenn die Datei mit einem BOM beginnt.

Ermahnung

siehe Hinweise

Export

Die Ausgabe einer adoc-Datei erfolgt in einem Format, wie HTML oder PDF. Ein Export kann eigene Stile und Attribute haben, die entweder im AsciiDoc-Dokument, oder im Export-Dialog vergeben werden. Die Ausgabe kann in eine Datei erfolgen und optional direkt mit anderen Programmen geteilt werden.

F

Feste Zeilenumbrüche

Da benachbarte Textzeilen in AsciiDoc bei der Konvertierung zu einem Absatz zusammengefasst werden, können Sie jeden Satz oder jede Phrase in eine eigene Zeile setzen. Die Zeilenumbrüche werden in der Ausgabe nicht angezeigt. Um Absätze voneinander zu trennen, genügt eine zusätzliche Leerzeile. Dieses Verfahren wird gerne im Arbeitsprinzip Doc as Code angewandt. Wenn Sie jedoch möchten, dass die Zeilenumbrüche in einem Absatz erhalten bleiben, können Sie ein Leerzeichen gefolgt von einem Pluszeichen (+) verwenden oder die Option "Harte Umbrüche" für den Absatz einstellen.

Fett

Bei fett gedruckter Text hebt sich das Gewicht eines Texts mit einer dickeren und/oder dunkleren Schriftart vom normalen Text ab. Das Formatierungszeichen für Fettdruck ist ein Sternchen * vor und hinter dem Wort (Tastatur: ++).

Formatierungszeichen und -paare

Eine Formatierungsmarke ist ein symbolisches Zeichen wie *, _ oder ~, das den Inline-Stil angibt, den der AsciiDoc-Konverter auf den Text anwenden soll. Formatierungszeichen gibt es immer in Paaren. Ein Formatierungspaar besteht aus einem identischen öffnenden und schließenden Zeichen, das den zu formatierenden Text umschließt. Der formatierte Text (d.h. der von einem Formatierungspaar umschlossene Text) kann sich über mehrere, zusammenhängende Zeilen erstrecken. Die Anfangsmarke gibt an, wo die Formatierung beginnen soll. Die Schlussmarkierung gibt an, wo die Formatierung enden soll.

G

GIT

Git ist eine freie Software zur verteilten Versionsverwaltung von Dateien, die 2005 durch Linus Torvalds initiiert wurde. Alle Texte und Medien aus adoc Studio können in einem Git Repository versioniert werden.

Gliederung

Eine Gliederung ist die Aufteilung eines Ganzen in mehrere strukturelle Teile oder Bereiche, die in sich weitgehend abgeschlossen sind, aber aus dem Ganzen als Einheit nicht entfernt werden können, ohne dieses unvollständig zu machen. adoc Studio enthalt mehrere Gliederungen: Der Dateinavigator und Abschnittsnavigator in der Seitenleiste, die Überschriftsstruktur über dem Editor und weitere.

Glossar

Ein Glossar ist eine Liste von Wörtern mit beigefügten Bedeutungserklärungen oder Übersetzungen. Als Anhang eines Werkes wird ein Glossar auch als Wörterverzeichnis bezeichnet, ein eigenständiges Glossar als Wörterbuch. Übrigens lesen Sie gerade im Glossar von adoc Studio.

H

Handbuchseite

Eine Handbuchseite (engl. man page), ist eine textorientierte Form der Softwaredokumentation, die üblicherweise Software auf UNIX und Unix-artigen Betriebssystemen begleitet. Ihre formalisierte Struktur ermöglicht es dem man-Befehl, ein formatiertes Dokument in einem Terminal darzustellen. Verfassen Sie eine Handbuchseite in AsciiDoc, hat das den Vorteil, dass Sie sie in mehrere Formate konvertieren können, darunter HTML und PDF. Das macht die Quelle der Handbuchseite wiederverwendbar. Die Konvertierung zu man pages ist in adoc Studio noch nicht implementiert.

Header-Attribut

Ein Header-Attribut ist ein Dokumentattribut, das im Kopfbereich eines Dokuments definiert ist. Es ist von allen Knoten im Dokument aus sichtbar und wird oft für globale Attribute benötigt, z.B. für den Icon-Modus: :icons: font.

Hervorhebung

siehe Markierung

Hinweis (engl. Admonition)

Mit Hinweisen lenken Sie die Aufmerksamkeit auf bestimmte Aussagen, indem Sie den Block oder Absatz aus dem Fluss des Inhalts herausnehmen. Mit einem von fünf Typen (NOTE, TIP, IMPORTANT, CAUTION, WARNING) definieren Sie die Darstellung. Ein Hinweis kann als Absatz oder als Absatz definiert werden.

Hochgestellt (engl. superscript)

Hochgestellter Text wird häufig in mathematischen Ausdrücken und chemischen Formeln verwendet. Das Formatierungszeichen für hochgestellte Schrift ist ein Caret (^).

HTML

Die Hypertext Markup Language (HTML) ist eine textbasierte Auszeichnungssprache zur Strukturierung elektronischer Dokumente wie Texte mit Hyperlinks, Bildern und anderen Inhalten. HTML-Dokumente sind die Grundlage des World Wide Web und werden von Webbrowsern dargestellt.

I

ID-Attribut oder Anker

Mit einem Anker können Sie einem Block- oder Inline-Element einen Identifikator (d.h. einen eindeutigen Namen) zuweisen. Es dient dazu, das Element bei der Verknüpfung als Sprungziel oder der Gestaltung zu identifizieren.

Index

Sie können Indexbegriffe in AsciiDoc-Inhalten explizit markieren. Indexbegriffe bilden ein kontrolliertes Vokabular, mit dem Sie ausgehend von einem Index nach Stichworten im Dokument navigieren können.

Inhaltsmodell

Das Inhaltsmodell eines Blocks bestimmt, welche Art von Inhalt der Block haben kann und wie dieser Inhalt verarbeitet wird (z.B. einfach, zusammengesetzt, wortwörtlich, unbearbeitet, usw.).

Inline

Der Inline-Doctype ermöglicht es dem AsciiDoc-Prozessor, die gesamte Bandbreite an Anwendungen abzudecken, von unstrukturiertem (Inline-)Text bis hin zu vollständigen, eigenständigen Dokumenten.

Inline-Element

Ein Inline-Element ist eine Phrase (d.h. eine Inhaltsspanne) innerhalb eines Blockelements oder eines seiner Attribute in einem AsciiDoc-Dokument. Sie werden zur Formatierung von Text und zur Durchführung verschiedener Arten von Textersetzungen verwendet. Inline-Elemente und die Syntax von Inline-Elementen werden in den Konfigurationsdateien definiert. Die Konvertierung von Inline-Dokumenten ist in adoc Studio noch nicht implementiert.

Italic

siehe Kursiv

Integrierte Schreibumgebung (Integrated Writing Environment – kurz: IWE)

Ist eine Software, die umfassende Schreib- und Wissensmanagement-Funktionen für Autoren und Informationsmitarbeiter bietet. So auch adoc Studio. IWEs ermöglichen es Autoren und Informationsmitarbeitern, eine Vielzahl von Aufgaben im Zusammenhang mit dem Dokument in der IWE in einer einzigen Umgebung durchzuführen. Im optimalen Fall werden auch Prinzipien, wie Docs as Code unterstützt. Dies sorgt für einen ablenkungsfreien Arbeitsbereich und eine optimierte Schreibumgebung.

J

K

Kapitel

Ist eine inhaltlich trennende Unterteilung in Texten. In adoc Studio sprechen wir bei den Dateien in Sammeldokumenten von Kapiteln.

Keywords

Das Attribut :keywords: enthält eine Liste von durch Kommata getrennten Werten, die dem HTML <meta>-Element zugewiesen werden.

Kodierung

siehe Encoding

Kolophon (auch Subskription)

Ist ein Element eines Buches und steht in der Regel am Schluss. Enthalten sind Informationen unter anderem über Inhalt, Verfasser, Ort, Zeit, Hersteller, Auftraggeber und Produktionsdetails der Veröffentlichung.

Konverter

Ist eine Softwarekomponente, die ein AsciiDoc-Prozessor aufruft, um ein AsciiDoc-Dokument in ein bestimmtes Ausgabeformat zu konvertieren.

Kursiv (engl. Italic)

Text wird oft kursiv gesetzt, um ein Wort oder einen Satz zu betonen, einen Sprecher zu zitieren oder einen Begriff einzuführen. Kursive Schrift ist leicht nach rechts geneigt und kann, je nach Schriftart, kursive Schwünge und Schnörkel aufweisen. Das Formatierungszeichen für kursiv ist ein Unterstrich (+-).

L

M

Makro

Ist eine Syntax zur Darstellung von Nicht-Text-Elementen oder einer Syntax, die sich mithilfe der bereitgestellten Metadaten in Text verwandelt. Siehe Makro, um mehr über die Bedeutung dieses Begriffs zu erfahren.

Makro-Attribut

Ist ein Attribut, das mit einem Block- oder Inline-Makro verbunden wird. Diese Attribute können die Verarbeitung des Makros beeinflussen, können aber nicht über eine Attributreferenz referenziert werden.

Manual page (man-page)

siehe Handbuchseite

Markdown

Eine vereinfachte Auszeichnungssprache, die im Dezember 2004 von John Gruber und Aaron Swartz veröffentlicht wurde.

Markierung

Eine weitere Möglichkeit, die Aufmerksamkeit auf Text zu lenken, ist es diesen durch eine Markierung hervorzuheben. Dieser semantische Stil wird zu Referenz- oder Notationszwecken verwendet oder um die Bedeutung eines wichtigen Themas oder Punktes hervorzuheben. Das Formatierungszeichen für Markierung ist eine Raute # (#).

Medienordner

In adoc Studio hat der Medienordner einige besondere Funktionen. Wird er selektiert, werden alle enthaltenen Medien als Vorschau angezeigt. Es können beliebig viele Medienordner angelegt werden.

Metadaten

Sind strukturierte Daten, die übergreifende Informationen über eine Ressource - wie Bücher, Webdokumente, Videos oder Bilder - beinhalten. Auf ein Dokument bezogen sind es z.B. eine Beschreibung des Dokuments, Schlüsselwörter und benutzerdefinierte Informationen, die als Attribute im DokumentenKopf zugewiesen werden können. Bei der Konvertierung in HTML entsprechen die Werte dieser Attribute den Elementen, die im <head>-Abschnitt eines HTML-Dokuments enthalten sind.

Monospace

Bei technischen Inhalten muss der Text oft so gestaltet werden, dass er auf einen Befehl oder einen Quellcode hinweist. Solcher Text wird in der Regel mit einer Schriftart mit fester Breite (d.h. Monospace) hervorgehoben. Das Formatierungszeichen für Monospace ist ein Backtick ` (+´).

N

O

Ordner

Ist ein Verzeichnis innerhalb einer Datenstruktur. In adoc Studio können beliebig viele Ordner – auch verschachtelt – angelegt werden. In Sammeldokumenten kann ein Ordner selektiert werden um die darin enthaltenen Kapitel in der Vorschau kombiniert anzuzeigen.

P

Parser

Ein Parser ist ein Computerprogramm, das in der Informatik für die Zerlegung und Umwandlung einer Eingabe in ein für die Weiterverarbeitung geeigneteres Format zuständig ist. Für technisch interessierte: Der Parser in adoc Studio ist nach Vorbild von AsciiDoc in Swift geschrieben. Es ist eine Migration, keine Kopie oder direkte Portierung.

PDF (Portable Document Format)

Ist ein plattformunabhängiges Dateiformat, das 1992 von Adobe Inc. entwickelt und veröffentlicht wurde. Elektronische Dokumente in diesem Dateiformat können unabhängig vom ursprünglichen Anwendungsprogramm, vom Betriebssystem oder von der Hardwareplattform originalgetreu wiedergegeben werden.

Plaintext

Bezeichnet in der IT die Daten, die ohne eine Formatierung versehen, menschenlesbar sind und daher unmittelbar unter Verwendung von Schriftzeichen in Text umgesetzt werden können. Die AsciiDoc-Dokumente in adoc Studio verwenden Plaintext.

Präambel

Ist der Inhalt zwischen dem Ende des Dokumentenkopfs und dem ersten Abschnittstitel im Dokumentenkörper. Eine Präambel ist in AsciiDoc optional.

Präprozessoranweisung

Ist eine Funktion, die die Zeilen steuert, die in den Parser eingegeben werden. Eine bedingte Präprozessoranweisung kann Zeilen so konfigurieren, dass sie aufgrund des Vorhandenseins eines Attributs (ifdef, ifndef) oder einer anderen beliebigen Bedingung (ifeval) einbezogen oder ausgeschlossen werden. Eine Include-Direktive kann dem Dokument zusätzliche Zeilen hinzufügen, die aus einem anderen Dokument stammen.

Preprocessor Directive

siehe Präprozessoranweisung

Produkte

Sind eine logische Zusammenfassung vieler Exports. Innerhalb eines Produktes können viele Exporte angelegt werden, die wiederum eigene Stile und Attribute und Ausgabeformate haben können.

Produktstile

In adoc Studio ist Text von der Gestaltung getrennt. Also muss eine Technik beide miteinander verbinden. Diese Aufgabe erfolgt mithilfe der Produktstile. Ein Produktstil ist ein Datei-Bundle, in dem sich mindestens neben einer Informationsdatei, die Stildatei im CSS-Format befindet. Optional können weitere Ressourcen wie Medien oder Schriften enthalten sein.

Projekt

Ist in adoc Studio eine Zusammenfassung aller AsciiDoc-Dateien und Ordner, inkl. der Medienordner. Zusätzlich können Projekte auch weitere Dateien, wie CSS-Dateien und andere, enthalten. Es wird in adoc Studio über den Projekt-Navigator organisiert und verwaltet. Zusätzlich findet mit dem Verzeichnis im Betriebssystem einen stetige Synchronisierung statt. So kann das Projekt auch im Finder modifiziert werden.

Q

Quelltext

Ist ein für Menschen lesbarer in einer Programmiersprache geschriebener Text eines Computerprogramms. In dem Arbeitsprinzip Docs as Code wird der AsciiDoc-Text auch oft als Quelltext bezeichnet.

R

Rolle

Blöcken und den meisten anderen Inline-Elementen können mit dem Attribut role eine oder mehrere Rollen zuweisen. Eine Rolle fügt einem Element zusätzliche Semantik hinzu, um zum Beispiel einen zusätzlichen Stil zu vergeben (über einen CSS-Selektor).

RTF (Rich Text Format)

Ist ein proprietäres Dateiformat für Texte, das 1987 von Microsoft eingeführt wurde. Es kann als Austauschformat zwischen Textverarbeitungsprogrammen verschiedener Hersteller auf verschiedenen Betriebssystemen dienen. In adoc Studio kann die Vorschau auf Text eingestellt werden, was dem Rich Text Format entspricht. Auch für den Export und innerhalb der Produkte ist dieses Format wählbar.

S

Sammeldokument

Ist in adoc Studio eine eigene Dokumentart und steht im Kontrast zu den alleinstehenden Dokumenten. Sie sammeln viele Kapitel zu einem großen Dokument. Es können innerhalb eines Sammeldokuments viele Ordner und Medienordner für die weitere Strukturierung angelegt werden. Alle Ordner können selektiert werden, um die darunter liegenden Kapitel in der Vorschau kombiniert darzustellen. Attribute, die irgendwo im Sammeldokument definiert wurden, können in jedem Kapitel des Sammeldokuments verwendet werden.

Schlüsselwörter

siehe Keywords

Section

siehe Abschnitt

Stylesheet

Ist am ehesten mit einer Formatvorlage zu vergleichen. Grundidee hierbei ist die Trennung von Text und Darstellung. Das Programm, das das Stylesheet auswertet, interpretiert die zugewiesenen Daten (Text, Tabellen, Grafiken etc.) und formatiert sie nach den vorgegebenen Regeln. Die Cascading Stylesheets sind wohl das bekannteste Beispiel für ein Stylesheet. In adoc Studio können eigene Stylesheets als .css-Dateien in das Projekt gelegt und mit dem Attribut :stylesheet: genutzt werden.

Syntax

Man versteht im allgemeinen darunter ein Regelsystem zur Kombination verschiedener Zeichen, die zu einem natürlichen oder künstlichen Systemen zusammengesetzt werden. Die Regeln der Syntax stehen hierbei den Interpretationsregeln der Semantik gegenüber. Der Befehlsumfang einer Sprache, wie AsciiDoc, wird gerne als Syntax bezeichnet.

T

Teil (engl. Part)

Im Sinne eines mehrteiligen Buchs ist ein Teil eine zusätzliche Unterteilung. Ein Teil kann wiederum eigene Kapitel oder Anhänge enthalten.

Text

Umgeben von den Markierungen, Begrenzungszeichen und Metadatenzeilen befindet sich der Text. Der Text ist der Schwerpunkt eines Dokuments und der Grund, warum die AsciiDoc-Syntax ihm so viel Raum zum Atmen gibt. Text findet sich am häufigsten in den Zeilen eines Blocks (z. B. Absatz), im Blocktitel (z. B. Abschnittstitel) und in Listenelementen, aber auch an anderen Stellen. Text unterliegt Ersetzungen. Ersetzungen interpretieren Markup als Textformatierung, ersetzen Makros durch Text oder Nicht-Text-Elemente, erweitern Attributreferenzen und führen andere Arten von Textersetzungen durch. Normaler Text unterliegt allen Ersetzungen, sofern nicht anders angegeben. Wörtlicher Text unterliegt einem minimalen Satz von Ersetzungen, damit er in der Ausgabe so angezeigt werden kann, wie er im Quelltext erscheint. Es ist auch möglich, alle Ersetzungen zu deaktivieren, um den Text unverändert (d. h. unbearbeitet) an die Ausgabe weiterzugeben. Das Parsen des Textes besteht aus einer Mischung von Inline-Elementen und anderen Formen von Transformationen.

Textformatierung

AsciiDoc stellt eine Reihe von Formatierungszeichen zur Verfügung, mit denen Sie Ihr Dokument optisch hervorheben und typografische Interpunktion verwenden können. Sie können auf diese grundlegenden Formatierungszeichen mit Hilfe von integrierten und benutzerdefinierten Rollen aufbauen. Beispiele sind: fett, kursiv, hervorheben usw.

Textvervollständigung (intelligente oder automatische)

Eine Technik, die nach der Eingabe von zwei bis drei Buchstaben im Editor erkennt, dass an der aktuellen Schreibposition zum Kontext passende Attribute, Makros oder anderes möglich ist. Wichtig ist dabei, dass der Mensch im Schreifluss nicht blockiert, sonder nur unterstützt wird. Sie wird auch gerne zur Zeitersparnis eingesetzt.

Tiefgestellt (engl. subscript)

Tiefgestellter Text wird häufig in mathematischen Ausdrücken und chemischen Formeln verwendet. Das Formatierungszeichen für tiefgestellt ist eine Tilde ~ (+n).

U

Umgebungsattribut

Ein Umgebungsattribut ist ein dynamisches Dokumentattribut, das sich auf die Laufzeitumgebung bezieht oder Informationen darüber liefert.

UTF-8

siehe Encoding

V

Versionsverwaltung

Eine Versionverwaltung dient dazu mehrere Versionen eines Dokumentes platzsparend zu verwalten. Bei den meisten Versionsverwaltungssystemen wird neben dem Originaldokument, nur noch die Änderungen gespeichert, die notwendig sind um eine bestimmte Version zu erzeugen. Ausserdem wird durch eine Versionsverwaltung das gemeinsame Arbeiten an ein und demselben Dokument ermöglicht.

Vordefiniertes Attribut

Ein vordefiniertes Attribut ist ein Dokumentattribut, das aus Gründen der Bequemlichkeit definiert wurde. Es wird oft zum Einfügen von Sonderzeichen für den Inhalt verwendet.

Vorschau

In der Vorschau stellt adoc Studio alle Inhalte vom Editor in verschiedenen Formaten dar. Es steht HTML, PDF und RTF Text zur Verfügung. Jedes Ausgabeformat kann mit einem Stil formatiert werden.

Vorwort

Ein Vorwort ist ein besonderer Abschnitt, der dem ersten Kapitel eines Buches oder eines Buchteils vorausgeht. In AsciiDoc ist das Vorwort ein eigener Blocktyp, der vorzugsweise in Büchern verwendet wird.

W

Widmung

Wird verwendet, um Dankbarkeit gegenüber Dritten auszudrücken. In AsciiDoc ist die Widmung ein eigener Blocktyp, der vorzugsweise in Büchern verwendet wird.

X

Y

Z

Zeile

AsciiDoc ist eine zeilenorientierte Sprache, daher ist die Zeile ein wichtiges Konstrukt. Eine Zeile ist definiert als Text, der auf beiden Seiten entweder durch einen Zeilenumbruch oder durch die Begrenzung des Dokuments getrennt ist. Viele Aspekte der Syntax müssen eine ganze Zeile einnehmen. Bei arbeiten nach Docs as Code, ist die einzelne Zeile besonders wichtig, da auf ihr Änderungen in einem Git einfacher erkannt werden.

Zitat, zitierter Text

Text, der von einer speziellen Interpunktion umgeben ist, um andere Autoren zu zitieren, oder dem Text eine besondere Bedeutung zu verleihen.

Zusammenfassung

siehe Abstract


1. Hier ist der Text der Fußnote