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.

What is "Draft Outloud"

Draft Outloud is a web application written on the Ruby-on-rails framework. 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).

The primary criteria that motivated the creation of Draft Outloud instead of the reuse of an existing system:

• Present the book's content in a way that allows for the book being only partially complete and updated frequently.
• Allow people to read the book on the web, or download the current draft of the book in a format conducive to off-line reading.
• Allow readers to indicate what unwritten or incomplete portions of the book they're most interested to see written next.
• Allow readers to ask questions or describe subject matter which they would like to see the final book address.
• Allow readers to give feedback on existing sections: suggest changes, point out type-o's, etc.
• Support a book storage/input format that is also convenient for the production of a print edition of the book.

So why not just use a wiki? In addition to wanting to clearly separate the authorship and readership of the book, and support actually drafting the book's content off-line, wiki's generally aren't linearly structured the way a book is. "Draft Outloud" will format cross-references and such within the book as HTML links, but is generally more book-like than web-like in its presentation.

Book Processing Flow

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. (Note that this is the overall as-intended flow. Not all steps and site features are implemented yet.)

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.

   3. Each section and group of sections of the book are also downloadable as stand-alone HTML files. These are now generated from the whole-book document tree.

6. The book version being served by the site is changed. The generated downloadable files are moved to the directory from which they will be served. The pre-generated HTML for section pages is moved to the cache directory. The "current version" information used to select TOC information from the database is updated to the new target version.