heading and contains no other

 blocks use less than about 80 columns, though this is
   commonly broken.

 * Spurious   entities and the like are despised but are left
   unmolested in practice unless they cause obvious problems.

 * All of these guidelines are regularly broken if the printed page
   looks OK.

TOC.txt file 
~~~~~~~~~~~~
In addition to the HTML chapters, the source of a FLOSS Manuals book
contains a file named TOC.txt which orders the chapters and groups
them into sections.

The TOC.txt format is quite simple but fiddly to describe and thus
undocumented.  An example can be seen here:

http://en.flossmanuals.net/pub/Audacity/_index/TOC.txt

and decoding methods can be found in the Objavi2 source.  Much of the
information encoded in the TOC.txt file is useless to Objavi.

The objavi process
==================

Objavi2 starts with the chapters of a book concatenated in order, as
provided by links like this:

http://en.flossmanuals.net/bin/view/Audacity/_all?skin=text

and separately fetches the TOC.txt file described above.  Using lxml
(an xml/html library), it finds and numbers chapter headings,
canonicalises image links, and inserts section headings which group
related chapters together.  This modified HTML is sent to wkhtmltopdf,
a command-line interface to Webkit that renders a PDF.  

At this point the PDF has no page numbers, no gutters, no table of
contents, and is using a too big paper size.  In order to write a
table of contents, the text is re-extracted from the PDF and searched
for invisible tags that were added along with the chapter numbers. (It
is not possible to know what page a chapter will end up on before the
PDF has been laid out).  The table of contents thus generated is
combined with other preliminary pages and another PDF is created.

Pdfedit is used to crop the pages down to size and to shift them
alternately left and right, creating a gutter for the spine of the
book.  Then pdfedit is used again to add page numbers to both PDFs,
with lowercase roman numbers being used for the preliminary pages.

Finally the two PDFs are combined using pdftk and, optionally, spun
180 degrees so they appear upside down.  If a right-to-left book is
printed like this on a left-to-right printer, the binding will be on
the correct side.

Pdfedit and wkhtmltopdf both require an X server to run, for which
Xvfb is used.  

How this differs from Objavi beta
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Because it is integrated into TWiki, Objavi beta doesn't need to fetch
the book or the TOC.txt over the network, and can instead construct
the html using the TWiki library.  Pisa adds page numbers and
generates a table of contents as it goes, and the gutter is set using
its advanced CSS page support.

Future plans
============

There is a TODO in the git repository, but one or two items are worth
expanding.  

It should be easy to add Gecko as an optional layout engine, so people
can choose between the Webkit and Gecko versions.  Some languages
might suit one more than the other, and when one grows new paged media
CSS features, Objavi2 will not be stuck with the wrong choice.

On the other hand, Objavi2 could be tempted into a tighter snuggle
with Webkit, as its front-end wkhtmltopdf is able to generate PDF
outlines and tables of contents as it makes the PDF.  The way it does
these things is currently unusable by Objavi2, but it could be
changed.

Another intriguing but probably stupid possibility would be to embed
Webkit directly in Objavi2 using pyQT.

Installation
============

See the INSTALL file.  Apologies for its inadequacy.