Case study: Customizing the DocBook output

On Thu, Jun 6, 2013 at 12:22 AM, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]> wrote:

One of the authors for Manning, Craig Walls, discovered a new requirement while customizing the Asciidoctor DocBook templates to fit the XML schema that Manning requires.

Asciidoctor renders each block using discrete templates. To fit the Manning schema, the listing and callout list blocks need to be handled by the same template so the output is wrapped by an outer XML element.

Here's how Craig describes the requirement and his solution. (Keep in mind, the "deficiency" isn't a defect in Asciidoctor, but rather a deficiency in the context of their use case).

As I started adding some annotations to my code listings, I uncovered another deficiency in the Asciidoctor templates. It seems that annotations (or callouts as they're known in both Asciidoc and Docbook) were being placed *outside* of the <example> block. Per Manning's schema, they must be *inside* the example block to be valid.

I couldn't figure out a way to make Asciidoctor place the callouts inside of an <example> block. There probably is a way, but I couldn't find it. Rather than being dragged down by this small issue, I created a simple awk script to tweak the generated Docbook file to be valid Manning Docbook. You'll find it in the scripts folder at https://github.com/habuma/asciidoc-manning-templates. You'll also notice that it is now being called from within the a2d.sh script.

I just sent a pull request that shows how this can be done within the template.

https://github.com/habuma/asciidoc-manning-templates/pull/1

This is an interesting use case that I had never thought of before. Each of the block elements are isolated to their own template. In this case, two sibling blocks need to be handled by the same template, and the callout block needs to be skipped where it would normally be rendered.

While my patch demonstrates that this is possible today, I realize that additional locator methods on the node object (Asciidoctor::Block) as well as a flag to mark a block as rendered would make this customization much easier. 

Here's the really great news from the subtext of this case study:

 

Once again, I'm able to generate a valid chapter, starting with Asciidoc and going all the way through to valid Manning Docbook and PDF with no manual tweaks on my part. And the chapter in question is a complete chapter, including code examples (both formal and informal), callouts, images, tables, notes, etc.

Cheers,

-Dan

p.s. I'm planning on creating a set of standalone ERB templates for the docbook output so it's less work to fork and customize (so far I only have ERB templates for the HTML output). If you are willing to use either Haml or Slim, I already have complete sets for those template languages. You can find them here:

https://github.com/asciidoctor/asciidoctor-backends

--

Dan Allen | http://google.com/profiles/dan.j.allen

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Case-study-Customizing-the-DocBook-output-tp297.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML