A New Manual In AsciiDoc

Part 2

This is the second part of my project report for the new Merlin Project manual. I will try to give a more or less brief update on the project every Friday.

The Project

Before we jump into AsciiDoc, here's a quick look at my project.

The Git repository has been set up
The lines are defined and some of them are listed here as well.
The prerequisites are known as far as they go.
A first outline has been created and will now be refined gradually.
As pictures I will first use only quick screenshots, and then recreate them as needed.
A weekday for writing is set.

The last point in particular was a real challenge for me, because somehow I have to find the time to write. If I just take every available minute, I'll probably never finish. I need a set block of time, and that's exactly what I've created. As of now, Wednesday is my manual writing day. Let's see how long that works ...

Of course there is a Kanban board. We have chosen English as the language for our internal documentation.

AsciiDoc Hints

Splitting files

I don't build the manual in one file, but prefer to split it chapter by chapter. I also store the variables and attributes of my manual in a separate file, so that I can build the files separately or view them in the browser and use all variables and attributes. This file is usually called Attributes and so I can always find it quickly, it gets a "_" and is always at the beginning of the file list.

ifndef::_attributes[]
include::_attributes.de.adoc[]
endif::[]

Here I query if the variable _attributes is already set.
If not, the file is included.

So I make sure that the attributes file is not loaded several times, because each file starts with these lines.

My Rapid Turnaround

I'm still writing the manual alone at the moment, but all texts and media go into Git. This means that my morning start of writing begins in the terminal, or - depending on what I have at hand - the BBEdit Unix Worksheet, with a spirited git pull. Then I open the BBEdit project file (which is included in the repository, of course) and see all included files in the left list.

I split the screen roughly in half: I'm writing on the left and I have Chrome open on the right. In the browser window I simply drag the proxy icon of the edited file. Thanks to the extension Asciidoctor.js the browser is updated with every save in BBEdit.