Mit der Nutzung unserer Website erklären Sie sich damit einverstanden, dass wir Cookies verwenden. Mehr Informationen

| Zustimmen

Blog

Ein neues Handbuch in AsciiDoc

Teil 4

Deckblatt des Merlin Project Handbuchs

In dieser Woche hat es endlich wieder funktioniert. Mein Plan mit den geblockten Zeitphasen im Kalender ist aufgegangen. Ich konnte am Mittwoch fast durchgehend schreiben.

Dabei sind mir ein paar Kleinigkeiten in AsciiDoc aufgefallen, die ich mit Ihnen teilen möchte.

Lokalisierte Sektionen

Leider werden bestimmte Sektionen wie z. B. Inhaltsverzeichnis, Bildverzeichnis, Glossar, Bibliographie etc. nicht übersetzt. Der erste Schritt ist die Definition der Sprache:

:lang: de

Das reicht aber leider noch nicht aus. Es muss eine bestimmte Datei aus dem Lieferumfang von Asciidoctor (hier auf Github) mit eingebunden werden:

// Include your own path for the attributes:
include::../locale/attributes.adoc[]

Erst dann erscheinen alle Standardsektionsnamen in der gewünschten Sprache.

Wiederholungen des Programmnamens

Sicher, grundsätzlich sind Wiederholungen nicht gut. Aber in einem Handbuch ist es unvermeidlich, dass der Produktname des öfteren wiederholt wird. So habe ich mir sehr schnell eine Variable gebastelt:

:mp: Merlin Project

So verwende ich die Variable:

Willkommen bei {mp}!

Ergebnis:

Willkommen bei Merlin Project!

Und noch ein Bonus: Ich setze zwischen Merlin und Project ein geschütztes Leerzeichen (in BBEdit ist das die Tastenkombination ⌥ + Leertaste). Dann wird der Programmname im Umbruch nie auseinander gerissen.

Menünamen und Tastaturabkürzungen

In der Natur eines Handbuchs für Software liegt die Beschreibung der Oberfläche und deren Bedienung. Hier kann man natürlich eigene Standards setzen und die Elemente in kursiver oder fetter Schrift setzen. Es gibt aber in AsciiDoc eine tolle Alternative. Dazu muss allerdings zuerst die Verwendung mit einem speziellen Schalter aktiviert werden.

:experimental:

Übrigens, welbst wenn der Schalter experimental heißt, ist die Funktion bereits voll etabliert. Hier ein Kommentar von Dan Allen dazu.

Nun werden Menüeinträge mit einer speziellen Notation geschrieben:

Ein Klick auf menu:Hilfe[Dynamische Hilfe] startet die Balloon-Hilfe.

Ergebnis:

Ein Klick auf Hilfe->Dynamische Hilfe startet die Balloon-Hilfe.

Natürlich kann die Formatierung der Menüeinträge in den Stilen angepasst werden.

Ähnlich funktioniert es mit Shortcuts, den Tastaturabkürzungen. Hier ist die Notation:

kbd:[⌘ + N]

Ergebnis:

⌘ + N.

Noch einfacher geht es, wenn man die HTML-Entities in Variablen steckt. Ich habe auf StackExchange die wichtigsten HTML-Entities für Apple Computer gefunden:

:commandkey: ⌘
:optionkey: ⌥
:controlkey: ⌃
:shiftkey: ⇧
:enterkey: ⌤
:enterkey: ⌤
:returnkey: ⏎
:deletekey: ⌫
:rightkey: →
:leftkey: ←
:upkey: ↑
:downkey: ↓

Jetzt lautet Ihre Eingabe nur noch:

Drücken Sie kbd:[{commandkey} + Q] um ins Wochenende zu starten.

Ergebnis:

Drücken Sie ⌘ + Q um ins Wochenende zu starten.

In diesem Sinne – bis zur nächsten Woche …

Fortsetzung - Ein neues Handbuch in AsciiDoc, Teil 5

Geschrieben von Frank Blome am 05.11.2021 unter Interna
Tags: asciidoc asciidoctor handbuch-projekt wol

Merlin Project auf dem Mac und dem iPad

Ihre Ideen, unsere Magie – Projekte einfach verwirklichen!
Jetzt 30 Tage kostenlos testen.