Markdown 2 Manning

(C) Jason Williams & Alvaro Videla, All Rights Reserved. Distributed under the BSD license.

These tools will allow you to convert Markdown w/ Pandoc Extensions to PDF and Manning Publishing's version of DocBook.

Currently they allow you to:

• Create chapter stubs compatible with the tools.
• Convert single chapters to PDF and/or Manning DocBook (with validation against Manning schema).
• Convert all chapters into individual PDFs and/or Manning DocBook.
• Build a single PDF representing the whole book containing all chapters.
• Publish any chapter directly to Manning's LiveBook site.

Required Software

IMPORTANT: We now use Manning's Agile Author PDF maker (you get Manning ready PDFs as a result)! Please read how to install below.

• Agile Author PDF Maker: We can't distribute this. But you can get it from Manning (or email us and we'll help) if you're an author.
  • To install: Unpack the AA PDF maker archive into AAMakePDF/ in the root directory of this repo.
• Agile Author Validator: We can't distribute this either. But you can get it from Manning (or email us and we'll help) if you're an author.
  • To install: Unpack the AA validator archive into validator/ in the root directory of this repo.
• TexLive or MacTex (I use MacTex) - Required for PDF generation
  • TexLive: http://tug.org/texlive/
  • MacTex: http://www.tug.org/mactex/
• Haskell
  • For most platforms this is the easy way: http://hackage.haskell.org/platform/
• Pandoc 1.8 - Converts Markdown and Pandoc extended Markdown to other formats (PDF/Docbook)
  • Once you've got Haskell installed, run:
    • cabal update
    • cabal install pandoc
    • NB: pandoc will throw some warnings regarding deprecated functions that we plan to fix later
  • http://johnmacfarlane.net/pandoc/index.html
• xmllib2 - Specifically we need the xsltproc, xpath and xmllint programs.
• curl
• GNU make
• GNU awk
• GNU sed

Creating a new book

• Check out this repository.
• Make a new directory for your book somewhere on your computer (e.g. /book/mycoolbook)
• Copy the entire contents of this repository into your book directory.
• Change to your new book directory.
• Run echo X > BOOK_ID where X is your book's number in Manning LiveBook.
• Run echo "XYZ" > LIVEBOOK_URL where XYZ is the full URL to the chapter addition page in LiveBook.
• Edit Makefile :
  • change BOOK_NAME to the name of your book (i.e. RabbitMQ in Action)
  • change BOOK_FILE to the filename (without extension) you want your single book PDF to have
• Edit toc.md and change the title, author and date info to match (multi-authors separated by ";")
• Create your first chapter by running make new_chapter NUM=1
• You should now have a directory in your book called ./chapter-1/ with a file inside called chapter-1.md
• Change directories into ./chapter-1/, and let's make your first PDF and DocBook: run make
• You should now have a chapter-1.pdf and chapter-1.xml

Things to know about markdown2manning

• Chapters must be in directories called "chapter-X" where X is the chapter number.
• Chapter files themselves must be in their "chapter-X" directory and named "chapter-X.md".
• Put chapter images inside the chapter directory for the chapter they belong to (.png, .jpg, and .gif are supported)
• Only use the single # section for chapter title at the beginning of a file (all other sections should use at least ## ):

Example:

# Chapter 1 #

Extended Markdown Syntax

By default, we support the Pandoc extensions to markdown. There are also a few other extensions to markdown we've added specific to authoring Manning books:

• Code Listings: Using the syntax below will create a titled code listing (make sure there are at least 3 tildas). Note that you don't have to put the listing number in the title, it will be automatically created for you when the XML and PDF are generated. The normal markdown syntax for code blocks will create a code snippet instead.

Example: ~~~~~~~~~{title="My cool code example"} import foo

foo.super\_print("Ain't this rockin'?")
~~~~~~~~~

• Callouts: Inside of a code listing, you can use special comment syntax to create a "callout". This will convert the comment when formatted into a number placed next to the section with your comment text as the explanation. It will also allow you to reference the callout number in your explanatory paragraphs below the code listing. The syntax is #/(calloutID) Comment text. calloutID can be any string without spaces you want and must be unique across all of your callouts.

Example: ~~~~~~~~~{title="Anti-Gravity Machine"} import grav_neutralizer

g = grav\_neutralizer() #/(agm.1) Initialize the neutralizer.
g.activate() #/(agm.2) Start repelling gravity.
~~~~~~~~~

Command Reference

• Book Commands (run from the book's root directory)
  • make new_chapter NUM=x - Creates a new chapter stub where x is the chapter number.
  • make all_chapters - Runs "make" inside of all the chapter directories.
  • make book - Creates a single PDF
• Chapter Commands (run from inside an individual chapter directory)
  • make or make all - Create PDF and Manning DocBook versions of the chapter.
  • make pdf - Create PDF version only of the chapter.
  • make docbook - Create Manning DocBook versions of the chapter (validates against Manning schema).
  • make publish - Re-create the Manning DocBook version of the chapter, ZIP it up with the images in the directory and upload it to Manning LiveBook

Using Markdown w/ Pandoc Extensions

The Pandoc extensions to Markdown allow you to create tables, insert cross-references, add footnotes, and sanely insert images. You can also insert inline TeX commands if you're so inclined (\newpage is a very useful TeX command for positioning tables and images). Checkout the Pandoc Markdown syntax reference below:

• Pandoc Markdown Extensions syntax reference
• Standard Markdown syntax reference