Category Archives: spring boot

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.

Cheers!

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

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!

#SpringBoot gives you the kinds of problems you want

ch2_fodtAt my old company, I had a manager that was happy to point out when we had “good” problems. He was often citing situations where we had too much work from the customer such that our current staffing levels couldn’t keep up. Instead of anyone being let go, we sought out new talent to tackle this.

Well Spring Boot recently started causing me some problems that I discovered were good to have. As I was roughing out chapter two of Learning Spring Boot, “Quick Start with Java”, I noticed that my page count was coming in around in the mid-twenties. The estimate I had submitted was forty pages. What?!?!

I have an app that connects to GitHub and scans for open issues across two repositories. It plugs in using Spring Mobile to automatically detect the user agent of the browser and switch which view template is rendered. The mobile template uses jQuery Mobile to provide a nice mobile experience.

Well I already chewed out Roy for cutting out the code to set up the view resolver. The nerve of that man to reduce half a page of code to a single property setting! Heh.

What am I supposed to do? Usually, when you write code for books, you have to trim stuff down to toy applications because there isn’t enough space. But I’m discovering that with same amount of space, I’m able to write production grade apps. I had an idea of where to fill in some more details, but after reading the outline again last night, I might have to re-evaluate. I have a slew of stuff in the next chapter that I don’t want to just pull into this one.

The irony? My original proposal to Packt called for ten chapters, but to speed up time-to-market, was cut back to five. I may yet fit in ten chapters worth of material in the allotted space.

All-in-all, Spring Boot’s ability to trim code down to a fraction to get the same things done is a good problem to have!

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!!!

Recently wrapped up Chapter 1 – “Quick Start with Groovy”

Late last week, I wrapped up chapter one, “Quick Start with Groovy”. Whenever I present Spring Boot for the first time to a group, I lead with what Rob Winch snappily tweeted last August:

This kind of sums up the power of Spring Boot. Just a few annotations provide enough clues for a bit of software to configure Spring MVC, Jackson2, and embedded Tomcat. That and other discussion threads about how far you can get with this Groovy + CLI approach made me want to dive into my book on this front.

In this chapter, I basically take a similar app, and dial things up as far as possible to take it to production. It’s amazing how much functionality can be covered in just seventeen pages. It’s a testament to the expressiveness of Groovy and to Boot’s powerful auto-configuration features.

I want to blow the reader’s mind and make them understand, it’s not just a toy. You have access to the battle tested Spring + Apache Tomcat stack, any industry accepted javascript library you can think of, and a whole gamut of production support tools.

Is the whole book coded using Spring Boot’s CLI tool? No. I figured that the majority of readers out there probably use either java or groovy inside a project+build file. Boot’s CLI makes for powerful microservices, but this book isn’t about microservices.

The first deadline is approaching, and I always, always, ALWAYS like to stay ahead of the curve. In my opinion, the key to avoiding a crushing deadline is to not let it be crushing. I prefer to be a chapter or two ahead and then have time to go back and further polish things up. I’ve already roughed out about 25% of the chapter two. Once that’s done, I can go back and fine tune that chapter.

Cheers!

 

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 https://github.com/gregturn/asciidoc-packt. 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.