4. Exportieren
Für die Ausgabe von Dokumenten bietet adoc Studio besonders für umfangreiche und langfristige Projekte nützliche Funktionen. Sie können zwischen dem einmaligen normalen Export eines Dokuments und der wiederholten Ausgabe von Produkten wählen. Zuvor lohnt sich jedoch ein Blick auf die Vorschau.
4.1. Die Vorschau
Rechts neben dem Editor finden Sie die Vorschau. Ist sie nicht sichtbar, klicken Sie auf das Symbol oder verwenden Sie den Tastaturkurzbefehl ⇧+⌘+P, um sie einzublenden.
Die Vorschau passt sich automatisch dem gewählten Ausgabeformat an. Je nach Einstellung kann sie wie ein Browser für HTML-Seiten oder wie eine PDF-Vorschau aussehen.
Das Ausgabeformat wählen Sie im Dialogfeld hinter dem Symbol rechts neben . Hier lassen sich auch weitere, formatspezifische Einstellungen vornehmen.
Im Kontextmenü der Vorschau stehen zwei besonders nützliche Funktionen zur Projektnavigation zur Verfügung:
- Quelle zeigen
-
Setzt den Fokus im Editor an die entsprechende Stelle des Quelltexts.
Diese Funktion ist in macOS 14 (Sonoma) nicht verfügbar. - Im Projektnavigator zeigen
-
Selektiert im Projektnavigator die zugehörige Quelldatei.
Zusätzlich finden Sie im Kontextmenü weitere Funktionen, die vom Betriebssystem bereitgestellt werden.
HTML-Vorschau und Einstellungen
Wenn Sie das Ausgabeformat auf HTML einstellen, zeigt der Editor Ihr Dokument als durchgehendes HTML-Dokument an.
-
Stil: Wählen Sie den gewünschten Produkt-Stil für die Vorschau Ihres Dokuments.
-
Erscheinung: Legen Sie fest, ob die Darstellung hell oder dunkel sein soll, oft als Brightmode bzw. Darkmode bezeichnet. Bei automatischer Einstellung orientiert sich adoc Studio an den Systemeinstellungen Ihres Betriebssystems.
-
Attribute: Verwalten Sie die Dokumentattribute. Neben den im Dokument definierten Attributen können Sie hier über einen Dialog zusätzliche Attribute festlegen. Weitere Details finden Sie in der Beschreibung der Produkte.
PDF-Vorschau und Einstellungen
Die PDF-Vorschau zeigt das Dokument genau so an, wie es beim Export in eine Datei geschrieben wird. Die Optionen im Klappmenü hinter dem Symbol umfassen neben Stil, Erscheinung und Attributen zusätzlich folgende Einstellungen:
-
Papier: Legen Sie Drucker, Papierformat und Seitenränder fest. Weitere Details und Zusammenhänge finden Sie im Kapitel über Produktstile.
-
Ausrichtung:Wählen Sie zwischen Hochformat (Portraitmodus) und Querformat.
Im Menü Vorschau stehen Ihnen bei aktiviertem PDF-Format zusätzliche Optionen zur Anpassung der Anzeige an Ihre Bildschirmgröße zur Verfügung:
-
Einzelseite
-
Doppelseite
-
Einzelseite scrollen
-
Doppelseite scrollen
4.2. Funktionen für Editor und Vorschau
Über dem Editor oder der Vorschau sehen Sie eine horizontale Linie, sie markiert den aktuellen Fokus. Der Fokus bestimmt, welcher Bereich Ihre Tasteneingaben empfängt.
Mit der Maus oder dem Tastaturkurzbefehl ⌃+Tab wechseln Sie zwischen Editor, Vorschau und Projektnavigator.
Vorschau mit dem Editor koppeln
In der Standardeinstellung folgt die Vorschau beim Scrollen der Position der Einfügemarke (Schreibmarke) im Editor.
So bleibt der Text in der Vorschau immer auf derselben Höhe wie die aktuelle Zeile im Editor. Mit der ⌥-Taste können Sie dieses Verhalten kurzfristig außer Kraft setzen.
Dann scrollt die Vorschau unabhängig von der Position der Einfügemarke.
Möchten Sie das automatische Folgen dauerhaft deaktivieren, zum Beispiel, um Text aus einer anderen Vorschau zu kopieren und im Editor einzufügen.
Nutzen Sie die Option im Menü .
| Halten Sie die ⌥-Taste gedrückt, um auch andere Dateien aus dem Projektnavigator in der Vorschau anzuzeigen, ohne sie im Editor zu öffnen. |
Aufklappzustand mit dem Editor koppeln
Aktivieren Sie in den Einstellungen die Option Schaltflächen zum Zuklappen von Abschnitten, um die Kopplung zu nutzen, oder deaktivieren Sie sie hier separat.
Der Aufklappzustand gilt für die Sektionen – also Überschriften von == bis ====== – nicht jedoch für den Dokumenttitel.
Klappen Sie eine Sektion im Editor zu, wird sie automatisch auch in der Vorschau zugeklappt.
Selbst wenn der Editor ausgeblendet ist, zeigt die Vorschau die `Aufklappdreiecke ( / ) weiterhin an, sodass Sie den Text nach Bedarf ein- oder ausblenden können.
Inhalt mit dem Editor koppeln
Über das Menü legen Sie fest, ob eine Datei automatisch gleichzeitig im Editor und in der Vorschau angezeigt wird.
Ist die Option aktiviert, zeigt adoc Studio alles, was Sie in der Seitenleiste auswählen, sowohl im Editor als auch in der Vorschau.
| Wenn Sie die ⌥-Taste gedrückt haltenund klicken Sie auf eine Datei in der Seitenleiste, um sie im Editor zu entkoppeln. Die Datei wird dann nur in der Vorschau angezeigt, sodass Sie parallel eine andere Datei im Editor bearbeiten können. |
4.3. Export
Sie können eine Datei entweder über das Menü exportieren oder den Tastaturkurzbefehl ⌥+⌘+E verwenden. Alternativ klicken Sie in der Symbolleiste auf das Symbol.
Sind Sie mit der Darstellung in der Vorschau zufrieden, setzen Sie ein Häkchen bei Wie Vorschau und drücken ⏎.
Andernfalls stehen Ihnen die bekannten Optionen für die Ausgabe zur Verfügung, wie bereits bei der Vorschau beschrieben:
-
Format: Wählen Sie das gewünschte Zielformat (Text, HTML, Webseite oder PDF).
-
Stil: Legen Sie das Erscheinungsbild der Datei fest. Weitere Details finden Sie hier.
-
Aussehen: Bestimmen Sie Hell- oder Dunkelmodus oder lassen Sie das System die Entscheidung treffen.
-
Attribute: Definieren Sie vorgegebene oder benutzerdefinierte Attribute. Eine Einführung finden Sie hier.
-
Spezifische Einstellungen für die Ausgabe: Passen Sie weitere Optionen je nach Ausgabeformat an.
-
Aktion: Legen Sie fest, was mit der exportierten Datei geschehen soll. Standardmäßig wird „Exportieren“ ausgeführt. Alternativ können Sie die Datei per E-Mail versenden, über Apple AirDrop teilen oder anderweitig weitergeben.
Beim Export ins HTML-Format können Sie zusätzlich festlegen, wie die Ressourcen (Medien, Stildateien) ausgegeben werden:
-
Separieren: Ressourcen werden als separate Dateien neben der HTML-Datei gespeichert.
-
Eingliedern: Ressourcen werden direkt in die HTML-Datei eingebettet.
-
Ohne: Ressourcen werden nicht exportiert.
-
Aus Attributen: Ressourcen werden nicht exportiert, aber die Attribute
:stylesheet:und:stylesdir:werden berücksichtigt.-
Ist
:data-uri:gesetzt, werden Bilder als Base64 inline eingebettet. -
Ohne
:data-uri:landen Bilder im Ressourcen-Ordner. -
Mit `:linkcss: wird das Stylesheet als Text in die HTML-Datei eingebettet, sonst im Ressourcen-Ordner.
-
In den Einstellungen können Sie spezielle Attribute für ein Dokument definieren. Öffnen Sie die Liste, um neue Attribute zu erstellen oder vorhandene auszuwählen.
| Alle Einträge in dieser Liste werden von den im Text definierten Attributen überschrieben, außer das Attribut ist im Dialog auf @. |
Bilder exportieren
Bilder stellen beim Export oft eine Herausforderung dar – besonders bei der Auflösung. Das Produkt-Team liefert Bilder meist in maximaler Auflösung, was für die Anzeige auf mobilen Geräten zu groß sein kann.
In adoc Studio steuern Sie den Umgang mit Bildern über Attribute, die Sie im Dokumentkopf setzen:
ads-max-image-resolution
Legen Sie die maximale Auflösung für Bilder in HTML- und PDF-Exporten fest.
Geben Sie die Werte in dpi, dpcm oder dppx an. Für HTML beeinflusst diese Einstellung nur Bilder, bei denen im Quelltext eine Breite oder Höhe explizit angegeben ist.
Möchten Sie die Größe von Bildern ohne festgelegte Breite oder Höhe begrenzen, verwenden Sie das Attribut ads-max-image-width.
-
:ads-max-image-resolution: 72dpi
begrenzt Bilder in der Ausgabe auf 72dpi
ads-max-image-width
Legen Sie für den HTML-Export die maximale Pixelbreite für diejenigen Bilder fest, für die Sie im Quelltext keine Breite oder Höhe angegeben haben.
-
:ads-max-image-width: 200px
begrenzt Bilder in der Breite auf 200 Pixel.
ads-rasterizing-resolution
Wenn Sie einen Wert setzen, werden PDF- und SVG-Bilder sowie STEM-Gleichungen in HTML-Exporten in PNG-Bilder umgewandelt. Sie können Auflösungswerte in dpi, dpcm oder dppx angegeben.
-
:ads-rasterizing-resolution: 72dpi
begrenzt Bilder in der Ausgabe auf 72dpi.
PDF/UA-Konformität
PDF/UA steht für "Universal Accessibility" und ist ein internationaler ISO-Standard (ISO 14289) für barrierefreie PDF-Dokumente. Das Ziel ist, dass die Dokumente für alle Menschen, einschließlich Menschen mit Behinderungen, zugänglich sind. PDF/UA ist kein eigenes Dateiformat, sondern eine Methode, das bestehende PDF-Format so zu strukturieren, dass es barrierefrei ist. Mehr bei Wikipedia.
ads-pdf-ua
Wenn Sie das Attribut setzen, fügt der PDF-Export Barrierefreiheitsinformationen gemäß dem PDF/UA-Standard hinzu. Standardmäßig ist diese Option deaktiviert.
Möchten Sie ein Dokument PDF/UA-konform machen, aktivieren Sie einfach das Attribut:
-
:ads-pdf-ua:
4.4. Produkte
Für Dokumente, die mit adoc Studio erstellt werden, ist eine langfristige Pflege und regelmäßige Ausgabe üblich. Fast schon wie ein Produkt aus der Softwareentwicklung – daher der Name. Sie benötigen ein Werkzeug, 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ü 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 geben Sie dem Produkt optional einen Namen.
-
Quelle: Hier wählen Sie das oder die Dokumente, Sammeldokumente oder Ordner aus dem Ihr Produkt erstellt wird.
-
Sprache: Falls im Projekt unterschiedliche Sprachen definiert wurden, entscheiden Sie für welche Sprachen die Ausgabe erfolgen soll.
-
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. Gerade, wenn sie gleichzeitig mehrere Produkte ausgeben, ist das sehr sinnvoll.
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 je Produkt das HTML-Format und das PDF-Format ein. Auf diese Weise wechseln Sie in der Symbolleiste schnell zwischen der HTML-Vorschau und der PDF-Vorschau. |
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.
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ü 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.
4.5. Webseiten
Mit adoc Studio wurde in der Pro Version ein weiteres Exportformat eingeführt: die Webseite. Es erlaubt ein Dokumentationsprojekt als eigenständige Webseite zu exportieren. Natürlich ist auch die automatisierte Ausgabe via Produkte und per Kommandozeile vorgesehen.
In der Grundstruktur sieht eine erzeugte Webseite wie rechts dargestellt aus. Den Text umgibt (im Bild blau dargestellt):
-
Top-Menü
-
Seiten-Menü
-
Satelliten-Menü
-
Vor- und Zurück-Blättern
-
PDF-Download
Natürlich kann diese Struktur durch einen CSS-Designer beliebig geändert werden.
| Das aktuelle Stylesheet ist für moderne Browser und Mobilgeräte sowie Smartphones optimiert. |
Konfiguration
Das Konzept zur Strukturierung der Webseite unterscheidet sich in adoc Studio von anderen Werkzeugen. Während dort immer zuerst eine Struktur für die Navigation aufbauen müssen, generiert adoc Studio die Webseite automatisch aus der vorhandenen Dokumentstruktur. Natürlich haben Sie Optionen für die Ebenen und Strukturtiefen.
Wählen Sie im Export-Dialog oder in der Konfiguration der Produkte die Webseite aus, finden Sie im unteren Teil zwei neue Einträge:
-
Navigation
-
PDF’s
Während letzterer für die zusätzliche Einbettung eines PDFs dient, schauen wir nun erst auf die Navigation.
HTML-Seiten
Sie wählen zuerst aus, wie kleinteilig Ihre Dokumente in HTML-Dateien aufgeteilt werden. Die Standardeinstellung ist »Für Dokumente«. Dadurch werden jedes Dokumente in dem Projekt auch in der Webseite als einzelne HTML-Seiten generiert.
Möchten Sie den Leser der Webseite kleinere Dokumentschnipsel anbieten, stehen für die Aufteilung alle Abschnittsebenen bereit.
Top-Navigation
In der Top-Navigation erscheinen die Projektinhalte von:
-
bis zu drei Ordnerebenen,
-
bis zu drei Ebenen von Ordnern und Dokumenten,
-
bis zu drei Ebenen von Ordnern, Dokumenten und Abschnitten,
-
oder bis zu drei Abschnittsebenen
Seitliche Navigation
Haben Sie eine Tip-Navigation angegeben, können hier:
-
bis zu drei weitere Ordnerebenen,
-
bis zu drei weitere Ebenen von Ordnern und Dokumenten,
-
bis zu drei weitere Ebenen von Ordnern, Dokumenten und Abschnitten,
-
oder einfach nur bis zu drei Abschnittsebene vorgegeben werden.
Die zur Verfügung stehenden Möglichkeiten in adoc Studio werden immer dynamisch angepasst.
Satellitennavigation
Eine Satellitennavigation ist ein weiterer Bereich auf der Webseite, in dem Überschriften zur Navigation dargestellt werden. Wichtig ist eine Satellitennavigation auf umfangreichen oder stark strukturieren Seiten. Dieser wird oft dort eingeblendet, wo auch der Inhalt dargestellt wird. Damit funktioniert die Navigation auch wenn die Top- oder Seiten-Navigation nicht dargestellt ist.
In adoc Studio ist die Satellitennavigation optional. Zuvor wird die Top- und Seiten-Navigation generiert. Sollten am Ende noch Navigationsebenen übrig sein, können bis zu drei weitere Ebenen eingeblendet werden.
| Je kleinteiliger Ihre HTML-Dokumente generiert werden, um so seltener werden Sie eine Satellitennavigation erhalten. |
Blättern
Um das bequeme Blättern in einer Dokumentation einzubinden, aktivieren Sie nur die Checkbox Mit Blättern. Den Rest erledigt adoc Studio für Sie.
Die Anzeige der vorherigen und nächsten Themen wird dabei aus den Überschriften der entsprechenden Abschnitten generiert.
-
Grundkonzept
-
Navigation zuweisen
-
Blättern
-
Suche
-
PDF
-
Responsives Design
-
lokales Testen der Webseite
4.6. Kommandozeile
In vielen Fällen wird eine Dokumentation automatisiert über Skripte ausgegeben.
Installation
Vor der ersten Nutzung auf dem Mac starten Sie mit dem Menüeintrag das Installationsprogramm. Ist das Kommandozeilen-Werkzeug bereits installiert, lautet der Menüeintrag statt dessen: .
Folgen Sie nach dem Aufruf den den Anweisungen auf dem Bildschirm und geben Sie zur Installation Ihr Benutzerpasswort ein. Damit erlauben Sie dem Installationsprogramm auf Ihrem Mac im Verzeichnis /usr/local/bin/ das Werkzeug adocstudio zu installieren.
Aufruf und Optionen
Geben Sie im Terminal nur den Befehl adocstudio ein, erhalten Sie folgende Ausgabe:
OVERVIEW: Export content from an adoc Studio project in HTML, PDF or text format.
USAGE: adocstudio export <subcommand>
OPTIONS:
-h, --help Show help information.
SUBCOMMANDS:
products Export products from an adoc Studio project using their
pre-defined configuration.
documents Export documents from an adoc Studio project with custom
configuration
See 'adocstudio help export <subcommand>' for detailed help.
Das heißt, das Kommandozeilen-Tool ist in zwei Unterkommandos aufgeteilt:
-
export products
-
export documents
Beide erwarten verschiedene Parameter, haben aber eines gemeinsam. Es muss immer aus einem Projekt exportiert werden. Der Export einer einzelnen, nicht in einem Projekt enthaltenen Datei, ist nicht möglich.
Dokumente exportieren
Schauen wir uns zunächst die Hilfe für die Dokumente an. Mit der Eingabe adocstudio help export documents erhalten wir:
OVERVIEW: Export documents from an adoc Studio project with custom configuration
USAGE: adocstudio export documents --project <project> --document <document> ... [--language <language> ...] [--format <format>] [--style <style>] [--appearance <appearance>] [--attribute <attribute> ...] [--paper-size <paper-size>] [--paper-margins <paper-margins>] [--text-format <text-format>] <output-folder> [<output-filename>]
ARGUMENTS:
<output-folder> Path to the folder to which the specified document should be exported.
A path containing spaces should be enclosed in quotes.
<output-filename> An optional filename for the main export file.
If it does not contain an extension, a default file extension matching the format is
used.
OPTIONS:
-p, --project <project> Path to an adoc Studio project file
-d, --document <document>
A document to be exported by name, relative path or ID.
A name containing spaces should be enclosed in quotes.
-l, --language <language>
The project language to be exported, given as a BCP 47 identifier
(like en, en-US, de-DE etc.). Needs to be one of the project
languages. If none is specified, all project languages are exported.
-f, --format <format> The export format. (values: html, pdf, text; default: html)
-s, --style <style> The style for formatting the exported document by name or ID.
If none is specified, the default style is used. A name containing
spaces should be enclosed in quotes.
-A, --appearance <appearance>
The appearance of the exported document.
(values: automatic, light, dark; default: light)
-a, --attribute <attribute>
A document attribute to set in the form of name, name!,
or name=value pair. Values containing spaces should be enclosed in quotes.
The attribute takes precedence over the same attribute defined in a document
unless the name ends in @ (i.e., name@=value). name!
unassigns the same attributed defined in a document.
-P, --paper-size <paper-size>
Only for pdf. CSS page size like: a4, letter, a4 portrait,
10cm 20cm (width x height), 10in 20in. If not specified, the default paper
size defined in the chosen style is used.
-M, --paper-margins <paper-margins>
Only for pdf. CSS margin string like: 1cm 2cm 3cm 4cm.
When one value is specified, it applies the same margin to all four sides.
When two values are specified, the first margin applies to the top and bottom,
the second to the left and right. When four values are
specified, the margins apply to the top, right, bottom,
and left in that order (clockwise). If not specified, the default margins
defined in the chosen style are used.
-F, --text-format <text-format>
Only for text. Determines the format of the exported text:
rich, plain (values: plain, rich; default: rich)
-h, --help Show help information.
Die Ausgabe einer Datei könnte am Beispiel des Handbuch-Projekts sein:
adocstudio export documents --project Handbuch.adocproject --document colophon.adoc --format PDF --style Optima ~/Desktop/
Produkte exportieren
Die Ausgabe für ein Produkt via adocstudio help export products ist dagegen übersichtlicher:
OVERVIEW: Export products from an adoc Studio project using their pre-defined configuration.
USAGE: adocstudio export products --project <project> [--product <product> ...] <output-folder>
ARGUMENTS:
<output-folder> Path to the folder to which the specified products
should be exported.
OPTIONS:
-p, --project <project> Path to an adoc Studio project file
-P, --product <product> Specify one or more products by name or ID.
If no products are specified, all products will be exported.
-h, --help Show help information.
Die Ausgabe eines Produkts könnte am Beispiel des Handbuch sein:
adocstudio export products --project Handbuch.adocproject --product ‘PDF für Mac‘ ~/Desktop/
| Enthält der Produkt- oder Projektname keine Umlaute oder Leerzeichen, können Sie die einfachen Anführungszeichen weg lassen. |
4.7. Apple Kurzbefehle
Im Gegensatz zum Terminal-Werkzeug, müssen Sie die Unterstützung der Kurzbefehle.app nicht zuvor installieren. Sobald die v3 oder eine neuere Version installiert ist, können Sie direkt durchstarten, wenn adoc Studio auf Ihrem Gerät ist.
Sie fügen adoc Studio in einen Kurzbefehl ein, indem Sie in der Aktionsauswahl nach adoc suchen. Als Ergebnis werden zwei Kommandos angezeigt:
-
Dokumente exportieren
-
Produkte exportieren
Beide bieten eine Reihe von Optionen an, die Sie innerhalb eines Kurzbefehls automatisch oder im Editor direkt eingeben.
| Weitere Details zu Kurzbefehlen und deren Bedienung finden Sie auf der Apple Webseite. |