Clarify topic type in ASCIIDoc

[tomschr]

Problem description

During PR SUSE/doc-modular#4, Stefan brought up the topic about how to define the topic type (tasks, concept, reference) in ASCIIDoc.

The basic functionality in asciidoctor doesn't provide any special attributes etc. to insert into the document which is then passed to the DocBook output.

Expected behavior

There is a role attribute (or any other attribute we need) available in the DocBook's root element.

Proposed solution

After looking around for a possible solution, I found slim templates. It's a language similar to Jinja templates, but for Ruby. We could provide these templates with the daps package and use them when converting it to DocBook.

To use slim templates during your conversion, do the following:

1. Install some dependencies for asciidoctor (replace the placeholder <VERSION> to your Ruby version in major.minor format):

   $ sudo zypper install ruby<VERSION>-rubygem-tilt ruby<VERSION>-rubygem-slim
   

2. Create the directory structure asciidoctor-templates/docbook5/.

3. Inside this structure, add the file document.xml.slim with the following content:

   doctype xml
   
   article<>(version="5.2"
     id=@id
     role=(attr :topic)
     xmlns="http://docbook.org/ns/docbook"
     xmlns:xi="http://www.w3.org/2001/XInclude"
     xmlns:xlink="http://www.w3.org/1999/xlink"
   )
     title=title
     =>content
   

   Probably this could be done nicer, but I'm not familiar with slim. For more information, see http://slim-lang.com.

4. Add you favorite topic type into the header as such:

   = Document Title
   :topic: concept
   Tux Penguin <[email protected]>
   

5. Transform the ADoc file into DocBook5 with:

   $ asciidoctor -v -b docbook -d article -T asciidoctor-templates/ main.adoc
   

The result looks like this (formatted to improve readability):

<?xml version="1.0" encoding="utf-8"?>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.2" role="concept">
 <title>Document Title</title>
</article>

You can customize even more ways how specific elements has to be transformed. It just needs a specific naming convention to get it activated.

The only way is to provide a template structure and pass it to asciidoctor.

Taken from https://github.com/SUSE/doc-modular/pull/4#issuecomment-899561029