43

Writing for Packt with Asciidoctor

In this chapter, you’ll learn:

• How to create a Packt manuscript using asciidoctor (http://asciidoctor.org)

• How to write your text calmly, and let the tools do the layouts for you.

• How to embed images, source code, and create bullets, notes, etc.

• Über easy ways to write your next book (and even use ü’s!)

If you’ll notice, all lines of that bullet list are tagged Bullet [PACKT], except the last. It’s tagged Bullet End [PACKT].

Getting started

After 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.

— Greg L. Turnquist

1. First, grab this project with git clone git@github.com:gregturn/asciidoc-packt.git

2. Second, install http://asciidoctor.org

3. Third, run this book and see what happens!

If you’ll notice, all lines of that numbered list are tagged Numbered Bullet [PACKT], except the last. It’s tagged Numbered Bullet End [PACKT].

To run things, you just need a handy dandy script:

$ asciidoctor -T slim -b packt README.adoc && xmllint -format README.fodt

The output will be compacted XML (FODT), so it will be hard to read. That why running it through xmllint is handy.

Note	You have to ensure xmllint is installed. It’s not part of this project.

You should see a nice output: README.fodt.

$ ls -ltr
total 616
-rw-r--r--@  1 gturnquist  staff   22836 May 30 08:27 packt_template.ott
-rw-r--r--   1 gturnquist  staff  145233 May 30 08:28 packt_template.fodt
drwxr-xr-x   4 gturnquist  staff     136 Jun 18 18:01 slim/
drwxr-xr-x   4 gturnquist  staff     136 Jun 18 20:36 samples/
drwxr-xr-x  11 gturnquist  staff     374 Jun 18 20:36 asciidoc/
-rw-r--r--@  1 gturnquist  staff    6332 Jun 19 08:42 README.adoc
-rw-r--r--   1 gturnquist  staff  131532 Jun 19 08:45 README.fodt

From here, you can start writing your own manuscript for Packt. The core content will be towards the end, inside the <office:body> tag. Everything before hand are Packt’s styles embedded so LibreOffice will make everything look nice.

Does your manuscript live elsewhere, and NOT in the same folder as this project? No problem!

$ asciidoctor -T /path/to/your/clone/of/asciidoc-packt/slim -b packt your.adoc

You should now see a nice output.

Important

In order to open FODT files on Fedora, you must have the libreoffice-xsltfilter package installed.

Cheers!

Warning

I have used this process to successfully publish Learning Spring Boot. I ran into a few hiccups, such as editors reporting they couldn’t see images. I had no problem viewing embedded images, but I had Mac and they had Windows, so who knows? Nonetheless, there are no guarantees provided. If you take this on you assume ALL risk. You have been warned.

Admonitions

Note	This is for notes. They are mapped to Information Box [Packt]

Break…​

Tip	Tips that are side items and break out of the flow of the main text. Mapped to Tip [Packt]

…​things…​

Warning

Warning - Red alert! Put inside a Information Box [Packt] and then wrapped in Italics [Packt]

…​up…​

Caution

Same as warning.

…​or they’ll…​

Important

HIGHLY important. Tip [Packt] with Italics [Packt]

…​run together in a single chunk in LibreOffice.

Quotes

I decided to add quotes. There seemed to a lot of proverbial good ones bubbling up regarding Spring Boot, the topic of this endeavor. So I needed a way to wrap them up properly. It turns out that I preferred the verse over quote, so that’s the styling I have implemented support for.

If Markdown is a 1st-grader, then AsciiDoc is a PhD student.

— Dan Allen

This one simply has the text, wrapped in quotes, followed by a long dash and the speaker’s name.

After 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.

— Greg L. Turnquist
http://blog.greglturnquist.com/2014/05/asciidoc-springboot-packtpub-awesome-tool-chain.html

If you want to cite the source, add the third clause. It will be appended to the end after a ",". NOTE: There is no additional formatting applied, like URL types. Instead, the entire block is marked up with Packt’s QUOTE style. Hence, you might want to debate if this is REALLY needed.

Code

Nothing is complete without looking at code.

link:samples/app.groovy[role=include]

This chunk of code is Groovy (http://groovy.codehaus.org). It contains the @RestController to flag the entire class as being a controller that returns values directly back to the client, without invoking any views.

Every line of a code listing is marked Code [Packt] except the last. It’s marked Code End [Packt].

Console outputs

Create a listing block, but don’t prefix it with a source flag, and this backend will instead mark it up with Command Line[Packt].

$ asciidoctor -T slim -b packt README.adoc
$ xmllint -format README.fodt | tail -10
      <text:p text:style-name="Normal_20_5b_PACKT_5d_">This README page is structured in the theme of Packt. It might not render perfectly on GitHub, but when viewed through a text editor,
and certainly when converted by this backend to LibreOffice, it should provide a nice example of writing a manuscript for Packt.</text:p>
      <text:p text:style-name="Normal_20_5b_PACKT_5d_">Be advised, the nature of this doc is Packt-like, but don’t assume it represents the proper formatting of a book. This is how to
style things. Formatting governs what sections you’ll have in a chapter. When to use tips, quotes, etc. is strictly editorial and
YOUR responsibility.</text:p>
      <text:p text:style-name="Normal_20_5b_PACKT_5d_">NOTHING is done to make it look good on GitHub, because that is not the target. BUT…why waste a keen opportunity to document both
environments?</text:p>
    </office:text>
  </office:body>
</office:document>

Every line of a code listing is marked Command Line [Packt] except the last. It’s marked Command Line End [Packt].

Screen Text

Text seen on the screen must be wrapped with Screen Text [Packt].

Field	Value
`Group'	learningspringboot
`Artifact'	issue-manager
`Name'	Issue Manager
`Description'	Learning Spring Boot
`Package Name'	learningspringboot
`Styles'	`Thymeleaf'
`Type'	`Maven Project'
`Packaging'	`Jar'
`Java Version'	`1.7'
`Language'	`Java'

This table contains embedded options picked from the screen as well as things typed in.

Subsections

Yes, we handle subsections, but so far, only levels 2-5.

• Level 2 is for the chapter number

• Level 3 is for the chapter title

• Level 4 is for major sections

• Level 5 is for sub-sections

It might be possible to go deeper, but I frankly haven’t needed that yet.

Note	This doesn’t apply to Packt Cookbook formats.

Tables

We sure do cover them. Tables are an integral part of writing any manuscript. Check out the following table.

Stuff	Description
asciidoctor	command line tool to parse your doc
packt	name of the backend to process this
slim	THE simplest templating language designed to output XML. See http://slim-lang.com
key word	threw in a keyword inside a table just for fun

Images

Images are embedded through base64 encoding. They are NOT linked to external files.

The backend also embeds a Layout[Packt] tag afterwards with the basename of the file.

Note	It’s up to YOU to properly name the images according to Packt guidelines.

What are some of the things you don’t cover?

Well, there are actually a lot of other styles provided by Packt not handled here.

• Code-within-Tips

• Tips-within-Tips

• Bullets-within-Tips-within-Tips

• The entire appendix section of Packt’s style guide.

• etc.

That is too much, and frankly, I don’t much care for that stuff. Too detailed and really pulls me away from writing, so I don’t support it.

Warning

All styles embedded in this backend are owned by Packt Publishing Ltd. (http://packtpub.com) and potentially subject to their copyright notices.

Good to know stuff…​

• Don’t embed :author: or :title: attributes at the top. They end up getting printed which fouls up the product you must ship to Packt.

• Because asciidoc considers double-underscores indicators of emphasis, all styles names are edited to replace __ with _ to avoid clashing

In case you didn’t notice

This README page is structured in the theme of Packt. It might not render perfectly on GitHub, but when viewed through a text editor, and certainly when converted by this backend to LibreOffice, it should provide a nice example of writing a manuscript for Packt.

Be advised, the nature of this doc is Packt-like, but don’t assume it represents the proper formatting of a book. This is how to style things. Formatting governs what sections you’ll have in a chapter. When to use tips, quotes, etc. is strictly editorial and YOUR responsibility.

NOTHING is done to make it look good on GitHub, because that is not the target. BUT…​why waste a keen opportunity to document both environments?