search

gregturn / asciidoctor-packt

Backend and theme to convert Asciidoctor files into Packt Publishing OpenOffice doc
http://greglturnquist.com/category/learning-spring-boot
46 stars 13 forks source link

readme

== 43 === Writing for Packt with Asciidoctor

In this chapter, you'll learn:

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

[verse, Greg L. Turnquist] 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.

. First, grab this project with git clone git@github.com:gregturn/asciidoc-packt.git . Second, install http://asciidoctor.org . 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 http://greglturnquist.com/learning-spring-boot[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.

[verse, Dan Allen] If Markdown is a 1st-grader, then AsciiDoc is a PhD student.

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

[verse, Greg L. Turnquist, http://blog.greglturnquist.com/2014/05/asciidoc-springboot-packtpub-awesome-tool-chain.html] 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.

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.

[source,java]

include::samples/app.groovy[]

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

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? ---- 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]**. [options="header"] |==== | 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' |==== {empty} 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. [options="header"] |==== | 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 |==== {empty} ==== Images Images are embedded through base64 encoding. They are NOT linked to external files. image::samples/cat.jpg[width="65%" height="30%"] 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?