README

   1 Objavi2: another FLOSS Manuals publishing system
   2 ================================================
   3
   4 Introduction
   5 ============
   6
   7 FLOSS Manuals books are written and stored as HTML, but are converted
   8 to PDF for printing.  Programs which perform this task are called
   9 objavi (pronounced "ob-YAH-vee", as if the J was a Y), after the
  10 Croatian word "objavi!" meaning "publish!".
  11
  12 the previous objavi, Objavi beta, works very well but is unable to
  13 process bidirectional text and is closely tied to the TWiki software
  14 that FLOSS Manuals intends to abandon.  Objavi2 was written to provide
  15 a fully internationalised objavi that is decoupled from other parts of
  16 the FLOSS Manuals system.  It was not intended to outdo Objavi beta at
  17 the things that Objavi beta does well, though in some regards it has
  18 and that is OK too.
  19
  20 Objavi2 is free software, distributed under the version 2 or greater
  21 of the Gnu General Public License.  The source can be viewed at
  22
  23  http://repo.or.cz/w/objavi2.git
  24
  25 which also contains instructions for cloning the git repository.  If
  26 you want a source tarball without worrying about git, try this link:
  27
  28  http://repo.or.cz/w/objavi2.git?a=snapshot;h=HEAD;sf=tgz
  29
  30 It is primarily written in Python, with a substantial amount of
  31 QSAScript (an ECMAscript variant) and some Javascript, HTML, and CSS.
  32
  33 Which Objavi should I use?
  34 ==========================
  35
  36 Short answer
  37 ~~~~~~~~~~~~
  38 Try both and see which you like, unless the book in question has
  39 right-to-left text, in which case you want Objavi2.
  40
  41 Details
  42 ~~~~~~~
  43 Objavi beta (written in 2008 by Aleksandar Erkalovic) is a TWiki
  44 extension that uses Pisa to make PDFs.  Pisa lets you use CSS rules to
  45 avoid widowed or orphaned text and to adjust margins.  In other
  46 regards, its CSS support is variable.  This means Objavi beta makes
  47 well laid-out books, but people writing style rules need to be aware
  48 of its quirks and use peculiar workarounds to achieve certain effects.
  49 It only works with left-to-right scripts and possibly mis-renders some
  50 of those (due to not understanding combining characters).
  51
  52 Objavi2 uses Webkit to make PDFs.  Webkit is a common web browser
  53 engine, so it interprets CSS in a fairly predictable fashion but also
  54 has almost no concept of paged media.  It does not recognise CSS rules
  55 for setting page sizes or margins and has limited support for
  56 controlling page breaks.  (There are actually ways in which margins
  57 can be customised with Webkit but Objavi2 does not yet expose them).
  58 Webkit has very well tested Unicode support and it handles
  59 bidirectional text.
  60
  61 The page-break CSS properties supported by Webkit are
  62 page-break-before and page-break-after, which is sufficient to have
  63 each chapter start on a new page, but not to avoid breaking up
  64 paragraphs in unfortunate ways.
  65
  66 Objavi2 is somewhat faster than Objavi beta.
  67
  68 Compatibility
  69 ~~~~~~~~~~~~~
  70 The two objavis share no code but have a similar CGI interface, so
  71 sending the same request might result in a PDF being produced
  72 whichever Objavi was installed.  This behaviour is inherited rather
  73 than guaranteed, and might fade away.
  74
  75
  76 The FLOSS Manuals Book Format
  77 =============================
  78
  79 FLOSS Manuals source HTML
  80 ~~~~~~~~~~~~~~~~~~~~~~~~~
  81 The subset of HTML used in FLOSS Manuals books has been pragmatically
  82 determined rather than specified.  The constraints that have shaped it
  83 are that the source must be:
  84
  85  1. easily producible and editable using the Xinha editor and by hand,
  86  2. printable using Objavi beta,
  87  3. organised into chapters, and
  88  4. conformant to the instincts and habits of the authors.
  89
  90 This has led to simplified HTML that has the following properties:
  91
  92  * Each chapter starts with an <h1> heading and contains no other <h1>
  93    elements.
  94
  95  * Each chapter is in a separate file.
  96
  97  * Fixed width elements such as images are generally no bigger than
  98    600 pixels wide.
  99
 100  * Inline style, class and id attributes are avoided.
 101
 102  * Many uncommon or irrelevant tags are avoided.
 103
 104  * <pre> blocks use less than about 80 columns, though this is
 105    commonly broken.
 106
 107  * Spurious &nbsp; entities and the like are despised but are left
 108    unmolested in practice unless they cause obvious problems.
 109
 110  * All of these guidelines are regularly broken if the printed page
 111    looks OK.
 112
 113 TOC.txt file
 114 ~~~~~~~~~~~~
 115 In addition to the HTML chapters, the source of a FLOSS Manuals book
 116 contains a file named TOC.txt which orders the chapters and groups
 117 them into sections.
 118
 119 The TOC.txt format is quite simple but fiddly to describe and thus
 120 undocumented.  An example can be seen here:
 121
 122 http://en.flossmanuals.net/pub/Audacity/_index/TOC.txt
 123
 124 and decoding methods can be found in the Objavi2 source.  Much of the
 125 information encoded in the TOC.txt file is useless to Objavi.
 126
 127
 128 The objavi process
 129 ==================
 130
 131 Objavi2 starts with the chapters of a book concatenated in order, as
 132 provided by links like this:
 133
 134 http://en.flossmanuals.net/bin/view/Audacity/_all?skin=text
 135
 136 and separately fetches the TOC.txt file described above.  Using lxml
 137 (an xml/html library), it finds and numbers chapter headings,
 138 canonicalises image links, and inserts section headings which group
 139 related chapters together.  This modified HTML is sent to wkhtmltopdf,
 140 a command-line interface to Webkit that renders a PDF.
 141
 142 At this point the PDF has no page numbers, no gutters, no table of
 143 contents, and is using a too big paper size.  In order to write a
 144 table of contents, the text is re-extracted from the PDF and searched
 145 for invisible tags that were added along with the chapter numbers. (It
 146 is not possible to know what page a chapter will end up on before the
 147 PDF has been laid out).  The table of contents thus generated is
 148 combined with other preliminary pages and another PDF is created.
 149
 150 Pdfedit is used to crop the pages down to size and to shift them
 151 alternately left and right, creating a gutter for the spine of the
 152 book.  Then pdfedit is used again to add page numbers to both PDFs,
 153 with lowercase roman numbers being used for the preliminary pages.
 154
 155 Finally the two PDFs are combined using pdftk and, optionally, spun
 156 180 degrees so they appear upside down.  If a right-to-left book is
 157 printed like this on a left-to-right printer, the binding will be on
 158 the correct side.
 159
 160 Pdfedit and wkhtmltopdf both require an X server to run, for which
 161 Xvfb is used.
 162
 163 How this differs from Objavi beta
 164 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 165 Because it is integrated into TWiki, Objavi beta doesn't need to fetch
 166 the book or the TOC.txt over the network, and can instead construct
 167 the html using the TWiki library.  Pisa adds page numbers and
 168 generates a table of contents as it goes, and the gutter is set using
 169 its advanced CSS page support.
 170
 171
 172 Future plans
 173 ============
 174
 175 There is a TODO in the git repository, but one or two items are worth
 176 expanding.
 177
 178 It should be easy to add Gecko as an optional layout engine, so people
 179 can choose between the Webkit and Gecko versions.  Some languages
 180 might suit one more than the other, and when one grows new paged media
 181 CSS features, Objavi2 will not be stuck with the wrong choice.
 182
 183 On the other hand, Objavi2 could be tempted into a tighter snuggle
 184 with Webkit, as its front-end wkhtmltopdf is able to generate PDF
 185 outlines and tables of contents as it makes the PDF.  The way it does
 186 these things is currently unusable by Objavi2, but it could be
 187 changed.
 188
 189 Another intriguing but probably stupid possibility would be to embed
 190 Webkit directly in Objavi2 using pyQT.
 191
 192
 193 Installation
 194 ============
 195
 196 See the INSTALL file.  Apologies for its inadequacy.