Just added support for #AsciiDoc ~> @PacktPub numbered lists

By Greg Turnquist

Greg L. Turnquist worked on the Spring team for over thirteen years and is a senior staff technical content engineer at Cockroach Labs. He was the lead for Spring Data JPA and Spring Web Services. He wrote Packt's best-selling title, Learning Spring Boot 2.0 2nd Edition, and its 3rd Edition follow-up along many others.

June 17, 2014

asciidoc_numbered_listIt feels like I have almost reached feature completion with my Packt Publishing backend. It does just about anything I need. In fact, I don’t really think about editing my generating ODT files. (The only thing is potentially moving the [[layout notes]] that don’t properly wrap).

Sure there are lots of other styles, like bullet-within-tips, and code-following-bullets, but I don’t really use those. In fact, it’s probably a good thing to avoid those highly specialized spacings. I have paragraph formatting, section headers, URLs, code blocks, bullet lists, tables, and now numbered lists.

As usual, it took a bit of digging to figure out EXACTLY how this works in ODT’s cryptic XML. Sometimes, I have to manually edit the ODT file and inspect it afterwards to see what changed. But thanks to a bunch of digging using vi, TextMate, and other things, I deduced what the missing style bits I needed to add to packt.conf.

libreoffice_numbered_bulletSuffice it to say, I now have it tagging numbered lists, which are important for a sequence of steps. In this chapter, we create a tiny app that lets you look up issues across multiple GitHub repositories, and display them in both a desktop web page as well as a mobile web page. The sequence of steps to get a personal access token didn’t really fit a bullet list, but instead needed to be written up in order.

When I write such detailed step-by-step instructions, it just isn’t suitable in a paragraph or a table. By putting this in a numbered list, the reader can quickly spot the chain of steps, and if he or she is already familiar with the concept, easily skim past it to the next juicy bit of code.

A key tactic in writing is to break up all the material into easily consumable chunks. Several sub-sections, along with a few paragraphs between code blocks is a start. Calling out key parts of a code listing with either bullets or a table provides a nice, easy-to-view way to understand things. And if you already know what the code block says, your eyes will easily move past such a listing onto the next paragraph.

Happy reading!


Submit a Comment

Your email address will not be published. Required fields are marked *