By using our website you agree that we use cookies. More information

| Agree

Blog

A New Manual In AsciiDoc

Part 2

Cover page of the Merlin Project manual

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.

The Kanban Board in Merlin Project

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::[]
  1. Here I query if the variable _attributes is already set.
  2. 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.

My setup for writing

That's it for today – more next week.


Continuation - A new manual in AsciiDoc, part 3

Posted by Frank Blome on October 15th, 2021 under Internal
Tags: asciidoc asciidoctor manual-project wol

The Merlin Project Magic on the Mac and iPad

Gantt chart, Kanban and mind map on Mac and iPad. Test now 30 days for free.