Find file
Fetching contributors…
Cannot retrieve contributors at this time
69 lines (43 sloc) 3.59 KB

Publishing using the ORM workflow

O’Reilly’s "official" publishing workflow is done is developed in DocBook and managed in Subversion (SVN), another content management system. Your editor will provide you with a SVN repository for your content once you get a contract. To "publish" your work through O’Reilly you’ll need to get your content into this system.

It’s not so bad, actually. The basic workflow is:

  • Checkout your subversion repo

  • Move your content into the SVN repo

  • Commit your files with a special trigger in the commit message

  • Update the repo to download the new PDF and log files

  • Review changes and fix them in your working directory

The repo is set up to use a two-stage SVN commit hook, which first tries to convert asciidoc to DocBook (using ORM-customized config files) and then builds a PDF from that (assuming it’s succeeded ingenerating valid DocBook) in standard Animal style. Once you’re ready, you can also push the content out into our various e-channels.

The following sections cover these steps in detail.

Checkout your subversion repo

You’ll get an official SVN repository when you sign the contract. Your editor will help you with the gory details like getting a password, and so forth.

Checking out the files looks something like this:

svn checkout --username "odewahn@oreilly.com" "https://prod.oreilly.com/internal/books/sandbox_odewahn_RT79726/current/"

Move your content into the SVN repo

Caution
Using "git svn"

You might reasonably ask, "Hey, why do I have to copy this stuff? Can’t I just use git svn" by doing something like this (see Chapter 8 from Pro Git):

git svn clone --username "odewahn@oreilly.com" "https://prod.oreilly.com/internal/books/sandbox_odewahn_RT79726/current/" -T trunk -b branches -t tags

Good idea, but I don’t think this is going to work for us using our standard workflow. The main sticking point seems to be that git wants to make a complete history of all the changes that have happened on the repository, so it goes through several hundred thousand (literally!) different revisions. This takes a long time to complete — it has to go through almost 300K revisions. Also, it seems from reading around that SVN can have touble keeping up with the more complex histories of git projects.

But, I wonder if there is a way to speed it up? Maybe we could create a separate repository for just these projects?

Add the files to the SVN repo

Commit your files with a special trigger in the commit message

You can generate a PDF of your book by including the string "orm:asciidoc" in the commit message when you commit the repository. For example:

$ svn commit -m'Made some really important changes to Chapter 3; orm:asciidoc'

This will kick off the process to convert the asciidoc files into DocBook.

Update the repo to download the new PDF and log files

To retrieve the results, run the command "svn up" (update) copy about 5–10 minutes after committing your files. If all goes well, the process will generate the following files:

  • pdf/book.dcpsgen.xml.pdf (the PDF, assuming the process succeeded)

  • book.dcpsgen.xml (generated DocBook)

  • .dcps.a2xlog (log from asciidoc→DocBook conversion)

  • pdf/.dcpsgen.buildlog (log from PDF build of generated DocBook)

Review changes and fix them in your working directory

If you don’t see a fresh PDF when you 'svn up' after a few minutes, take a look at the logfiles above for errors. Be sure to fix any problems in your working git repository, not the temporary SVN repository. Then, give it another shot.