A New Manual In AsciiDoc
Part 4
This week it finally worked again. My plan with the blocked time phases in the calendar went off. I was able to write almost continuously on Wednesday.
In the process, I noticed a few little things in AsciiDoc that I want to share with you.
Localized Sections
When you need your documentation in other languages then english, unfortunately, certain sections such as table of contents, table of images, glossary, bibliography, etc. are not translated. The first step is to define the language, for example for Spanish:
:lang: es
However, this is not yet sufficient. A specific file from the Asciidoctor scope of supply (here on Github) must be included:
// Include your own path for the attributes:include::../locale/attributes.adoc[]
Only then will all default section names appear in the desired language.
Repetitions of The Program Name
Sure, in general, repetitions are not good. But in a manual it is inevitable that the product name is repeated often. So I very quickly made up a variable:
:mp: Merlin Project
This is how I use the variable:
Welcome to {mp}!
Result:
Welcome to Merlin Project!
And another bonus: I put a protected space between Merlin and Project (in BBEdit this is the key combination ⌥ + space). Then the program name is never torn apart in the wrap.
Menu names and keyboard shortcuts
In the nature of a manual for software lies the description of the interface and its operation. Here, of course, you can set your own standards and put the elements in italics or bold style. But there is a great alternative in AsciiDoc. For this, however, the use must first be announced with a special switch.
:experimental:
By the way, even if the switch is called experimental, the function is already fully established. Here is a comment by Dan Allen about it.
Now menu items are written with a special notation:
A click on menu:Help[Dynamic Help] starts the balloon help.
Result:
A click on Help->Dynamic Help starts the balloon help.
Of course, the formatting of the menu items can be customized in the styles.
It works similarly with shortcuts, the keyboard shortcuts. Here is the notation:
kbd:[⌘ + N]
Result:
⌘ + N.
It's even easier if you put the HTML entities in variables. I found the most important HTML entities for Apple computers on StackExchange:
:commandkey: ⌘:optionkey: ⌥:controlkey: ⌃:shiftkey: ⇧:enterkey: ⌤:enterkey: ⌤:returnkey: ⏎:deletekey: ⌫:rightkey: →:leftkey: ←:upkey: ↑:downkey: ↓
Now your input is just:
Press kbd:[{commandkey} + Q] to start the weekend.
Result:
Press ⌘ + Q to start the weekend.
In this sense - until next week ...
