fork of gregturn's asciidoctor-packt
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
samples
slim/packt
.gitignore
README.adoc
The PACKT Template.dotx
doc
packt_template 2.fodt
packt_template 2.ott
packt_template.fodt
packt_template.ott

README.adoc

43

Writing for Packt with Asciidoctor

Infos about this fork

Updated by @makevoid for generation from markdown, will follow informations to script the whole process.

This is the script I’m using

#!/usr/bin/env bash

page=${1:-chapter_02} # I update this default var as my current chapter


pandoc -t asciidoc -f markdown $page.md > $page.asciidoc &&

ruby bin/replace_images.rb $page &&

asciidoctor --trace -T ~/apps/asciidoctor-packt/slim -b packt $page.asciidoc &&

sed  -i.bak s/encoding=\"\"/encoding=\"utf-8\"/g $page.fodt &&

xmllint -format $page.fodt &&

if [[ "$OSTYPE" == "linux-gnu" ]]; then
  libreoffice $page.fodt
else
  open $page.fodt
fi

You will need pandoc, asciidoctor, libreoffice and xmllint installed.

This is the other script I’m using for handling the images, it’s useful but completely optional:

# configs
DEFAULT_ARGS = "width='100%' height='30%'"

page = ARGV[0]
@page = page
raise "no page... exiting..." unless page

page_file = File.read "#{page}.asciidoc"
page_file = page_file.split "\n"

pages = File.read "#{page}.imgz"
pages = eval pages#.split "\n"


def replace(line, pages: pages)
  match = line.match /image:(.+)\[/
  path = match[1]
  found = match[1].sub "./#{@page}/", ''
  args = DEFAULT_ARGS
  argz = pages[found.to_sym]
  args = argz if argz
  "image::#{path}[#{args}]"
end

page_file = page_file.map do |line|
  if line.match /^image:/
    replace line, pages: pages
  else
    line
  end
end

File.open("#{page}.asciidoc", "w") do |f|
  f.write page_file.join "\n"
end

And this is a sample .imgz file used by the ruby build script:

{
  "blockchain_diagram_01.png": "width='80%' height='25%'",
  "number_of_transactions_per_day.png": nil,
  "estimated_usd_transaction_volume.png": nil,
  "osx_01_install_devtools.png": nil,
  "blockchain_01.png": "width='100%' height='42%'",
}
---


Contact me for more infos and many thanks to Greg, who wrote this awesome repo and to Andrey Adamovich for telling me about the existence of it!

Enjoy!


=== Original Readme

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

[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://blog.greglturnquist.com/category/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]
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]**.

[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?