Ohne Titel

Dieses Dokument begleitet Sie auf dem direkten Weg in die Arbeit mit adoc Studio. Es erklärt den Aufbau der App, stellt die wichtigsten Befehle vor und gibt viele Hinweise für den tieferen Einstieg in die Dokumentation mit adoc Studio.

Zusätzlich gibt Ihnen der Quelltext dieser Dokumentation ein Beispiel für den Aufbau eines Projekts in adoc Studio. Das Benutzerhandbuch lässt sich über das Hauptmenü Hilfe Benutzerhandbuch aufrufen.

Notation in diesem Dokument

Im Text finden Sie folgende Symbole und ihre Bedeutungen:

Ergänzende Anmerkungen werden Ihnen als Notiz dargestellt.

Besondere Hinweise werden Ihnen als Tipp angezeigt.

Die Glocke weist Sie auf Besonderheiten hin.

Dieser Hinweis erscheint, wenn Ihre besondere Aufmerksamkeit erforderlich ist.

Achtung! Dieses Symbol informiert Sie über mögliche Gefahren, Schäden oder Konsequenzen.

Sie erkennen Menübefehle an der Struktur des Menüs, zum Beispiel: Ablage Export Produkte…. Falls es einen Tastaturkurzbefehl gibt, wird dieser folgendermaßen dargestellt: ⌘+⌃+E.

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 stammen, dient ausschließlich Informationszwecken und stellt keine Werbung dar. ProjectWizards übernimmt keine Gewähr hinsichtlich der Auswahl, Leistung oder Verwendbarkeit dieser Produkte.

Was ist adoc Studio?

Mit adoc Studio erstellen Sie technische Dokumentationen effizient und mühelos. Die App unterstützt Sie bei der Erstellung umfangreicher und strukturierter Dokumente. Nach dem Start blinkt der Cursor im Editor, und jedes Wort, das Sie schreiben, erscheint sofort rechts daneben in der Vorschau. Diese intuitive Arbeitsweise sorgt für eine hohe Produktivität. Ob auf dem Mac, dem iPad oder dem iPhone, Sie haben stets eine einheitliche und benutzerfreundliche Ansicht.

adoc Studio nutzt eine integrierte Schreibumgebung, die auf der Auszeichnungssprache AsciiDoc basiert und Dokumente in HTML und PDF erzeugt.

Auszeichnungssprache: Die meisten kennen Microsoft Word oder einen anderen Texteditor. Im Gegensatz dazu haben sich in den letzten Jahren Auszeichnungssprachen wie Markdown stark verbreitet. Diese präsentieren das Ergebnis nicht mehr wie Microsoft Word oder Apple Pages in einer druckähnlichen Vorschau. Stattdessen müssen sie übersetzt werden, was unterschiedlich viel Aufwand erfordert.
AsciiDoc: adoc Studio basiert auf AsciiDoc, einer etablierten Auszeichnungssprache. Die Entscheidung der Eclipse-Foundation, den Sprachumfang von AsciiDoc zu standardisieren, gewährleistet eine zukunftssichere Wahl. Wir haben uns für AsciiDoc entschieden, weil es sowohl für Einsteiger leicht zu erlernen ist als auch Profis einen umfangreichen Befehlssatz bietet.
Integrierte Schreibumgebung: Eine effiziente und benutzerfreundliche Arbeitsumgebung erfordert ein Programm, das alle notwendigen Funktionen integriert. Mit geben adoc Studio können Sie Texte ein, eingeben, diese in in Projekten organisieren, eine Vorschau zur ersten Überprüfung nutzen und die fertigen Dokumente entweder einzeln oder als gesamte Produkte exportieren.

adoc Studio bietet umfassende Anpassungsmöglichkeiten. Sie können das Aussehen des Editors bestimmen und einen Ausgabe-Stil wählen. Wir stellen Ihnen einige Stile zur Verfügung und veröffentlichen regelmäßig weitere auf unserer Webseite.

Mit adoc Studio Mit adoc Studio konzentrieren Sie sich vollständig auf die Struktur und den Inhalt Ihrer Dokumente. Sie haben die Möglichkeit, wichtige Aussagen zu betonen und Hervorhebungen vorzunehmen. Zudem unterstützt die App die Verwendung von Emojis 🙂

Was ist eine Auszeichnungssprache?

Historisch stammt der Begriff Auszeichnung aus der Typografie. In der Druckkunst bezeichnete er das Hervorheben von Textteilen durch abweichende Schriftvarianten wie kursive und fette Schriftschnitte, Kapitälchen, Versalien (GROßBUCHSTABEN), Sperren, Unterstreichen oder Einfärben des Textes sowie durch verschiedene Schriftgrößen und -arten. Auch das handschriftliche Kenntlichmachen entsprechender Stellen im Manuskript gehörte dazu (aus [Wikipedia](https://de.wikipedia.org/wiki/Schriftauszeichnung)). Diese Techniken wurden sinngemäß in die Computerzeit und Software übernommen, wodurch moderne Auszeichnungssprachen entstanden.

Sie haben vielleicht schon von der Sprache Markdown gehört oder den Satz „der Text ist in Markdown geschrieben". Damit sind Sie auf dem richtigen Weg. Zum einen liegt reiner Text vor, also Buchstaben ohne Formatierung. Zum anderen gibt es Markierungen, die den Text besonders auszeichnen: was eine Überschrift ist, was fett, kursiv oder ein Link ist und so weiter.

Es existieren zahlreiche Auszeichnungssprachen, die nicht mit Textverarbeitungsprogrammen wie Microsoft Word zu verwechseln sind. Die drei bekanntesten Vertreter von Auszeichnungssprachen umfassen:

HTML, die Sprache des Internets, ist sehr verbreitet, aber auch oft als umständlich empfunden.
TeX bzw. LaTeX, das wohl populärste Satzsystem für wissenschaftliche Artikel, ist im Geschäftsleben eher selten anzutreffen und gilt als schwer zu erlernen.
Markdown ist sehr einfach zu nutzen, jedoch zu simpel, da es an vielen Funktionen für technische Dokumentation mangelt. Ein detaillierter Vergleich von Markdown und AsciiDoc bietet weitere Einblicke.

Aufgrund der Nachteile der oben aufgeführten Sprachen fiel die Entscheidung auf AsciiDoc als Auszeichnungssprache. Bei ProjectWizards entstehen seit 2007 alle Handbücher und öffentlichen Dokumente in diesem Format.

AsciiDoc ist eine ausgereifte, leichtgewichtige und semantische Auszeichnungssprache, die hauptsächlich zum Erstellen technischer Dokumentation entwickelt wurde. Sie eignet sich ideal für alle strukturierten Texte. Die beeindruckende Anzahl von über 10 Millionen Downloads (Quelle: Asciidoctor History) verdeutlicht, dass stets Hilfe verfügbar ist. Diese Anerkennung gebührt Asciidoctor, dem ersten Parser von AsciiDoc-Texten.

Ein Parser ist ein Programm, das Textdaten analysiert, in strukturierte Komponenten zerlegt und auf syntaktische Korrektheit überprüft, um sie weiterverarbeiten zu können.

Betrachtung von Word, Pages oder Google Docs

Bezüglich der Wahl zwischen adoc Studio und WYSIWYG-Textverarbeitungsprogrammen wie Microsoft Word, Apple Pages oder Google Docs ergeben sich diverse Gründe:

Die Abkürzung "WYSIWYG" ist seit den 90er Jahren weit verbreitet und steht für "What you see is what you get" in ihrer vollen Form. Dies beschreibt die Ausgabe von Dokumenten, die genau so erfolgen soll, wie sie am Bildschirm dargestellt sind. Mit anderen Worten: Was du siehst, ist das, was du bekommst.

Trennung von Inhalt und Darstellung: Textbasierte Markup-Sprachen ermöglichen die klare Trennung von Inhalt und Darstellung. Dies gewährleistet eine konsistente Formatierung über verschiedene Dokumente hinweg und erleichtert die einheitliche Anpassung des Erscheinungsbilds von Dokumenten. Ein Dokument, das in einer Markup-Sprache verfasst ist, kann auf jedem Computer ohne spezielle Software geöffnet werden.
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 bereits sehr unterschiedlich aussehen.
Versionskontrolle: Markup-Sprachen sind mit Versionskontrollsystemen wie Git kompatibel, was die Zusammenarbeit und Nachverfolgung von Änderungen in großen Dokumenten erleichtert. Obwohl Word mittlerweile ein XML-Format eingeführt hat, weigern sich viele Administratoren noch, diese Dateien in ein Git einzuchecken.
Wiederverwendbarkeit: Ein Dokument in einer Markup-Sprache erstellt kann in verschiedene Formate konvertiert werden, wie 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 unterschiedlich.
Anpassungsfähigkeit: Textbasierte Markup-Sprachen ermöglichen eine sehr hohe Anpassungsfähigkeit. Sie ermöglichen die individuelle Anpassung des Aussehens und Verhaltens von Dokumenten auf eine Art und Weise, die in Standard-Textverarbeitungsprogrammen oft nicht möglich ist.
Automatisierung: Automatisierte Skripte und Tools können verwendet werden, um Dokumente in textbasierten Markup-Sprachen zu generieren, zu verarbeiten und zu manipulieren. Dies kann bei großen Dokumenten Zeit sparen und Fehler reduzieren.
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.

Installation

Sie laden adoc Studio aus dem entsprechenden App Store für Ihren Mac oder Ihr iPad bzw. iPhone. Wenn Sie diesen Text jetzt in adoc Studio lesen, ist das bereits erledigt. Gratulation!

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

Testphase & Lizenzierung

Ein Abonnement gewährt Ihnen Zugang zu beiden Versionen von adoc Studio, sowohl für den Mac als auch für iOS, also iPad und iPhone. Der Test startet beim ersten Start von adoc Studio.

Während des kostenlosen 14-Tage-Tests stehen Ihnen alle Funktionen zur Verfügung. Nach dem Testzeitraum können Sie ein monatliches oder jährliches Abonnement abschließen, wobei das jährliche Abonnement einen Preisvorteil bietet. Wenn Sie sich gegen ein Abonnement entscheiden, können Sie adoc Studio-Projekte weiterhin anzeigen, aber nicht mehr in der App bearbeiten.

Alle Textdateien werden im reinen Textformat (UTF-8 kodiert) gespeichert. Dies gewährleistet Ihre Datensicherheit während der Testphase. Falls erforderlich, lassen sich die Dateien in beliebigen Editoren, wie [BBEdit](https://www.barebones.com/products/bbedit/), weiter bearbeiten und mit anderen Prozessoren, wie [Asciidoctor](https://asciidoctor.org), übersetzen. Dies ist jedoch nur für den unwahrscheinlichen Fall gedacht, dass adoc Studio Sie nicht überzeugt.

adoc Studio kennenlernen

In diesem Kapitel erhalten Sie einen Überblick über die App und die Konzepte, die Ihnen die Bedienung erleichtern.

Die Benutzeroberfläche

Nach dem Start von adoc Studio sehen Sie eine Ansicht wie im folgenden Bild. Es zeigt das mit adoc Studio erstellte Benutzerhandbuch, das über das Hilfe-Menü aufgerufen wurde.

Das Fenster-Layout von adoc Studio gliedert sich in drei Bereiche:

Seitenleiste mit:
1. Projektnavigator für alle Dateien und Verzeichnisse (Tastaturkurzbefehl: ⌘+1)
2. Abschnittnavigator für das Inhaltsverzeichnis (Tastaturkurzbefehl: ⌘+2)
3. Suchnavigator für die Suche über alle Dateien (Tastaturkurzbefehl: ⌘+3)
4. Problemnavigator für alle Warnungen und Fehlermeldungen (Tastaturkurzbefehl: ⌘+4)
Texteditor
Vorschau

Am oberen Fensterrand befindet sich die Symbolleiste mit den folgenden Funktionen:

Seitenleiste ein- und ausblenden (Tastaturkurzbefehl: ⌘+0)
Neue Komponente anlegen (Tastaturkurzbefehl: ⌘+⇧+N)
Zurück- und Vorwärts-Schaltfläche für die Navigation (Tastaturkurzbefehl: ⌘+⇧+< und ⌘+⇧+>)
Verzeichnisbaum als Auswahlmenü
Inhaltsstruktur als Auswahlmenü
Optional: Liste aller Produkte
Editor ein- und ausblenden (mit oder Tastaturkurzbefehl: ⌘+⇧+E)
Vorschau ein- und ausblenden (mit oder Tastaturkurzbefehl: ⌘+⇧+E) inklusive der Einstellungen

Jeder Bereich kann individuell ein- und ausgeblendet werden, um eine optimale Anpassung an beliebige Bildschirmgröße zu ermöglichen. Die entsprechenden Funktionen finden Sie in den Menüs Darstellung, Editor und Vorschau.

Der Projektnavigator

In adoc Studio arbeiten Sie projektorientiert. Was bedeutet das konkret? Ein Projekt umfasst Ihren Text und gegebenenfalls die dazugehörigen Bilder. Mit zunehmender Textlänge wird es jedoch immer schwieriger, den Überblick zu behalten. Daher teilt man lange Texte gerne in kleinere Abschnitte auf, die in vielen einzelnen Dateien zusammen mit den Bildern liegen. Dies führt oft zu Unordnung und Verlust der Übersicht.

Um dieses Problem zu vermeiden, bietet adoc Studio das Sammeldokument an.

Dieses Kapitel erläutert den Umgang mit Projekten, Dateien und allen dazugehörigen Elementen.

Ein neues Projekt anlegen

Erstellen Sie in adoc Studio ein neues Projekt über das Menü Ablage Neu Projekt). In der Seitenleiste sehen Sie zunächst zwei Objekte:

einen Ordner für Medien
eine Datei für das Dokument

Ob die Dateiendung .adoc wie im Bild angezeigt wird, können Sie in den Einstellungen im Menü adoc Studio (Tastaturkurzbefehl: ⌘+,) festlegen.

Alle Objekte (Dateien und Ordner) in der Seitenleiste können bewegt werden. Sie können ineinander verschachtelt, neu strukturiert und angeordnet werden.

Medien und Bilder können an jeder Position im Projekt abgelegt werden. Es wird jedoch empfohlen, diese im Medienordnern zu sammeln. Falls der automatisch angelegte Medienordner nicht ausreicht, können Sie beliebig viele weitere Ordner in Ihrem Projekt erstellen.

Alleinstehende Dokumente verwenden

Im nächsten Schritt erweitern Sie Ihr Projekt und fügen ein alleinstehendes Dokument hinzu. Nutzen Sie dafür das Menü Ablage Neu, den Tastaturkurzbefehl ⌘+N oder das + in der Seitenleiste. Die Dokumente sind voneinander unabhängig und existieren eigenständig. Der Ablauf ist einfach und logisch:

Klicken Sie auf ein Dokument.
Es wird im Editor zur Bearbeitung angezeigt.
In der Vorschau sehen Sie den aktuellen Stand.

Wenn Sie auf ein anderes Dokument klicken, wird es im Editor angezeigt.

Das bedeutet, dass Sie die Inhalte des zweiten Dokuments Weiteres Dokument.adoc nicht in Dokument.adoc sehen und umgekehrt. Es gibt Techniken in AsciiDoc, um Inhalte aus anderen Dokumenten in einem Dokument anzuzeigen, wie z. B. die includes. Lesen Sie später mehr dazu.

Sammeldokumente verwenden

Sammeldokumente bieten im Gegensatz zu alleinstehenden Dokumenten eine strukturierte Zusammenführung mehrerer Dokumente. Wenn Sie Ihre Dokumente zu einem großen Dokument zusammenstellen, werden neu angelegte Dateien im Sammeldokument als Kapitel.adoc anstelle von Dokument.adoc benannt.

In einem Sammeldokument können Sie Ordner zur Strukturierung verwenden und diese beliebig tief verschachteln. Wenn Sie auf einen Ordner klicken, zeigt die Vorschau alle darin enthaltenen Kapitel zusammenhängend an. Je weiter Sie in der Hierarchie nach oben gehen, desto umfangreicher wird die Darstellung in der Vorschau.

Wenn der Fokus in der Seitenleiste auf einem Ordner liegt, bleibt der Editor leer. Um ein Kapitel zu bearbeiten, wählen Sie es gezielt aus. Die Vorschau wechselt dann sofort zur Darstellung des Textes im Editor.

Ordner zur Strukturierung verwenden

Bei schrittweiser Erstellung neuer eigenständiger Dateien könnte die Seitenleiste irgendwann überfüllt wirken. Um Dateien schnell wiederzufinden, bietet sich zwar die Verwendung des Filters am unteren Ende der Seitenleiste an. Allerdings setzt sich dieser nach einem Neustart von adoc Studio zurück.

Aus diesem Grund stellt sich eine weitere Lösung zur Strukturierung dar. Ähnlich wie im Betriebssystem haben Sie auch in adoc Studio die Möglichkeit, Ordner zu erstellen. Diese können Sie nach den Regeln des Betriebssystems benennen und bieten Platz für zahlreiche Dokumente. Zudem können diese Ordner auch innerhalb anderer Ordner angelegt werden, um eine noch feinere Strukturierung zu ermöglichen.

Das Konzept der einzelnen Dokumente bleibt bestehen. Selbst wenn Sie viele Ordner erstellt und darin zahlreiche Dateien abgelegt haben, bleiben sie voneinander unabhängig. Sollten Sie jedoch ein Buch mit vielen Kapiteln schreiben, benötigen Sie das Sammeldokument.

Medienordner verwenden

Der Medienordner erfüllt eine spezielle Funktion. Sie können standardmäßig alle Medien wie Bilder, Videos usw. darin ablegen. adoc Studio durchsucht das Projekt in einer festgelegten Reihenfolge nach diesen Medien.

Suchreihenfolge für Bilder

Die Zeile images::bild.jpg[] veranlasst adoc Studio dazu, das Bild in folgender Reihenfolge zu suchen:

adoc Studio sucht zuerst die Datei "bild.jpg" auf derselben Ebene wie die .adoc-Datei.
Falls sie dort nicht gefunden wird, sucht die App im übergeordneten Medienordner.
Wird das Bild dort ebenfalls nicht gefunden, sucht die App auf der nächsten übergeordneten Ebene erneut im Medienordner.
Dies setzt sich fort, bis das Wurzelverzeichnis des Projekts erreicht ist.
Wenn das Bild immer noch nicht gefunden wird, markiert der Editor den Dateinamen rot, und im Problemnavigator wird ein Eintrag zur Seitenleiste hinzugefügt.

Bilder mit Pfadangaben

Die Zeile images::/bild.jpg[] sucht das Bild im Projektverzeichnis, in dem sich auch die .adocprojekt-Datei befindet.
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 referenziert wird.

Grundsätzlich können alle Pfade wie im Betriebssystem angegeben werden. Die Wurzel ist dabei immer das Projektverzeichnis, in dem sich Ihre .adocproject-Datei befindet.

Für die AsciiDoc-Profis:

In adoc Studio existiert auch das Konzept von imagesdir. Wenn Sie dieses Attribut in bestehenden (externen) Projekten verwenden, sollte es immer vor den Bildern und möglichen Pfadangaben stehen. Beachten Sie jedoch, dass es nicht automatisch gesetzt wird und daher manuell angepasst werden muss.

Anstelle von:

image::Ordner/bild.jpg[]

verwenden Sie:

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

Weitere Einzelheiten und spezifische Anwendungsfälle findest Sie auf der AsciiDoc-Webseite.

Sie können viele Medienordner haben. Hier ein paar Beispiele:

Ein Medienordner mit allgemeinen Bildern.
Ein Medienordner mit Bildern einer speziellen Sprache.
Ein Medienordner mit Bildern einer bestimmten Plattform.

In diesem Projekt sind beispielsweise die Bilder für das iPad in einem Unterverzeichnis des Medienordners abgelegt und den Aufruf über das Attribut Mac in den Produkten gesteuert. Dabei dienen die Werte :plattform: iPad oder :plattform: Mac als Vorgaben. Die plattformabhängigen Bilder werden dann wie folgt eingebunden:

image::{platform}/neu-componente.jpeg

Auf diese Weise werden Anleitungen für den Mac, das iPad und andere Plattformen erstellt.

Bei externen Projekten gibt es noch einige weitere Besonderheiten. Mehr Details dazu finden Sie dort.

Neue Komponente einfügen

Um eine neue Komponente in Ihr Projekt einzufügen, verwenden Sie die Schaltfläche in der Symbolleiste oder den Tastaturkurzbefehl ⌘+⇧+N. Der Dialog passt sich je nach Auswahl in der Dateiliste wie folgt an:

Wenn Sie ein eigenständiges Dokument ausgewählt haben, können Sie entweder ein neues eigenständiges Dokument oder ein Sammeldokument erstellen.
Wenn Sie jedoch ein Sammeldokument oder ein Kapitel daraus ausgewählt haben, haben Sie die Möglichkeit, neue Kapitel hinzuzufügen.

In jedem Fall haben Sie die Möglichkeit, neue Ordner, Medienordner oder auch bestehende Dateien einzufügen.

Sie können Dateien direkt aus dem Finder in die Dateiliste ziehen, um sie in Ihr Projekt einzufügen.

Bestehende Dateien einfügen

In adoc Studio können Sie nicht nur Sammeldokumente mit ihren Kapiteln erstellen, sondern auch eigenständige Dokumente.

Ein eigenständiges Dokument übernimmt keine Attribute aus anderen Dokumenten in der Dateiliste. Alle Werte müssen in diesen Dokumenten explizit gesetzt werden. Auch Medienordner, die sich in Sammeldokumenten befinden, werden von einem eigenständigen Dokument nicht gefunden; nur diejenigen außerhalb von Sammeldokumenten sind auffindbar.

Es liegt an Ihnen, wie Sie diese Dateien in Ihr Projekt integrieren möchten. Im Folgenden finden Sie einige Möglichkeiten:

Doppelter Mausklick im Finder

Im Finder können Sie jede .adoc-Datei durch einen Doppelklick in adoc Studio öffnen, sofern keine andere Anwendung nach der Installation die .adoc-Dateiendung übernommen hat. Dabei erscheint ein Dialog, der es Ihnen ermöglicht, das Zielprojekt für die Datei auszuwählen oder ein neues Projekt zu erstellen. Anschließend wird die Datei in das ausgewählte Projekt kopiert, ohne verschoben zu werden.

Drag & Drop aus dem Finder

Eine weitere Methode, um Dateien in ein Projekt zu kopieren, ist das Ziehen und Ablegen per Drag & Drop. Sie können die gewünschte Datei einfach aus dem Finder ziehen und sie an die gewünschte Position in adoc Studio ablegen. Wenn das Ziel ein Sammeldokument ist, wird die Datei automatisch zum Bestandteil dieses Sammeldokuments.

Dateien im Finder kopieren oder verschieben

Sie können Dateien auch direkt im Finder in das Projektverzeichnis kopieren oder verschieben. adoc Studio erkennt sie automatisch, und innerhalb kurzer Zeit erscheinen sie direkt in der Dateiliste Ihres Projekts. Es ist nicht erforderlich, die App neu zu starten.

Menüfunktion

Abschließend bietet sich eine Menüfunktion an, um Dateien in Ihre Projekte einzufügen. Sie können entweder über das Menü Ablage Neu Dateien hinzufügen … oder den Tastaturkurzbefehl ⌘+⌥+A die Dateiauswahl öffnen. Die ausgewählte(n) Datei(en) werden dann unterhalb der aktuellen Auswahl in der Dateiliste eingefügt. Anschließend können Sie sie mit der Maus an einen anderen Ort verschieben.

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

Dateiinformationen

Für den Fall, dass eine Datei in einem Sammeldokument liegt, aber nicht ausgegeben werden soll, bietet adoc Studio Ihnen eine Lösung:

Durch einen Sekundärklick auf die Datei im Dateiverzeichnis der linken Seitenleiste rufen Sie das Kontextmenü auf. Dort befindet sich der Eintrag Informationen …, der den rechts dargestellten Dialog aufruft.

Deaktivieren Sie die Option „Teil des Sammeldokuments“, um die Datei aus der Einbindung zu entfernen. Soll die Datei dennoch verwendet werden, müssen Sie sie über den include-Befehl einbinden.

Weitere Informationen

Die meisten Dateien und alle Ordner in der Seitenleiste können Sie über das Menü Informationen… modifizieren. Neben der Umbenennung einer Datei oder eines Ordners gibt es folgende Möglichkeiten:

Für eine Datei:
- Teil eines Sammeldokuments
Für einen Ordner:
- Ordner
- Sammeldokument
- Medienordner

Diese Einstellungen beziehen sich ausschließlich auf die Arbeit in adoc Studio. In macOS Finder ¹ erscheinen alle Objekte lediglich als Ordner und Dateien.

Ein Projekt sichern

Der alte Weg

In der Vergangenheit wurde ein neues Projekt im ersten Schritt gesichert. Dabei legten Sie den Speicherort fest, an dem das Projekt angelegt wird. Dies erfolgt über Ablage Sichern … oder den Tastaturkurzbefehl ⌘+S.

Es steht Ihnen frei, die Dateien von adoc Studio auf Ihrem lokalen Rechner, einem Server oder in einem Cloud-Speicher zu sichern. Auch die Nutzung eines Versionskontrollsystems wie Git oder GitHub ist möglich.

Der neue Weg

Ein initiales Sichern ist nicht mehr erforderlich, um Datenverlust zu vermeiden. Schließen Sie das letzte Projektfenster, fragt adoc Studio, ob das Projekt gesichert werden soll. Sie entscheiden dann, ob und wo das Projekt abgelegt wird.

TIPP: In adoc Studio übernimmt die App das regelmäßige Sichern der .adoc-Dateien in kurzen Abständen für Sie. Falls gewünscht, können Sie weiterhin den Tastaturkurzbefehl ⌘+S verwenden, jedoch erfolgt die automatische Sicherung schneller.

Weitere Fenster für ein Projekt

Ein Projekt kann mithilfe des Menüs Fenster Neues Fenster in mehreren Fenstern geöffnet werden. Dies ist insbesondere im Zwei-Monitor-Betrieb sehr hilfreich, wenn Sie die Vorschau in einem eigenen Fenster anzeigen möchten.

Klicken Sie auf Ihrem Mac mit gleichzeitig gedrückter ⌘-Taste auf den Fenstertitel, um ein Menü mit dem Pfad des aktuellen Projekts im Finder zu öffnen.

Externe Projekte

Die externen Projekte sind noch nicht beschrieben. Eine ausführliche Dokumentation wird so bald wie möglich zur Verfügung stehen.

Der Abschnitt-Navigator

Der zweite Reiter in der Seitenleiste zeigt die Struktur der Überschriften als Gliederung an.

Bei Sammeldokumenten wird das gesamte Inhaltsverzeichnis angezeigt, unabhängig davon, in welchem Kapitel Sie gerade arbeiten.

Bei einzelnen Dokumenten erscheint nur das jeweilige Inhaltsverzeichnis.

Um ein Inhaltsverzeichnis im Text auszugeben, verwenden Sie das Attribut :toc:, das hier beschrieben wird.

Der Such-Navigator

Der Reiter mit der Lupe ist der Such-Navigator. Verwenden Sie ihn, um Texte im gesamten Projekt zu finden.

Im Kontextmenü hinter der Lupe können Sie die Ersetzen-Funktion aktivieren. Außerdem können Sie hier folgende Einstellungen vornehmen:

Groß-/Kleinschreibung ignorieren,
Akzente und Umlaute ignorieren.

In diesem Menü aktivieren Sie ebenfalls die reguläre Ausdrücke für die Suche.

Nach der Suche werden die Treffer nach den Dateien im Projekt gruppiert zusammengefasst. Ein Klick auf eine Datei öffnet diese im Editor und springt zur gewünschten Position.

Besonderheiten

Wenn Sie gefundenen Text ersetzen wollen, bietet adoc Studio einige praktische Funktionen:

Selektieren Sie einzelne Treffer in der Liste (eine Mehrfachauswahl per ⇧-Taste ist möglich), um die Ersetzungen nur für die ausgewählten Stellen vorzunehmen.
Selektieren Sie eine Datei in der Trefferliste, um die Ersetzungen nur in dieser Datei vorzunehmen.

Der Problem-Navigator

Das Konzept für AsciiDoc und adoc Studio ist es, einen Text auszugeben, unabhängig davon, ob und wie viele AsciiDoc-Fehler im Text vorhanden sind. Es geht bei dem Problem-Navigator nicht um grammatikalische oder orthographische 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 als Warnungen in Gelb dargestellt.

Die Liste selbst ist nach dem Auftreten sortiert. Ein Klick auf eine Meldung lässt den Editor an die entsprechende Stelle springen, damit Sie den Fehler beheben können.

Schreiben und im Text navigieren

Wählen Sie in der Dateiliste eine Textdatei aus. Sollte der Cursor nicht bereits im Editor-Fenster blinken, setzen Sie ihn mit einem Mausklick in den mittleren Bereich des Fensters oder durch Drücken von ⌃+TAB, und schon können Sie mit dem Schreiben beginnen. Hinweise zu AsciiDoc erhalten Sie im nächsten Kapitel.

Der eingegebene Text erscheint in der Vorschau. Bei längeren Texten wird die Position der beiden Fenster synchronisiert, sodass Sie immer den links geschriebenen Text auf der gleichen Höhe in der Vorschau sehen. Die Position der Schreibmarke wird mit der Position in der Vorschau synchronisiert.

Beachten Sie, dass das Wechseln zur Vorschau im PDF-Format bei längeren Texten zeitaufwendig sein kann. Daher empfehlen wir, bei der HTML-Vorschau zu bleiben, da diese schneller aktualisiert werden kann.

Der Editor kann nach Ihren persönlichen Vorlieben (Farbempfinden, Dioptrienstärke usw.) angepasst werden. Der Reiter Editorstile in den Programmeinstellungen bietet Ihnen fast endlose Möglichkeiten der Gestaltung.

Zusatznavigation

Oberhalb des Editors befindet sich die Zusatznavigation.

Sie beginnt mit den Navigationspfeilen nach links und rechts . Die Funktion ähnelt der Navigation in Ihrem Browser: Sie ermöglicht es Ihnen, vorwärts und rückwärts zu navigieren.

Danach folgt ein grafischer Block, der Ihnen die aktuelle Datei und deren Struktur zeigt.

Von links nach rechts gelesen, sehen Sie, wo sich die Datei befindet, in der Sie gerade schreiben. Am äußersten rechten Rand finden Sie ein kleines Inhaltsverzeichnis der Struktur, das auch den Gesamtkontext zeigt. Zudem können Sie mit jedem Element zu jeder beliebigen Datei springen.

Zeilennummern

Eine einzelne Zeilennummer erscheint am rechten Rand des Editors zur Orientierung. In den meisten Fällen reicht dies aus. Wenn Sie die Anzeige aller Zeilennummern bevorzugen, ändern Sie dies in den Einstellungen.

Ein Klick auf eine Zeilennummer oder ⌘+L, gibt Ihnen die Möglichkeit, zu einer bestimmten Zeile zu springen.

Auch Texte werden sofort gesichert

Änderungen in den Texten werden genauso wie die Projektdateien umgehend gesichert. Sie müssen sich also keine Sorgen um Datenverlust machen!

Cursor

Beim Schreiben möchten Sie nicht ständig die Hand von der Tastatur nehmen, um den Cursor mit der Maus zu positionieren. Deshalb wurden die bekannten Shortcuts der Textbearbeitung von macOS und iPadOS übernommen und genau so in adoc Studio integriert.

Tabelle 1. Verwendete Modifizierungstasten
`⌘`	Command- oder Befehlstaste
`⌥`	Option- oder Wahltaste
`⌃`	Control- oder Ctrl-Taste
`⇧`	Shift- oder Umschalttaste
`⌤`	Eingabetaste
`⏎`	Zeilenschalter
`⌫`	Backspace- oder Rückschritttaste
`⌦`	Entf.-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 rechts vom Cursor

Ein weiterer Tastaturkurzbefehl, den Sie regelmäßig in adoc Studio verwenden möchten, ist die ESC-Taste. Damit betreten Sie den großen Bereich der Eingabehilfen.

Eingabehilfen

Der Funktionsumfang von AsciiDoc ist sehr vielfältig. Daher kann es selbst Profis passieren, dass der eine oder andere Befehl vergessen wird, ein Makro unerkannt bleibt oder man sich nicht mehr an eine bestimmte Syntax erinnert. Aus diesem Grund ist in adoc Studio eine intelligente Eingabehilfe integriert.

Während Sie schreiben, sucht die App kontinuierlich nach Möglichkeiten, Ihnen zu helfen. Oft erkennt sie bereits nach dem zweiten oder dritten Zeichen verschiedene Optionen und bietet diese in einem Menü mit Vervollständigungen an. Dabei ist es das Ziel von adoc Studio, Ihren Schreibfluss so wenig wie möglich zu unterbrechen. Daher erhalten Sie die Vervollständigungsvorschläge nur, wenn Sie eine Schreibpause machen.

Bei Bedarf können Sie das Menü mit den Eingabehilfen jederzeit über die ESC-Taste aufrufen.

Beispiel: Ein Bild im Text einbinden

Beginnen Sie am Zeilenanfang mit der Eingabe von bil oder ima.
Ein kurzes Menü erscheint:
Navigieren Sie in der Liste mit den Tasten ↓ oder ↑.
Wählen Sie den gewünschten Eintrag mit der ⏎-Taste aus.
Nach der Auswahl erscheint ein weiteres Menü:

Die Bilder werden praktischerweise gleich als kleine Vorschau dargestellt.
Nach Auswahl des passenden Bildes mit der ⏎-Taste erscheint das Bild in voller Breite in der Vorschau.
Setzen Sie den Cursor zwischen die beiden eckigen Klammern nach dem Bildnamen ([]), um die passenden Optionen für das Bild einzugeben.
Geben Sie als Erstes die Breite des Bildes ein, indem Sie wi eingeben. Jetzt erscheint erneut das Menü mit allen verfügbaren Optionen für Bilder, die wi enthalten.
Navigieren Sie mit den Cursortasten zu width= und betätigen Sie die ⏎-Taste.
Jetzt sehen Sie folgendes:
Überschreiben Sie den Platzhaltertext mit einer Zahl (z. B. 200), um die Skalierung des Bildes in der Vorschau sofort zu sehen.
Setzen Sie den Cursor 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.
Betätigen Sie die ESC-Taste, damit das Vervollständigungsmenü mit den weiteren Optionen für das Bild erscheint.
Angenommen, Sie möchten das Bild rechts neben einen Text platzieren. Hierzu benötigen Sie die Option float. Beginnen Sie mit der Eingabe von flo, und das Vervollständigungsmenü zeigt alle Optionen, die flo enthalten:
Wählen Sie float=right.

Herzlichen Glückwunsch! Sie haben ein Bild eingefügt, das skaliert und rechts neben dem Text positioniert wird.

Im Quelltext auf der linken Seite sieht das wie folgt aus:

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.

Das Ergebnis auf der rechten Seite in der Vorschau sieht so aus:

Wie im Beispiel gezeigt, steht Ihnen für jeden AsciiDoc-Befehl und alle Attribute das Vervollständigungsmenü zur Verfügung. Im Zweifelsfall hilft ein einfacher Druck auf die ESC-Taste, um alle Makros zu sehen, die an der aktuellen Stelle möglich sind.

Programmeinstellungen

In adoc Studio können Sie viele Bereiche nach Ihren Wünschen anpassen.

Allgemein

Öffnen Sie das Fenster mit den Einstellungen über das Hauptmenü adoc Studio Einstellungen … oder den Tastaturkurzbefehl ⌘+,.

Hier finden Sie die wichtigsten Einstellungen für adoc Studio unter dem Allgemein-Reiter:

Zeilennummern: Entscheiden Sie, ob alle Zeilennummern oder nur die der aktuellen Zeile angezeigt werden sollen.
Zuklappen von Abschnitten: Aktivieren Sie die Dreiecke zum Ein- & Ausklappen der Abschnitte im Text.
Zeige Dateiendungen: Wählen Sie, ob alle Dateiendungen im Projektnavigator der Seitenleiste eingeblendet werden sollen. Wenn diese Option deaktiviert ist, wird die Dateiendung nur für die aktuell ausgewählte Datei angezeigt.

Zeilenbreite: Definieren Sie hier die maximale Anzahl von Zeichen pro Zeile im Editor, bevor dieser sie umbricht. Wenn der angezeigte Bereich zu klein ist, bricht der Editor die Zeile dennoch um.
Abschnitts-Einrückung: Hier wählen Sie aus, wie viel Platz links von den Gleichheitszeichen in Überschriften freigehalten werden soll. Dabei legen Sie einen Wert zwischen 0 und 6 fest, um den linken Rand anzupassen. Dadurch wird der Fließtext linksbündig ausgerichtet, während die =-Zeichen weiter nach links ragen.
Tabulatorbreite: Legen Sie hier fest, wie breit ein Tabulator im Text sein soll. Dabei können Sie einen Wert zwischen 1 und 100 für die Zeichenbreite eines Tabulators wählen. Praktisch haben sich Werte zwischen 3 und 5 bewährt.

Einrücken mit: Wählen Sie hier, wie der Platz beim Einrücken gefüllt werden soll. Entweder mit Tabulatoren oder Leerzeichen.

Dateizugriff

Die Sicherheit ist ein zentrales Thema bei modernen Betriebssystemen wie macOS und iOS. Um schädliche Programme daran zu hindern, auf sensible Bereiche des Betriebssystems zuzugreifen, hat Apple das Konzept der Sandboxes eingeführt.

Jede App arbeitet in ihrer eigenen Sandbox und darf nur innerhalb dieser Umgebung agieren. Dadurch laufen viele Apps zwar gleichzeitig auf dem Computer, jedoch jeweils isoliert in ihren eigenen Sandkästen. Wenn eine App außerhalb ihres Sandkastens operieren möchte, benötigt sie die ausdrückliche Genehmigung der Benutzerin oder des Benutzers.

Dieses Sicherheitsprinzip gilt auch für adoc Studio auf macOS und iOS. Da adoc Studio für die Bearbeitung von Projekten auf sämtliche enthaltenen Text- und Mediendateien zugreifen muss, erfordert dies eine explizite Freigabe Ihrerseits.

Alle genehmigten Dateizugriffe werden in einer Liste auf diesem Tab in den Einstellungen aufgeführt und können mithilfe der Schaltflächen + und - verwaltet werden. Wenn Sie ein neues Projekt öffnen, das hier noch nicht aufgeführt ist, wird die App Sie um Erlaubnis bitten und die Genehmigung automatisch eintragen.

Um weniger häufig nachgefragt zu werden, können Sie auch Ordner auf einer höheren Ebene in der Dateistruktur eintragen.

Editorstile

In diesem Abschnitt legen Sie das Erscheinungsbild des Editors fest. Gehen Sie auf der linken Seite mit der Maus durch die Liste der benannten Stile. Die meisten Stile sind sowohl für den Hell-Modus (gekennzeichnet durch ein ○ am Ende) als auch für den Dunkel-Modus (gekennzeichnet durch ein ● am Ende) verfügbar. Wählen Sie einen Stil aus, der Ihnen gefällt oder Ihrem Geschmack am nächsten kommt. Dann können Sie fortfahren.

In der mittleren Liste finden Sie alle Elemente, Attribute und Funktionsnamen, die im Text verwendet werden. Eine einfache Regel ist, mit dem Eintrag „Allgemein“ zu beginnen und dort die Schriftart, ihre Größe und viele weitere gewünschte Attribute einzustellen.

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

Produktstile

In den adoc Studio Einstellungen … ⌘+, unter dem vierten Register finden Sie die Produktstile.

Wie bereits zuvor beschrieben, sind in adoc Studio Text und Gestaltung voneinander getrennt. Jede Gestaltung stammt aus einer Stildatei, den Produktstilen. Es wird bereits eine Reihe von Produktstilen mitgeliefert, aber Sie können auch eigene erstellen. Das Besondere an diesen Produktstilen ist ihre Technologie. Sie basieren auf Cascading Style Sheets (CSS), womit Sie nicht nur Texte, sondern auch HTML oder PDF-Dateien gestalten können.

Das bedeutet, mit einem CSS-Stil können Sie alle Dokumente formatieren, einschließlich PDF-Dateien.

In diesem Register der Einstellungen können Sie Ihre Produktstile verwalten.

Auf der linken Seite werden zunächst Ihre eigenen Produktstile und dann die mitgelieferten Stile aufgelistet. Auf der rechten Seite werden Beispiele im ausgewählten Produktstil angezeigt. Unter 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 durch Doppelklick auf die Datei installiert werden. Alternativ können Sie sie einfach in die Liste auf der linken Seite der Einstellungen ziehen. Darüber hinaus finden Sie unter der Liste der vorhandenen Produktstile auch eine +-Taste, über den Sie neue hinzufügen können.

Produktstile entfernen

Um eigene Produktstile zu entfernen, klicken Sie mit der rechten Maustaste auf den gewünschten Produktstil und wählen Sie im Kontextmenü die Option Löschen aus.

Eigene Produktstile erstellen

Um einen eigenen Produktstil zu erstellen oder zu modifizieren, sind CSS-Kenntnisse.erforderlich. Hier zeigen wir Ihnen, wie Sie auf einfache Weise einen Produktstil auf Basis eines vorhandenen erstellen können:

Wählen Sie den gewünschten Produktstil aus, der als Grundlage dienen soll.
Klicken Sie auf und wählen Sie die Option Duplizieren aus dem Kontextmenü. Alternativ können Sie auf den Namen des Produktstils mit einem Sekundärklick das Kontextmenü öffnen und Duplizieren auswählen.
Der duplizierte Stil wird nun als neuer Eintrag oben in der Liste angezeigt.
Doppelklicken Sie auf den Namen des neuen Stils, um ihn zu bearbeiten.

Einen Stil bearbeiten

Um den Produktstil zu bearbeiten, benötigen Sie einen Text-Editor. Ein geeignetes Tool ist BBEdit. Jeden anderen Editor können Sie ebenso verwenden, solange er CSS-Dateien im Format UTF-8 speichern kann.

Wählen Sie den neu erstellten Produktstil aus.
Klicken Sie auf -Menü oder rufen Sie mit einem Sekundärklick das Kontextmenü auf und wählen die Option Bearbeiten in aus.
Wählen Sie Ihren bevorzugten Editor aus der Liste.
Die gewählte App startet und der Produktstil wird dort 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 werden Ihre Änderungen im externen Editor umgehend in adoc Studio aktualisiert und gespeichert.

Die Auszeichnungssprache AsciiDoc

adoc Studio verwendet die Markup-Sprache AsciiDoc als Grundlage. Dieses Kapitel bietet Einsteigern einen ersten Überblick über den Befehlsumfang von AsciiDoc und enthält weiterführende Links zur offiziellen Dokumentation.

Erfahrene AsciiDoc-Nutzer können dieses Kapitel überspringen. Es gibt jedoch eine Bitte: Auf der Roadmap für adoc Studio findet sich eine Liste der noch nicht implementierten AsciiDoc-Funktionen. Dort lässt sich der persönliche Bedarf priorisieren, und im Forum besteht die Möglichkeit, mit anderen Nutzern zu diskutieren.

Was ist AsciiDoc?

AsciiDoc ist eine vereinfachte Auszeichnungssprache, die das Erstellen von Texten in verschiedenen Dokumentenformaten erleichtert. AsciiDoc-Dateien lassen sich in HTML, PDF, ePub und andere Formate konvertieren.

Im Vergleich zu XML-basierten Dokumentenformaten wie DocBook bietet AsciiDoc den Vorteil, dass es leicht erlernbar ist und auch als reiner Text gut lesbar bleibt. Weitere Informationen finden sich auf Wikipedia.

In diesem Kapitel gibt es Verweise auf die AsciiDoc-Dokumentation, die derzeit nur in englischer Sprache verfügbar ist. An einer deutschen Übersetzung wird gearbeitet.

Text schreiben

Verfassen Sie Ihren Text einfach so, wie Sie es gewohnt sind. Schreiben Sie alles direkt hintereinander, wie in anderen Programmen, was oft als Fließtext bezeichnet wird. Alternativ können Sie den Text auch Zeile für Zeile schreiben, also jeden Satz in eine neue Zeile setzen. Der gesetzte Text sieht immer gleich aus.

Erzeugen Sie einen neuen Absatz, indem Sie eine Leerzeile zwischen den Absätzen einfügen.

Die Präambel

Der erste Absatz eines Dokuments wird als Präambel oder manchmal auch als Abstrakt bezeichnet. Dieser Absatz erscheint automatisch etwas größer als der normale Text und wird häufig als Einleitung für das Dokument genutzt.

Um auch andere Absätze größer zu setzen, kann ein [.lead] vorangestellt werden.

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.

Vermeiden Sie diesen Effekt im ersten Absatz, indem Sie ein [.nolead] voranstellen. So beginnt Ihr Text sofort in der regulären Schriftgröße.

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

Formatierungen

Wie in jeder Auszeichnungssprache können Sie einzelne Worte fett, kursiv oder anders formatieren. Das erleichtert den Umstieg. Das Editor-Menü in adoc Studio bietet Ihnen außerdem alle wichtigen Formatierungen für den schnellen Zugriff mit der Maus oder der Tastatur.

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	Tastaturkurzbefehl	Auszeichnung im Text	Ergebnis in der Vorschau
Fett	`⌘`+`B`	fett	fett
Kursiv	`⌘`+`I`	_kursiv_	Kursiv
Markiert	`⌘`+`#`	#markiert#	markiert
Feste Laufweite	`⇧`+`⌘`+`#`	`feste Laufwxeite`	`feste Laufweite`
Unterstrichen	`⌘`+`U`	[.underline]#unterstrichen#	unterstrichen
Durchgestrichen	`⇧`+`⌘`+`X`	[.line-through]#durchgestrichen#	durchgestrichen
Überstrichen	`⌥`+`⇧`+`⌘`+`X`	[.overline]#überstrichen#	überstrichen
Hochgestellt	`⌥`+`⇧`+`⌘`+`+`	^hochgestellt^	^hochgestellt
Tiefgestellt	`⌥`+`⇧`+`⌘`+`-`	~tiefgestellt~	_tiefgestellt

AsciiDoc kann noch viel mehr. Sie können verschiedene Auszeichnungen beliebig kombinieren.

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

Ergebnis in der Vorschau:

Supercalifragilistischexpialigetisch 😀

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

Überschriften

Überschriften, genauer gesagt, die Ebenen der Überschriften, können Sie durch eine Anzahl von = oder # festlegen. Letzteres erleichtert den Umstieg von Markdown zu AsciiDoc. Es ist jedoch ratsam, sich direkt an das =-Zeichen zu gewöhnen, da dieses deutlich mehr Möglichkeiten bietet.

Hier sind 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, können Sie vor einer Zeile ein . als Absatzüberschrift setzen:

.Weitere Überschriften

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

Inhaltsverzeichnis

Wenn Sie Überschriften setzen, denken Sie direkt an ein Inhaltsverzeichnis. Um ein Inhaltsverzeichnis in adoc Studio zu erstellen, genügt es, wenn Sie die Überschriften (Section Title in AsciiDoc-Sprache genannt) erstellen.

Wenn Sie :toc: in den Dokumentkopf einfügen, wird automatisch ein Inhaltsverzeichnis generiert. Dieses enthält standardmäßig zwei Ebenen von Überschriften und wird über dem Dokument platziert. Das Inhaltsverzeichnis wird automatisch aktualisiert.

Das :toc:-Attribut kann zusätzlich Parameter enthalten:

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: Das gleiche wie ohne Parameter.

In diesem Zusammenhang ist auch das Attribut :toclevels: 3 interessant. Durch die Ziffer nach dem Attribut toclevels bestimmen Sie, wie viele Ebenen im Inhaltsverzeichnis angezeigt werden sollen. Dieses Attribut muss im Dokumentenkopf festgelegt werden. Standardmäßig sind zwei Ebenen vorgegeben.

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

Links

Bei den Verlinkungen gibt es zwei Arten:

Hyperlinks ins Internet
Querverweise im Dokument

Hyperlinks ins Internet

Der einfachste Link besteht aus einer ausgeschriebenen Adresse. In der Vorschau wird sie sofort zu einer klickbaren URL. Beim Anklicken öffnet sich die entsprechende Seite im Browser: https://adoc-studio.app. Dies funktioniert für die wichtigsten URL-Schemas:

http
https
ftp
irc
mailto

Sie können Links auch als Makro ausgeben: https://www.adoc-studio.app[]. Zwischen den Klammern können Sie optional einen Text einfügen, der anstelle der URL angezeigt wird.

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

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 entspricht einer automatisch generierten ID einer Überschrift oder eines Ankers.

Verwenden Sie die automatischen IDs so sparsam wie möglich. Wenn Sie eine Überschrift ändern, auf die Sie per Querverweis zugreifen, wird der Querverweis möglicherweise ungültig.

Es ist immer besser, einen Anker vor einer Überschrift zu setzen.

[#mein_anker] 
== Meine Überschrift

Setzen Sie den Querverweis im Text mit:

<<mein_anker>>

Im gesetzten Dokument wird die Überschrift angezeigt. Optional können Sie auch einen Text festlegen, der anstelle der Überschrift erscheint:

<<mein_anker, Springe hier hin>>

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

Fußnoten

Das Makro footnote:[] generiert automatisch Fußnoten.² Der Text der Fußnote wird in eckigen Klammern hinter dem Makro eingefügt:

footnote:[Hier ist der Text der Fußnote]

AsciiDoc unterstützt derzeit nur Fußnoten, die als Endnoten angezeigt werden. Daher sind sowohl footnote als auch endnote in adoc Studio implementiert. Um die Kompatibilität mit bestehenden Dokumenten sicherzustellen, kann das Attribut :footnotes-position: verwendet werden.

Mehr Informationen zu Fußnoten finden Sie auf der AsciiDoc-Webseite.

Bilder

In der

In der Einführung wurde bereits kurz über Bilder und ihre Pfade gesprochen. Jetzt wird genauer darauf eingegangen, wie Bilder in den AsciiDoc-Text eingebunden werden.

Sie können Bilder auf zwei Arten einfügen, als Blockbild oder als Bild im Fließtext.

Blockbilder

Die grundsätzliche Schreibweise ist wie folgt:

image::bild.png[]

Der Text sollte in einer eigenen Zeile stehen. Die Klammer kann viele Optionen aufnehmen, wobei das Vervollständigungsmenü von adoc Studio hilfreich ist, wie im Beispiel "Beispiel: Ein Bild im Text einbinden" gezeigt. Drei wichtige Optionen sind:

width: Die Breite des Bildes.
align: Die Ausrichtung eines Bildes.
float: Der Umfluss um ein Bild.

Inline-Bilder

Die Syntax für Inline-Bilder ähnelt stark der für Blockbilder, mit dem Unterschied, dass ein Doppelpunkt : weggelassen wird:

image:bild.png[]

Ein Bild, das sich im Fließtext befindet, wird wie folgt eingefügt:

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

Das ergibt:
Drücken Sie bitte , um die Seite neu zu laden.

Nebeneinander gestellte Bilder lassen sich auch mit Inline-Bildern einfach umsetzen:

hello hello hello

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

Listen

Um eine ungeordnete Liste zu erstellen, verwenden Sie die folgende Syntax:

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 mit Markdown vertraut sind, können Sie auch folgende Syntax für Listenpunkte verwenden:

Markdown-Listen beginnen mit einem -
das funktioniert
auch in adoc Studio

Geordnete Listen sind genauso einfach zu erstellen:

eins
zwei
drei

Sie haben auch die Möglichkeit, Zahlen anzugeben:

eins
zwei
drei
Fehlerhafte Nummerierungen werden ignoriert. In diesem Fall wird nicht die 7. wie im Editor angezeigt, sondern die 4.

In adoc Studio wird die Nummerierung immer automatisch erstellt.

Wenn die Listen etwas komplexer werden sollen, folgen Sie demselben Konzept wie bei der ungeordneten Liste.

Schritt 1
1. Schritt 1 a
2. Schritt 1 b
Schritt 2
Schritt 3

Checklisten sind ebenfalls möglich:

zu erledigen
erledigt
auch erledigt
- und können auch mit anderen Einträgen vermischt werden.

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

Blockelemente

Blockelemente, auch einfach als Blöcke bezeichnet, sind äußerst vielseitig in AsciiDoc. Es gibt zahlreiche Verwendungen und Darstellungsformen für sie.

Hinweise
Randnotizen
Quellcode und Listings
Gleichungen
Durchreichungen
Zitate

Blöcke können in verschiedenen Formen verwendet werden:

In einer Kurzform, die normalerweise einzeilig ist.
In einem Absatz, der jedoch auch mehrere Zeilen umfassen kann.
Mit vielen Absätzen, die auch Leerzeilen enthalten können.

quote completion

Nach dem Text "zit" oder "quote" öffnet sich das Vervollständigungsmenü mit den drei abgebildeten Möglichkeiten:

Zitat (Kurzform) wird im Text wie folgt dargestellt:

.Titel
"Text"
-- Autor,Werk

Zitat (Ein Absatz) wird im Text wie folgt dargestellt:

.Titel
[quote,Autor,Werk]
Text

Zitat (Mehrere Absätze) wird im Text wie folgt dargestellt:

.Titel
[quote,Autor,Werk]
____
Text
____

Die Texte sind immer als Platzhalter formatiert. Wenn der Platzhalter selektiert ist und blau erscheint, können Sie den

ersetzen. Wenn Sie den Platzhalter nicht nutzen möchten, drücken Sie einfach Enter oder Löschen.

Ein Block muss immer zwischen zwei Begrenzern stehen, dem Blockstart und dem Blockende. Es gibt eine Vielzahl von verschiedenen Zeichen, die verwendet werden können, wie beispielsweise bei dem folgenden Zitat:

"Lernen ist Erfahrung. Alles andere ist einfach nur Information."

— Albert Einstein

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

Hinweise

Mit Hinweisen können Sie den Leser im Text auf Besonderheiten aufmerksam machen. Die Hinweise werden in verschiedenen Stilen mit unterschiedlichen Symbolen dargestellt.

Achten Sie darauf, das Attribut :icons: font am Anfang Ihres Dokuments zu setzen. Dadurch werden die Symbole korrekt angezeigt.

NOTE liefert der Leserin oder dem Leser ergänzende Hinweise.

TIP bietet der Leserin oder dem Leser einen nützlichen Hinweis oder eine besondere Empfehlung.

WARNING warnt die Leserin oder den Leser vor einer möglichen Gefahr.

CAUTION macht die Leserin oder den Leser auf einen möglichen Fallstrick aufmerksam.

IMPORTANT lenkt die Aufmerksamkeit der Leserin oder des Lesers auf einen wichtigen Umstand.

Hier ist direkt ein Tipp:

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

Tabellen

Die Tabellen sind ähnlich umfangreich wie die Blöcke. Sie können mit einfachen tabellarischen Darstellungen wie dieser beginnen:

Eins

Zwei

Drei

Fügen Sie eine Kopfzeile hinzu, indem Sie nach der ersten Zeile eine Leerzeile einfügen:

Titel 1	Titel 2	Titel 3
Eins	Zwei	Drei
Vier	Fünf	Sechs

Titel 1

Titel 2

Titel 3

Eins

Zwei

Drei

Vier

Fünf

Sechs

Hier ein paar komplexe Beispiele, wie sie auf der AsciiDoc-Webseite zu finden sind:

Spalte 1 Spalte 2

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

Der Text wird mit einer Monospace-Schriftart (m) gerendert.

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.

Benutzerschnittstelle

In der technischen Dokumentation sind Beschreibungen der Benutzeroberfläche (GUI) oder kurz der UI (User Interface) an der Tagesordnung. Hier gibt es vor allem drei wichtige Bereiche:

Tastaturkurzbefehle

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

Eine Besonderheit bei den kbd:[]-Makros zeigt sich bei der Nutzung der 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

Der Text könnte folgendermaßen überarbeitet werden:

Das Makro btn:[] ist für die Darstellung aller Arten von Schaltflächen zuständig. Damit haben Sie zum Beispiel eine OK-Schaltfläche zur Verfügung.

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

Kommentare

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

Zu Beginn einer Zeile markieren Sie den folgenden Text mit // als Kommentar:

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

Ganze Abschnitte definieren Sie als Kommentar, indem Sie am Anfang und Ende des Blocks //// verwenden:

Warum sollte Sie Kommentare einfügen, die im endgültigen Dokument nicht erscheinen? Hier einige Gründe:

// TODO:: Anstehende Aufgaben wie Optimierungen, Verbesserungen und Korrekturen.
Anweisungen zur Formatierung des Textes.
Begründungen und Erklärungen für spezifische Inhalte.
Interne Versionshinweise über Änderungen und Überarbeitungen.
Anmerkungen für Lektoren.
Zusätzliche Kontextinformationen, die für das Verständnis des Quelltextes im Editor hilfreich sind, jedoch im finalen Dokument nicht benötigt werden.

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

Attribute

Nutzen Sie die Attribute, um Ihre Dokumentation auf eine völlig neue Ebene zu bringen.

Der Begriff "Attribute" wird in adoc Studio auf verschiedene Weise genutzt. Grundsätzlich ermöglichen sie Ihnen Folgendes:

Definition von Werten zur späteren Verwendung im Text
Anpassung von Einstellungen im Dokument

Nutzung von Attributen als Variable

In vielen Fällen wiederholen sich bestimmte Wörter, URLs und andere Informationen im Text. Einige Begriffe ändern sich je nach Version des Dokuments, während andere, wie beispielsweise URLs, so lang sind, dass es ratsam ist, sie nur einmal einzugeben, um Fehler zu vermeiden.

Um Attribute an beliebiger Stelle im Dokument wiederverwenden zu können, legen Sie diese wie folgt fest:

Beispiel 1. Nutzen Sie ein Attribut als Variable

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.

Damit eröffnen sich bereits umfangreiche Möglichkeiten. Jedes Mal, wenn der Name adoc Studio in dieser Dokumentation auftaucht, wird das Attribut {app-name} genutzt. Hier sind einige weitere Attribute, die in diesem Dokument verwendet werden:

: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

In adoc Studio gibt es eine Reihe von Standardattributen, die bereits vorbereitet sind, da sie in (fast) jedem Dokument vorkommen. Diese müssen jedoch zu Beginn Ihres Dokuments im Dokumentenkopf eingetragen werden:

Autoreninformationen (:author:)
Versionsattribute (: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

Sie können einen Standardtitel wie folgt abkürzen:

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

In diesem Fall werden die Informationen für :author:, :email:, :revnumber: sowie :revdate: automatisch aus dem Kontext nach dem Dokumenttitel (=) abgerufen und können später als Attribute mit {} verwendet werden.

Attribute zur Dokumenteinstellung

Ein weiterer Zweck von Attributen besteht darin, die Einstellungen Ihres Dokuments zu steuern. Jedes Dokument enthält verschiedene Name-Wert-Paare, die als Dokumentattribute bezeichnet werden.

Diese Attribute ermöglichen es, den Backend-Prozessor zu konfigurieren und Dokument-Metadaten anzugeben. Sie können auf bereits vorhandene eingebaute Attribute zurückgreifen oder eigene definieren.

Setzen Sie Dokumentattribute immer am Anfang einer Zeile!

Eingebaute Attribute

Eingebaute Attribute unterstützen aktiv die Konfiguration und Steuerung des Dokuments. Ihre Wirkung entfaltet sich oft erst, wenn sie am Anfang des Dokuments in einer Zeile sich befinden.

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 (beispielsweise Bildern) angeben
Speichern von Inhalten zur Wiederverwendung in einem Dokument

Beispiele

Sie setzen Attribute entweder nur durch den reinen Eintrag: :beta:.
Sie setzen Attribute durch Zusätze: :beta-version: 23.
Sie setzen Attribute durch ein Ausrufezeichen um oder deaktivieren sie: :!beta: oder :beta!:.

In adoc Studio ist der Zugriff auf alle eingebauten Attribute äußerst benutzerfreundlich gestaltet. Drücken Sie einfach am Anfang einer Zeile die ESC-Taste und wählen Sie im Menü der Textvervollständigungen den Eintrag Attribute aus. Anschließend finden Sie alle verfügbaren eingebauten Attribute aufgelistet. textmenu textmenuattributes

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

Benutzerdefinierte Attribute

Benutzerdefinierte Attribute sind solche, die der Autor festlegt und die nicht von der AsciiDoc-Sprache oder einer Erweiterung vorbehalten sind. Sie dienen normalerweise dazu, Text zu ersetzen. Mit diesen Attributen können Sie benannte und wiederverwendbare Inhalte definieren. Anstatt Text im gesamten Dokument zu wiederholen, beispielsweise einen Produktnamen, kann dieser Text in einem Attribut festgelegt und durch seinen Namen im Dokument referenziert werden. Diese Methode hilft Ihnen dabei, das Dokument effizienter zu gestalten und das Prinzip "Don’t Repeat Yourself" (DRY) anzuwenden.

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

: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.

Diese Methode spart viel Arbeit, weil Sie den Text nicht immer wieder durch Copy & Paste kopieren und einfügen müssen. Wenn Sie den Text ändern müssen, genügt eine einzige Anpassung an einer Stelle im Dokument.

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

Bedingte Anweisungen

Bedingte Anweisungen sind Kontrollstrukturen in der Programmierung, bei denen ein Programmabschnitt nur unter bestimmten Bedingungen ausgeführt wird. Ähnlich funktioniert es auch bei Texten in adoc Studio. Hier sind die bedingten Anweisungen, die Sie verwenden können:

ifdef: Der Inhalt wird nur eingefügt, wenn das angegebene Attribut existiert.
ifndef: Der Inhalt wird nur eingefügt, wenn das angegebene Attribut nicht existiert.
ifeval: Der Inhalt wird nur eingefügt, wenn der Ausdruck innerhalb der eckigen Klammern der ifeval-Direktive als wahr bewertet wird.

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

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

Includes

Eine der Kernfunktionen von AsciiDoc ist die Verwaltung von aufgeteilten Dateien, anstatt eine endlos lange Datei zu erstellen. Sie teilen den Text in viele einzelne Dateien auf und fügen sie dann nach bestimmten Regeln zusammen.

In adoc Studio wurde bereits im Abschnitt Der Projektnavigator ein eigenes Konzept dazu vorgestellt.

Wenn Sie beispielsweise mit Autoren zusammenarbeiten, die adoc Studio nicht verwenden können, ist die Verwendung des include-Befehls ratsam. Damit können die Kapitel, die im AsciiDoc-Format vorliegen, nacheinander eingefügt werden.

 include::kapitel-1.adoc[]
 include::kapitel-2.adoc[]
 include::kapitel-3.adoc[]

Includes in adoc Studio

Innerhalb adoc Studio kann die Verwendung des include-Befehls von Nutzen sein. Angenommen, Sie stehen vor der Herausforderung, dass für Ihr Produkt nicht alle Funktionen auf einmal dokumentiert werden können. In solchen Fällen benötigen Sie einen Platzhalter.

Für dieses Projekt ist in der Dateiliste ein solcher Platzhalter mit dem Namen comingSoon.adoc definiert. Damit diese Datei nicht im Sammeldokument ausgegeben wird, wurde in den Dateiinformationen die entsprechende Checkbox deaktiviert. Weitere Details dazu finden Sie 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. Eine ausführliche Dokumentation wird so bald wie möglich zur Verfügung stehen.

Der Trick ist der Inhalt der Datei comingSoon.adoc:

ifdef::feature[]

CAUTION: Die _{feature}_ sind noch nicht beschrieben. Eine ausführliche Dokumentation wird so bald wie möglich zur Verfügung stehen.

:!feature: 

endif::[]

Wenn Sie die Datei über den include-Befehl einbinden, wird zunächst dem Attribut feature ein Text zugewiesen. In diesem Fall "wichtigen Funktionen".
Danach erfolgt die Einbindung der Datei comingSoon.adoc an der aktuellen Position.
Als nächstes wird überprüft, ob das Attribut einen Text enthält.
Falls ja, wird eine Warnung ausgegeben.
Danach wird das Attribut geleert.

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

Dokumente ausgeben

Beim Export der Dokumente bietet adoc Studio eine neue Methode, die besonders bei umfangreichen Projekten nützlich ist. Sie können zwischen dem normalen Export eines Dokuments und der Ausgabe von Produkten wählen. Zuerst jedoch noch die Vorschau.

Die Vorschau

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

Rechts neben dem Editor finden Sie die Vorschau. Ist diese nicht sichtbar, klicken Sie auf das Bildsymbol oder verwenden Sie den Tastaturkurzbefehl ⌘+⇧+P, um sie einzublenden.

Die Vorschau passt sich dem eingestellten Ausgabeformat an. Manchmal erscheint sie wie ein Browser, der eine HTML-Seite darstellt, manchmal wie eine PDF-Vorschau oder eine Anzeige im RTF-Format. Sie wählen das Ausgabeformat im Dialogfeld hinter dem Symbol neben dem Bildsymbol . Dort können Sie auch weitere Einstellungen vornehmen, die je nach Ausgabeformat variieren.

HTML-Vorschau und Einstellungen

Wenn Sie das Ausgabeformat auf HTML einstellen, wird das Dokument im Editor als langes HTML-Dokument dargestellt.

Stil: Wählen Sie den gewünschten Produkt-Stil für die Vorschau Ihres Dokuments.
Erscheinung: Entscheiden Sie, ob die Darstellung hell oder dunkel sein soll. Dies wird oft als Darkmode und Brightmode bezeichnet. Bei automatischer Einstellung folgt adoc Studio den Vorgaben der Systemsteuerung Ihres Betriebssystems.
Attribute: Verwalten Sie die Dokumentattribute. Neben den im Dokument definierten Attributen können Sie hier zusätzliche Attribute über einen Dialog festlegen. Weitere Details finden Sie in der Beschreibung der Produkte.

Text-Vorschau und Einstellungen

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

Textformat: Wählen Sie, ob der Text formatiert (als RTF) oder als reiner Text ausgegeben wird. Bei der Ausgabe als reiner Text werden der Stil nicht mehr angewendet und Bilder nicht mehr dargestellt.

PDF-Vorschau und Einstellungen

Die PDF-Vorschau zeigt das Dokument so, wie es beim Export in eine Datei geschrieben werden soll. Die Einstellungen im Klappmenü hinter dem -Symbol umfassen nicht nur den Stil, die Erscheinung und die Attribute, sondern zusätzlich:

Papier: Wie abgebildet können Sie neben dem Drucker auch das Papierformat und die Seitenränder einstellen. Im Kapitel über die Produktstile erfahren Sie mehr über die Details und Zusammenhänge hierzu.
Ausrichtung: Hier stellen Sie ein, ob das Dokument im Hochformat (Portraitmodus) oder im Querformat dargestellt wird.

Im Menü Vorschau, finden Sie bei aktiviertem PDF-Format Einträge zur Optimierung des Platzbedarfs für Ihre Bildschirmgröße.

Einzelseite
Doppelseite
Einzelseite scrollen
Doppelseite scrollen

Funktionen für Editor und Vorschau

Vorschau mit dem Editor koppeln

In der Standardeinstellung folgt die Vorschau beim Scrollen der gleichen Zeile wie der Editor. Dadurch befindet sich der entsprechende Text in der Vorschau stets auf derselben Höhe wie die aktuelle Zeile im Editor.

Wenn Sie jedoch Text aus einer anderen Vorschau kopieren und in den Editor einfügen möchten, können Sie diese Funktion im Menü Vorschau Mit Editor koppeln Leseposition deaktivieren.

Aufklappzustand mit dem Editor koppeln

Wenn in den Einstellungen die Option Schaltflächen zum Zuklappen von Abschnitten aktiviert ist, können Sie diese Kopplung hier separat deaktivieren.

Der Zustand des Aufklappens betrifft die Sektionen, also die Überschriften von == bis ======, jedoch nicht den Dokumenttitel.

Wenn Sie eine Sektion im Editor zuklappen, wird sie auch in der Vorschau zugeklappt. Selbst wenn der Editor ausgeblendet ist, werden in der Vorschau die Aufklapp-Dreiecke angezeigt, sodass Sie den Text weiterhin ein- oder ausblenden können.

Inhalt mit dem Editor koppeln

Über das Menü Vorschau Mit Editor koppeln Inhalt können Sie festlegen, ob eine Datei automatisch im Editor und in der Vorschau gleichzeitig angezeigt wird. Wenn diese Option aktiviert ist, wird alles, was Sie in der Seitenleiste auswählen, sowohl im Editor als auch in der Vorschau angezeigt.

TIP:Wenn Sie die ⌥-Taste gedrückt halten und auf eine Datei in der Seitenleiste klicken, wird die ausgewählte Datei im Editor abgekoppelt und nur in der Vorschau angezeigt. Auf diese Weise können Sie schnell eine Datei in der Vorschau anzeigen lassen und eine andere im Editor bearbeiten.

Exportieren

Wenn Sie eine Datei exportieren möchten, können Sie entweder das Menü Ablage Export Auswahl verwenden oder die Tastenkombination ⌥+⌘+E. Alternativ dazu befindet sich in der Symbolleiste rechts das -Symbol.

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:

Sie mit der Darstellung in der Vorschau zufrieden sind, setzen Sie einfach das Häkchen bei der Option Wie Vorschau und bestätigen Sie mit der Eingabetaste. Andernfalls stehen Ihnen in diesem Dialog erneut die Optionen für die Ausgabe zur Verfügung, wie bereits beim Abschnitt Vorschau beschrieben.

Format: Wählen Sie das gewünschte Zielformat der Datei (Text, HTML oder PDF).
Stil: Definieren Sie das Erscheinungsbild der Datei. Weitere Details finden Sie hier.
Aussehen: Legen Sie fest, ob das Dokument im Hell- oder Dunkelmodus angezeigt werden soll, oder überlassen Sie diese Entscheidung dem System.
Attribute: Bestimmen Sie vorgegebene oder benutzerdefinierte Attribute für die Ausgabe. Eine Einführung dazu finden Sie hier.
Spezifische Einstellungen für die Ausgabe: Passen Sie weitere Einstellungen entsprechend dem Ausgabeformat an.
Aktion: Wählen Sie aus, was mit der exportierten Datei geschehen soll. Standardmäßig ist "Exportieren" ausgewählt, den Sie nach dem Klick auf „Export“ ausführen können. Alternativ können Sie die Datei auch direkt per E-Mail versenden, über Apple AirDrop teilen oder auf andere Weise mit anderen Nutzern teilen.

Beim Exportieren im HTML-Format können Sie zusätzlich die Ausgabe der Ressourcen der HTML-Datei einstellen. Ressourcen einer HTML-Datei umfassen beispielsweise Medien und Stildateien. Hier sind einige mögliche Vorgaben:

Beim Exportieren im HTML-Format können Sie zusätzlich die Ausgabe der Ressourcen der HTML-Datei einstellen. Hier sind einige mögliche Vorgaben:

Separieren: Die Ressourcen werden als separate Dateien in einem Ordner neben der HTML-Datei abgelegt.
Eingliedern: Die Ressourcen werden in die HTML-Datei eingebettet.
Ohne: Die Ressourcen werden nicht exportiert.
Aus Attributen: Die Ressourcen werden nicht exportiert, aber die Attribute :stylesheet: und :stylesdir: werden beachtet. Wenn diese Attribute nicht vergeben sind, werden die Ressourcen exportiert.

In den Einstellungen finden Sie eine Liste mit der Sie spezielle Attribute für ein Dokument festlegen können. Öffnen Sie die Liste, um einen kleinen Dialog zu sehen, in dem Sie neue Attribute erstellen oder vorhandene Attribute auswählen können.

Alle Einträge in dieser Liste überschreiben die im Text eingegebenen Attribute und haben daher die höchste Priorität.

Produkte

Für Dokumente, die mit adoc Studio erstellt werden, ist eine langfristige Pflege und Ausgabe üblich. Daher ist ein Werkzeug nötig, das komplexe Exportkonfigurationen sowie häufige Wechsel zwischen verschiedenen Einstellungen und speziellen Attributen effizient verwaltet und schnell abrufbar macht. Diese Aufgabe übernehmen die Produkte.

Das Dialogfeld zur Konfiguration der Produkte öffnen Sie über das Menü Ablage Export Produkte … oder mit dem Tastaturkurzbefehl ⌘+⌃+E

Wenn Sie die Produkte zum ersten Mal aufrufen, ist die Liste auf der linken Seite noch leer. Durch Klicken auf das + - Symbol gelangen Sie zu einer Liste aller Dokumente. Wählen Sie hier das gewünschte Dokument oder Sammeldokument aus.

Auf der rechten Seite finden Sie nun verschiedene Optionen:

Produktname: Hier können Sie optional einen Namen für Ihr Produkt festlegen.
Quelle: Hier wählen Sie die Quelle für Ihr Produkt aus. Sie können diese Auswahl jederzeit ändern.
Dateiname: Geben Sie hier den Namen für die exportierte Datei ein. Wenn dieses Feld leer bleibt, wird entweder der Produktname oder, falls nicht vorhanden, der Dateiname der Quelle mit der entsprechenden Dateiendung verwendet.
Unterordner: Sie können hier optional ein Unterverzeichnis angeben, in dem das Produkt exportiert werden soll.

Jetzt können Sie dieselben Exportparameter wie im vorherigen Abschnitt, dem Exportieren, festlegen.

Produkte in der Symbolleiste

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

Richten Sie ein Produkt für die Ausgabe im HTML-Format und ein weiteres für das PDF-Format ein. Auf diese Weise können Sie ganz einfach zwischen der schnellen HTML-Vorschau und der etwas langsameren PDF-Vorschau in der Symbolleiste wechseln.

Produkte ausgeben

Um ein Produkt auszugeben, wählen Sie im Produkte-Dialog das gewünschte Ziel aus und klicken dann entweder auf Exportieren … oder Teilen. je nachdem, was Sie tun möchten.

Alternativ dazu können Sie auch mehrere Produkte gleichzeitig exportieren. Gehen Sie dazu im Produkte-Dialog zum Kontext-Menü oder klicken Sie auf und wählen Sie im Menü Export Mehrere Produkte den Eintrag. Dadurch erscheinen neben jedem Produkt Kontrollkästchen. Markieren Sie die Produkte, die Sie exportieren möchten, und klicken Sie dann auf Exportieren … oder Teilen.

Wenn Sie mehrere HTML-Exporte durchführen, teilen sich die Produkte die Ressourcen. Das bedeutet, dass Sie nach dem Export für jedes Produkt eine separate .html-Datei haben, jedoch nur einen Ordner mit gemeinsamen Bildern, CSS-Dateien usw.

Fehlt hier nicht noch was…?

Die Entwicklung von adoc Studio steht erst am Anfang. Für die erste Version wurde der Fokus auf Funktionen gelegt, von denen 80% der Benutzer sie benötigen. Aber es kann gut sein, dass gerade Ihnen eine bestimmte Funktion fehlt.

Selbst wenn Sie bereits mit AsciiDoc oder adoc Studio vertraut sind und feststellen, dass Ihnen etwas fehlt, können Sie aktiv die Entwicklung unterstützen. Melden Sie sich kostenlos auf der Roadmap-Plattform an und stimmen Sie für fehlenden Funktionen ab. Die Funktionen mit den meisten Stimmen werden bevorzugt umgesetzt.

Sie haben auch die Möglichkeit, eigene Wünsche zu äußern oder neue Funktionen vorzuschlagen. Möglicherweise werden Ihre Ideen auch von anderen Anwendern unterstützt. Auf diese Weise wird sichergestellt, dass die von Ihnen benötigten Funktionen als nächstes in adoc Studio erscheinen können.

Freuen Sie sich auf die spannenden Entwicklungen, die noch kommen werden!

Anhang A: Support

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

Systemanforderungen

Die minimalen Systemanforderungen für die Nutzung von adoc Studio sind:

macOS 13 Ventura
iOS 16

Erste Hilfe

Forum: Ihnen steht ein kostenloses Forum zur Verfügung, in dem Ihnen auch das Team der ProjectWizards mit Rat und Tat zur Seite steht.
Die adoc Studio Roadmap: Damit Sie die weitere Entwicklung nicht nur sehen, sondern auch darauf einen Einfluss nehmen können, steht Ihnen eine öffentliche Roadmap offen. 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, an einer Übersetzung wird gearbeitet.
Eigene Erfahrungen mit AsciiDoc: Im Blog der ProjectWizards-Webseite finden Sie eine ganze Reihe praktischer Artikel zum Thema AsciiDoc.
Weitere Tipps zu AsciiDoc: Auf Awesome Asciidoc(tor) finden Sie eine umfangreiche Sammlung verschiedener Tipps und Tricks zu AsciiDoc.

Hilfe mit Vorlagen und Stilen

Zur Zeit entsteht ein Partnernetzwerk, das Ihnen gerne beim Aufbau Ihrer Vorlagen und der Gestaltung der Produktstile hilft. Die aktuelle Liste der Partner finden Sie Online.

Im Laufe der Zeit wird dort auch ein Verzeichnis aller Stile aufgebaut. Sollten Sie Lust haben, aktiv mitzuwirken, schreiben Sie eine Nachricht an: office@projectwizards.net.

Anhang B: Reguläre Ausdrücke

Mit zunehmendem Umfang eines Schreibprojekts wird auch die Suche nach Inhalten immer komplexer. Anstatt in jeder Datei Wort für Wort zu suchen und möglicherweise zu ersetzen, können Sie auch nach einem bestimmten Muster im Text suchen, um relevante Textstellen zu finden. Diese Muster werden als reguläre Ausdrücke bezeichnet. Da dieser Begriff etwas sperrig ist, verwenden viele den englischen Ausdruck Regular Expressions und verkürzen ihn zu RegEx.

Ein kurzes Beispiel verdeutlicht die Mächtigkeit dieser Grammatik:

Die Suche nach h*.us ersetzt das *. mit einem oder mehr beliebigen Zeichen. Dadurch findet sie Wörter wie Haus, House und sogar Huus. Jedoch nicht Hans, sondern nur Worte, die mit einem "h" beginnen und mit "us" enden.

Es gibt viele solcher Muster, die aus einem oder mehr Zeichen, Operatoren oder Konstrukten bestehen können. Im Folgenden erhalten Sie einen ersten Überblick darüber.

Reguläre Ausdruck-Metazeichen

Die folgenden Tabellen erklären die Zeichenausdrücke, die reguläre Ausdrücke verwenden, um Muster in einem Text zu finden. Die Musteroperatoren zeigen, wie oft ein Muster abgeglichen wird und legen zusätzliche Abgleichsbedingungen fest. Die letzte Tabelle listet Flags auf, die in das Muster eines regulären Ausdrucks eingefügt werden können, um das Suchverhalten über mehrere Zeilen hinweg anzupassen.

Quelle: https://developer.apple.com/documentation/foundation/nsregularexpression

Die Tabelle Reguläre Ausdruck-Metazeichen beschreibt die Zeichenfolgen, die verwendet werden, um Zeichen innerhalb einer Zeichenkette abzugleichen.

Tabelle 6. Reguläre Ausdruck-Metazeichen
Zeichenausdruck	Beschreibung
\a	Entspricht einem GLOCKENZEICHEN, \u0007
\A	Entspricht am Anfang der Eingabe. Unterscheidet sich von ^, da \A nicht nach einem neuen Zeilenzeichen innerhalb der Eingabe entspricht.
\b, außerhalb eines [Sets]	Entspricht, wenn die aktuelle Position eine Wortgrenze ist. Grenzen treten an den Übergängen zwischen Wort (\w) und Nicht-Wort (\W) Zeichen auf, wobei Kombinationszeichen ignoriert werden.
\b, innerhalb eines [Sets]	Entspricht einem RÜCKSPRUNGZEICHEN, \u0008.
\B	Entspricht, wenn die aktuelle Position keine Wortgrenze ist.
\cX	Entspricht einem Steuer-X Zeichen.
\d	Entspricht jedem Zeichen mit der Unicode Allgemeinen Kategorie Nd (Zahl, Dezimalziffer).
\D	Entspricht jedem Zeichen, das keine Dezimalziffer ist.
\e	Entspricht einem ESCAPE, \u001B.
\E	Beendet eine \Q … \E zitierte Sequenz.
\f	Entspricht einem SEITENWECHSEL, \u000C.
\G	Entspricht, wenn die aktuelle Position am Ende des vorherigen Abgleichs ist.
\n	Entspricht einem ZEILENVORSCHUB, \u000A.
\N{UNICODE-ZEICHENNAME}	Entspricht dem benannten Zeichen.
\p{UNICODE-EIGENSCHAFTSNAME}	Entspricht jedem Zeichen mit der angegebenen Unicode-Eigenschaft.
\P{UNICODE-EIGENSCHAFTSNAME}	Entspricht jedem Zeichen, das nicht die angegebene Unicode-Eigenschaft hat.
\Q	Zitiert alle folgenden Zeichen bis \E.
\r	Entspricht einem WAGENRÜCKLAUF, \u000D.
\s	Entspricht einem Leerzeichen. Leerzeichen sind definiert als [\t\n\f\r\p{Z}].
\S	Entspricht einem Nicht-Leerzeichen.
\t	Entspricht einer HORIZONTALTABULATION, \u0009.
\uhhhh	Entspricht dem Zeichen mit dem Hex-Wert hhhh.
\Uhhhhhhhh	Entspricht dem Zeichen mit dem Hex-Wert hhhhhhhh. Genau acht Hex-Ziffern müssen angegeben werden, obwohl der größte Unicode-Codepunkt \U0010ffff ist.
\w	Entspricht einem Wortzeichen. Wortzeichen sind [\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}].
\W	Entspricht einem Nicht-Wort-Zeichen.
\x{hhhh}	Entspricht dem Zeichen mit dem Hex-Wert hhhh. Von einer bis sechs Hex-Ziffern können angegeben werden.
\xhh	Entspricht dem Zeichen mit dem zweistelligen Hex-Wert hh.
\X	Entspricht einem Graphem-Cluster.
\Z	Entspricht, wenn die aktuelle Position am Ende der Eingabe ist, jedoch vor dem letzten Zeilenende, wenn eines vorhanden ist.
\z	Entspricht, wenn die aktuelle Position am Ende der Eingabe ist.
\n	Rückverweis. Entspricht dem, was die n-te Erfassungsgruppe abgeglichen hat. n muss eine Zahl ≥ 1 und ≤ Gesamtanzahl der Erfassungsgruppen im Muster sein.
\0ooo	Entspricht einem Oktal-Zeichen. ooo ist von ein bis drei Oktal-Ziffern. 0377 ist das größte erlaubte Oktal-Zeichen. Die führende Null ist erforderlich; sie unterscheidet Oktalkonstanten von Rückverweisen.
[Muster]	Entspricht jedem einzelnen Zeichen aus dem Muster.
.	Entspricht jedem Zeichen. Siehe dotMatchesLineSeparators und den s Zeichenausdruck in Tabelle 4.
^	Entspricht am Anfang einer Zeile. Siehe anchorsMatchLines und den \m Zeichenausdruck in Tabelle 4.
$	Entspricht am Ende einer Zeile. Siehe anchorsMatchLines und den m Zeichenausdruck in Tabelle 4.
\	Zitiert das folgende Zeichen. Zeichen, die zitiert werden müssen, um als Literale behandelt zu werden, sind * ? + [ ( ) { } ^ $ \| \ . /

Reguläre Ausdruck-Operatoren

Die Tabelle Reguläre Ausdruck-Operatoren definiert die regulären Ausdruck-Operatoren.

Tabelle 7. Reguläre Ausdruck-Operatoren
Operator	Beschreibung

Alternation. A	B entspricht entweder A oder B.
*	Entspricht 0 oder mehrmals. Entspricht so oft wie möglich.
+	Entspricht 1 oder mehrmals. Entspricht so oft wie möglich.
?	Entspricht null oder einmal. Bevorzuge einmal.
{n}	Entspricht genau n-mal.
{n,}	Entspricht mindestens n-mal. Entspricht so oft wie möglich.
{n,m}	Entspricht zwischen n und m-mal. Entspricht so oft wie möglich, aber nicht mehr als m.
*?	Entspricht 0 oder mehrmals. Entspricht so selten wie möglich.
+?	Entspricht 1 oder mehrmals. Entspricht so selten wie möglich.
??	Entspricht null oder einmal. Bevorzuge null.
{n}?	Entspricht genau n-mal.
{n,}?	Entspricht mindestens n-mal, aber nicht mehr als für einen Gesamtmusterabgleich erforderlich.
{n,m}?	Entspricht zwischen n und m-mal. Entspricht so selten wie möglich, aber nicht weniger als n.
*+	Entspricht 0 oder mehrmals. Entspricht so oft wie möglich, wenn zuerst aufgetreten. Versuche nicht erneut mit weniger, selbst wenn der Gesamtabgleich fehlschlägt (besitzergreifender Abgleich).
++	Entspricht 1 oder mehrmals (besitzergreifender Abgleich).
?+	Entspricht null oder einmal (besitzergreifender Abgleich).
{n}+	Entspricht genau n-mal.
{n,}+	Entspricht mindestens n-mal (besitzergreifender Abgleich).
{n,m}+	Entspricht zwischen n und m-mal (besitzergreifender Abgleich).
(…)	Erfassende Klammern. Bereich der Eingabe, der der eingeklammerten Unterexpression entspricht, ist nach dem Abgleich verfügbar.
(?:…)	Nicht-erfassende Klammern. Gruppiert das eingeschlossene Muster, bietet jedoch kein Erfassen des abgeglichenen Textes. Etwas effizienter als erfassende Klammern.
(?>…)	Atomare Abgleich-Klammern. Der erste Abgleich der eingeklammerten Unterexpression ist der einzige versuchte; wenn er nicht zu einem Gesamtmusterabgleich führt, wird die Suche nach einem Abgleich auf eine Position vor dem "(?>" zurückgesetzt.
(?# … )	Freiformkommentar (?# Kommentar).
(?= … )	Vorausschau-Assertion. Wahr, wenn das eingeklammerte Muster an der aktuellen Eingabeposition entspricht, jedoch die Eingabeposition nicht voranschreitet.
(?! … )	Negative Vorausschau-Assertion. Wahr, wenn das eingeklammerte Muster nicht an der aktuellen Eingabeposition entspricht. Schreitet die Eingabeposition nicht voran.
(?⇐ … )	Rückschau-Assertion. Wahr, wenn das eingeklammerte Muster dem Text vor der aktuellen Eingabeposition entspricht, wobei das letzte Zeichen des Abgleichs das Eingabezeichen unmittelbar vor der aktuellen Position ist. Ändert die Eingabeposition nicht. Die Länge möglicher durch das Rückschaumuster abgeglichener Zeichenketten darf nicht ungebunden sein (keine * oder + Operatoren).
(?<! … )	Negative Rückschau-Assertion. Wahr, wenn das eingeklammerte Muster dem Text vor der aktuellen Eingabeposition nicht entspricht, wobei das letzte Zeichen des Abgleichs das Eingabezeichen unmittelbar vor der aktuellen Position ist. Ändert die Eingabeposition nicht. Die Länge möglicher durch das Rückschaumuster abgeglichener Zeichenketten darf nicht ungebunden sein (keine * oder + Operatoren).
(?ismwx-ismwx: … )	Flag-Einstellungen. Bewertet den eingeklammerten Ausdruck mit den aktivierten oder -deaktivierten angegebenen Flags. Die Flags sind in den Flag-Optionen definiert.
(?ismwx-ismwx)	Flag-Einstellungen. Ändert die Flag-Einstellungen. Änderungen gelten für den Teil des Musters nach der Einstellung. Zum Beispiel ändert (?i) zu einem Groß-/Kleinschreibung-unempfindlichen Abgleich. Die Flags sind in den Flag-Optionen definiert.

Vorlagenabgleichsformat

Der reguläre Ausdruck bietet Suchen-und-Ersetzen-Operationen für sowohl unveränderliche als auch veränderliche Zeichenketten mit der Technik des Vorlagenabgleichs. Tabelle Vorlagenabgleichsformat beschreibt die Syntax.

Tabelle 8. Vorlagenabgleichsformat
Zeichen	Beschreibung
$n	Der Text der Erfassungsgruppe n wird durch $n ersetzt. n muss >= 0 und nicht größer als die Anzahl der Erfassungsgruppen sein. Ein $, dem keine Ziffer folgt, hat keine besondere Bedeutung und erscheint im Ersetzungstext als es selbst, ein $.
\	Behandelt das folgende Zeichen als Literal, unterdrückt jegliche besondere Bedeutung. Backslash-Escaping im Ersetzungstext ist nur für '$' und '' erforderlich, kann jedoch bei jedem anderen Zeichen ohne negative Auswirkungen verwendet werden.

Flag-Optionen

Die folgenden Flags steuern verschiedene Aspekte des Abgleichs regulärer Ausdrücke. Diese Flag-Werte können innerhalb des Musters mit den (?ismx-ismx) Musteroptionen angegeben werden. Äquivalente Verhaltensweisen können für das gesamte Muster angegeben werden, wenn ein regulärer Ausdruck initialisiert wird.

Tabelle 9. Flag-Optionen
Flag (Muster)	Beschreibung
i	Wenn gesetzt, findet der Abgleich groß-/kleinschreibungsunabhängig statt.
x	Wenn gesetzt, erlaubt die Verwendung von Leerzeichen und #Kommentaren in Mustern.
s	Wenn gesetzt, wird ein "." in einem Muster einen Zeilenabschluss im Eingabetext abgleichen. Standardmäßig wird das nicht der Fall sein. Beachten Sie, dass eine Wagenrücklauf-/Zeilenvorschub-Kombination im Text als ein einzelner Zeilenabschluss fungiert und einen einzelnen "." in einem regulären Ausdrucksmuster abgleichen wird.
m	Steuert das Verhalten von "^" und "$" in einem Muster. Standardmäßig entsprechen diese nur am Anfang bzw. am Ende des Eingabetextes. Wenn dieses Flag gesetzt ist, werden "^" und "$" auch am Anfang und Ende jeder Zeile innerhalb des Eingabetextes entsprechen.
w	Steuert das Verhalten von \b in einem Muster. Wenn gesetzt, werden Wortgrenzen gemäß den Definitionen von Wort in Unicode UAX 29, Textgrenzen, gefunden. Standardmäßig werden Wortgrenzen durch eine einfache Klassifizierung von Zeichen als entweder „Wort“ oder „Nicht-Wort“ identifiziert, was das traditionelle Verhalten regulärer Ausdrücke annähernd nachahmt. Die Ergebnisse, die mit den beiden Optionen erzielt werden, können bei Läufen von Leerzeichen und anderen Nicht-Wort-Zeichen sehr unterschiedlich sein.

Anhang C: Glossar

Das Glossar bietet Übersetzungen einiger Begriffe aus adoc Studio, die ursprünglich aus dem Vokabular von AsciiDoc stammen und daher englischsprachig sind. Diese Übersetzungen führen zu einer Mischung aus englischen und deutschen Begriffen. Das Glossar hilft Ihnen, sich in diesem Sprachgemisch zurechtzufinden.

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 identischer Abgrenzungszeichen in separaten Zeilen begrenzt wird. Solche Blöcke dienen entweder dazu, andere Blöcke zu umfassen (z.B. mehrere Absätze) oder um das Inhaltsmodell des enthaltenen Inhalts festzulegen (z.B. wortwörtlicher Text).

Absatz: In den meisten Dokumenten ist der Absatz der wichtigste Blocktyp. Sie müssen 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 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 den Abschnittstitel folgen, bis zum nächsten gleichrangigen oder übergeordneten Abschnittstitel oder bis zum Ende des Dokuments.

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 der Begriff auch als ein Synonym zur Präambel verwendet.
Admonition: siehe Hinweis

adoc: Die Kurzform für adoc Studio 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 ans Endes eines Dokuments zu stellen.
Anker: Ein Anker ist ein Sprungziel, das über das ID-Attribut definiert wird.

Artikel: Der Artikel ist der Standard-Doctype in adoc Studio. Er umfasst optional die 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 von 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 und anderen Formaten. Um PDF-Dokumente zu erstellen, wird Asciidoctor PDF benötigt. Im Grunde ist es 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.

Asciidoctor PDF: Ist ein Kommandozeilen-Werkzeug zum Parsen vonAsciiDoc-Dateien und deren Konvertierung in das Ausgabeformat PDF. Asciidoctor PDF ist OpenSource und wird von Dan Allen entwickelt.

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 falsch – an 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 vö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: Das 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

Link

tbd:

links
Hyperlinks
crosslink

Listenblock

Wird durch eine Gruppe von geschwisterlichen Listenelementen definiert, die jeweils durch die gleiche Markierung gekennzeichnet sind.

Listenfortsetzung

Eine Listenfortsetzung ist ein Pluszeichen (+) in einer Zeile, das benachbarte Textzeilen zu einem Listenelement verbindet.

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.

Querverweis (Crosslink): Ist ein Link von einer bestimmten Stelle zu einer anderen Position im Dokument, die durch einen Anker gekennzeichnet ist.

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 Schreibfluss 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 (wie zum Beispiel Git) dient dazu mehrere Versionen eines Dokumentes platzsparend zu verwalten. Bei den meisten Versionsverwaltungssystemen wird neben dem Originaldokument, nur noch die Änderungen gespeichert, die notwendig sind um eine bestimmte Version zu erzeugen. Ausserdem wird durch eine Versionsverwaltung das gemeinsame Arbeiten an ein und demselben Dokument ermö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. und in allen anderen Betriebssystemen

2. Hier ist der Text der Fußnote

Arbeiten mit adoc Studio

Notation in diesem Dokument

Rechtliche Hinweise

Was ist adoc Studio?

Was ist eine Auszeichnungssprache?

Betrachtung von Word, Pages oder Google Docs

Installation

Systemanforderungen

Testphase & Lizenzierung

adoc Studio kennenlernen

Die Benutzeroberfläche

Der Projektnavigator

Ein neues Projekt anlegen

Alleinstehende Dokumente verwenden

Sammeldokumente verwenden

Ordner zur Strukturierung verwenden

Medienordner verwenden

Neue Komponente einfügen

Bestehende Dateien einfügen

Dateiinformationen

Ein Projekt sichern

Weitere Fenster für ein Projekt

Externe Projekte

Der Abschnitt-Navigator

Der Such-Navigator

Besonderheiten

Der Problem-Navigator

Schreiben und im Text navigieren

Zusatznavigation

Zeilennummern

Cursor

Eingabehilfen

Beispiel: Ein Bild im Text einbinden

Programmeinstellungen

Allgemein

Dateizugriff

Editorstile

Produktstile

Eigene Produktstile installieren

Produktstile entfernen

Eigene Produktstile erstellen

Einen Stil bearbeiten

Die Auszeichnungssprache AsciiDoc

Was ist AsciiDoc?

Text schreiben

Die Präambel

Formatierungen

Überschriften

Inhaltsverzeichnis

Links

Hyperlinks ins Internet

Querverweise im Dokument

Fußnoten

Bilder

Blockbilder

Inline-Bilder

Listen

Blockelemente

Hinweise

Tabellen

Benutzerschnittstelle

Kommentare

Attribute

Nutzung von Attributen als Variable

Attribute zur Dokumenteinstellung

Eingebaute Attribute

Benutzerdefinierte Attribute

Bedingte Anweisungen

Includes

Dokumente ausgeben

Die Vorschau

HTML-Vorschau und Einstellungen

Text-Vorschau und Einstellungen

PDF-Vorschau und Einstellungen

Funktionen für Editor und Vorschau

Vorschau mit dem Editor koppeln

Aufklappzustand mit dem Editor koppeln

Inhalt mit dem Editor koppeln

Exportieren

Produkte