Home

Welcome to the Draft Outloud wiki!

The content here is intended for developers and people deploying a web site based on Draft Outloud. There is nothing in this wiki about any individual book served from a web site using Draft Outloud.

Book Processing Flow

Draft Outloud servers the content of a book, to allow for public feedback. The original source of the book is expected to be in a source-control system accessible over the web (currently only git, such as GitHub) and stored in a standardized format (currently only DocBook XML, with a handful of conventions about file placement that Draft Outloud expects).

A site using Draft Outloud is configured to serve a particular book through values in its local database (the book's git URL and root file name) and by placing the correct SSH credentials for accessing the book's repository onto the Draft Outloud server.

While individual pages served by Draft Outloud are processed individually, much of the work of preparing the book to be served is performed in a batch when Draft Outloud is instructed to update to a new version of the book from the repository. The sequence of this processing is described here:

1. Updating the site to a new version of the book's content is triggered by an access to a special administrative URL with a parameter that is an acceptable parameter to "get checkout" (a commit SHA or tag, for example). This launches a background job within Draft Outloud. The background job writes to a static HTML file stored in 'public' to indicate its latest status. The file is written (always including the target checkout and a time stamp) at the end of each major step, and in the event of any error that halts processing.

2. The first step is to check out the version of the book matching the parameter given. If the local repository isn't already set up, it is cloned locally, and then the specified revision checked out.

3. Draft Outloud provides a download link for a monolithic PDF version of the book. At this point, the XML tool chain to generate PDF from the DocBook source is run. If errors occur, they are written to the status file and processing ends. The PDF version of the book is not made available for download yet, but held in the local working directory.

4. Draft Outloud also builds a monolithic, downloadable HTML version of the book. This HTML is served when someone clicks the "download" link on the home page and used as an intermediate data form for subsequent processing steps. At this point, the XML tool chain to generate the HTML version of the book is executed. If errors occur, they are written to the status file and processing ends. The HTML version of the book is not made available for download yet, but held in the local working directory.

5. The generated HTML version of the book is read into Ruby and parsed into a document tree. The following processes are then run on the tree:

   1. It is scanned for all HTML elements that represent entries in the outline of the book (chapter headers, section/subsection headers, etc.). Database records reflecting the book's outline are updated, including "what changed between versions" info. The central content (not header or footer) of the site's TOC (home page) is generated and cached.

   2. The content for each "section" of the book is extracted from the whole-book document tree, and new HTML is generated (including the markup necessary for the site's interactive features) for the body of each section page that Draft Outloud will server for the current version of the book.

6. bar