Category Archives: asciidoc

Goodbye #AsciiDoc, hello @Asciidoctor. Tnx @mojavelinux!

asciidoc_numbered_listI just got my last few tweaks into my Asciidoctor Packt backend. It was enough to drop the venerable AsciiDoc and replace it with Asciidoctor.

Most notably, I fixed the images so they would be centered, and text would not wrap around. I also centered the [[Layout]] note that always is placed below. It looks perfect!

I can say this: working with an asciidoctor backend is gobs simpler than that asciidoc backend. It was brittle, hard to decode, and most of the time I was editing a monolithic file. With asciidoctor backends, each logical fragment is split off into a separate file.

In each file, I was using slim, a very terse way of writing templates. Given that the output is FODT, i.e. XML, slim is pretty neat. You get to express XML structures without the overload of reading angled brackets or having to write the closing tag.

But none of this would have been possible without Dan Allen’s direct involvement. I tried to get started on my own, but it was a no-go until Dan stepped in and submitted a pull request with an initial cut of a backend along with some critical steps to use it. To top it off, we were able to work back and forth, either through more pull requests, or through a discussion thread, to resolve other critical issues. At the end of the day, Dan is one rock solid community builder.

This already opens the door to using options unavailable before hand. The biggest one is how I want to extract fragments of source files into my manuscript. There is still a pending pull request to slightly alter the section format of the manuscripts, but this is structural and doesn’t interfere with my writing.


Chapter 2 shows #SpringBoot + #java + #spring #mobile + #jquery. Fun!!!

learning_spring_boot_ch2I just shipped off chapter 1, “Quick Start with Groovy”. Last night, I dug through and updated the code samples along with outputs to Spring Boot 1.1.1.RELEASE, which went out late yesterday. It really is awesome having that effort minimized thanks to AsciiDoc! Basically, I edited the code directly, re-ran the bits where I had captured console outputs so I could recapture them, and made other suitable updates.

Now it’s time to dig in deeper on chapter 2, “Quick Start with Java”. The neat thing with Spring Boot is that what would be usually trimmed down to toy apps due to space constraints can really show off some slick stuff.

ch2_fodtIn this chapter, I am writing an app that will scan multiple GitHub repositories for open issues and print them out on a web page. It shows the name of the repository, a hyperlink to the issue, and the title. I could put more, but I think this gets the point across.

From there, I will ramp up things wicked cool by adding mobile support. I’ll plug in super simple automatic view switching between desktop and mobile views thanks to Spring Mobile. And I will add a mobile view with jQuery Mobile. Given the rise of mobile-based apps, I think this will be VERY appealing to my readers.

And once again, thanks to AsciiDoc, I don’t waste time on typesetting code. Instead, I WRITE the code, and add explanations and details, a lot like writing reference docs. Yum!!!

Post processing AsciiDoc outputs with a #SpringBoot script

platform-spring-bootI’ve made great strides getting things to look nice with my AsciiDoc-to-LibreOffice outputs. But I ran into issues that I couldn’t solve with asciidoc-packt.

  • Text wrapped in **double asterisks** wouldn’t appear with the Key Word [PACKT] styling applied.
  • Bullet point lists have a special style for the last entry, probably to grant additional spaces afterwards before the Normal block begins.

As my colleagues are well aware, when I can’t beat something, I write a script! So I decided to see if I could a bit of code to post-process the FODT XML file generated by AsciiDoc.

This time, I didn’t reach for Python to solve it. Instead, I reached for Spring Boot CLI + Groovy. Something I’ve been coming to realize is that Groovy is a powerful scripting language. But not only that, it provides easy access to the Java ecosystem through @Grab annotations. Spring Boot CLI dials things up a notch by making it super easy to write a command line runner and even tack on a web page later on via Spring MVC.

So I embarked on doing some XML parsing and editing. Naturally I reached for Jsoup. Jsoup by default is made for parsing HTML, but it also has an XML parser. With it, it’s easy to search for tokens because it has a jQuery-like selector API. I was able to look for patterns of behavior, like a bullet point list, and then find the last row’s entry. Then it simply a matter of adjusting one attribute to adjust the style. Write the updated DOM document back out to disk, and POOF! I had proper formatting for all my bullet point lists.

I was able to get **key word** formatting to work by looking for strong styling in specific situations, like inside Normal, Bullet, and Tip paragraphs (but NOT Code listings).

I tried to hammer out code blocks, but was unsuccessful. Packt’s style sheet shows each line of a code listing being wrapped like a separate paragraph with Code [PACKT]. Then the last line can be styled as Code End [PACKT]. But my solution with asciidoc-packt was the wrap the whole listing as a single paragraph. It’s buried with <text:line-break /> tags. I tried splitting it up and rejoing it, but I could never replace that DOM element with a new one.

Since I needed to not spend my entire writing schedule on tools, I put that feature down and decided I will either duck the whole thing, or put in that particular styling edit manually. After all, I’m already getting major efficiency improvements by having AsciiDoc do most of the leg work for me. So it’s probably best if I not get too wrapped up working on this post processing script, and instead focus the right amount of time every night on my manuscript.

I’ve already roughed out chapter one. I am now going through each section and making sure it flows nicely. I’m moving chunks around, and ensuring everything is clearly and cleanly explained. I don’t want any reader to suffer jolts with things appearing to jump too hastily.

The whole idea isn’t to dump a bunch of code in the reader’s lap, but instead tell an enjoyable story that just happens to be about the most innovative way to build rock solid apps on the battle tested Spring + Apache Tomcat + JVM stack.

#AsciiDoc + #SpringBoot => @PacktPub. Awesome tool chain!

learning_spring_boot_ch1_adocAfter writing gobs of documents over the past year with AsciiDoc, I was strongly motivated to make that work as I embark on writing Learning Spring Boot.

Writing a book with a word processor is one thing if you’re talking about a trade novel. That format is nothing but words, words, and more words. But for a technical book, we have a different medium. There are words, code listings, inline code fragments, console outputs, screen shots and more. This is more like a reference manual or blog posting that is targeted for print.  And that is something AsciiDoc was made for.

learning_spring_boot_ch1_odtI googled around and found a nifty backend that let you output from AsciiDoc straight into ODT. The gulf I needed to bridge was incorporating Packt’s styles. Packt has a template document that has all their styles. Thankfully they support OpenOffice. I was able to open their stylesheet and save it a Flat ODT (i.e. flat XML document). Then I wrote a Spring Boot CLI script to extract all of their styles (but not the sample text) and dump them into an AsiiiDoc format file. With some tweaks to packt.conf, I managed to crank out a nicely formatted OpenOffice doc from my raw manuscript!

Click on the images on this blog post, and you can see the original AsciiDoc as well the auto-generated LibreOffice document. (Note how the ODT document is in the middle of a bullet point listing, and the type in the top left corner reads Bullet [PACKT].)

If you’re interested, you can experiment with it as well! Just visit If you have tips on how to improve this, feel free to submit pull requests.

NOTE: This is at the bottom of my list of things to manage, so unless your patch is super simple or solves an immediate problem I’m having, don’t assume instant response.