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

| Agree


A New Manual In AsciiDoc

Part 1

Cover page of the Merlin Project manual

We are constantly optimizing Merlin Project for easier use. We already started some time ago with the start dialog and cleaning up the inspector.

With version 8, the dynamic help has now been introduced: Just click on the ? symbol and you will get an explanatory help text for every object you point to with the mouse (or with your finger on the iPad). You can even create your own help texts for your own fields.

Unfortunately our manual is a bit behind. But don't worry, there is rich and up-to-date documentation, like:

A complete manual does not exist at the moment. And that's exactly what I want to change now.

The Project

I have recently started to rewrite the manual and create this very reference. Of course I have set up a project for it, but unfortunately it has to share the available time with all my other projects.

The Goal

Besides the obvious goal of creating an up-to-date documentation of the features in Merlin Project in the major languages, I set myself a few more sub-goals or sub-objectives:

However, the target date is completely open with all planning as I have a different workload from week to week. Thus, it would be completely unrealistic setting a target date.

The Tools

At ProjectWizards, we write all text in ascii format and check it into our git no later than the end of the day.

Quite contrary to the current fashion, we do not write in Markdown or any of its derivatives or supplements. We already focused on AsciiDoc a very long time ago and since a few years on the new Asciidoctor, the new implementation of Dan Allen (via Twitter). The reasons for this decision are mainly:

  • Variables,
  • Linking other files,
  • conditional texts and formatting,
  • tables, charts and many other contents,
  • text output in many different formats,
  • automatic tables of contents, as well as glossaries, indexes and bibliographies
  • and much more ...

And before I forget, of course BBEdit is still set as editor #1 with me.

AsciiDoc vs Asciidoctor

In short, you give the AsciiDoc source to Asciidoctor and get a result that you can publish. So:

  • AsciiDoc is the language
  • Asciidoctor is the processor

Like Markdown, AsciiDoc was designed as a language to be unobtrusive and concise, and to make writing easier, even more enjoyable. But AsciiDoc itself is not a publishing format. It's more like a shorthand. This is where an AsciiDoc processor comes in.

An AsciiDoc processor, such as Asciidoctor, reads the AsciiDoc source text and converts it into publishable formats such as HTML 5, eBook or PDF. Of course, the whole thing is complemented with design tools, such as Cascading Style Sheets (CSS).

Working out Loud (WOL)

In the spirit of Working out Loud I will try to report regularly about this work. I will put less emphasis on how many words or sentences I was able to write during the week. It's much more about presenting help and new knowledge about Asciidoc and Asciidoctor.

With this approach, of course, I also honor the tireless work of Dan Allen and support him. At least as much this is a vote for Asciidoc in project management.

We'll start next Friday at this slot.

Continuation - A new manual in AsciiDoc, part 2

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

Merlin Project on the Mac and iPad

Your ideas, our magic – make projects easy! Test now 30 days for free.