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://booki-dev.flossmanuals.net/git?p=objavi2.git
  24  (or, alternatively, http://repo.or.cz/w/objavi2.git)
  25
  26 which also contains instructions for cloning the git repository.  If
  27 you want a source tarball without worrying about git, try this link:
  28
  29  http://repo.or.cz/w/objavi2.git?a=snapshot;h=HEAD;sf=tgz
  30
  31 It is primarily written in Python, with a substantial amount of
  32 QSAScript (an ECMAscript variant) and some Javascript, HTML, and CSS.
  33
  34 The development of Objavi2 was supported by Internews.
  35
  36 Which Objavi should I use?
  37 ==========================
  38
  39 Short answer
  40 ~~~~~~~~~~~~
  41 Try both and see which you like, unless the book in question has
  42 right-to-left text, in which case you want Objavi2.
  43
  44 Details
  45 ~~~~~~~
  46 Objavi beta (written in 2008 by Aleksandar Erkalovic and Luka Frelih)
  47 is a TWiki extension that uses Pisa to make PDFs.  Pisa lets you use
  48 CSS rules to avoid widowed or orphaned text and to adjust margins.  In
  49 other regards, its CSS support is variable.  This means Objavi beta
  50 makes well laid-out books, but people writing style rules need to be
  51 aware of its quirks and use peculiar workarounds to achieve certain
  52 effects.  It only works with left-to-right scripts and possibly
  53 mis-renders some of those (due to not understanding combining
  54 characters).
  55
  56 Objavi2 uses Webkit to make PDFs.  Webkit is a common web browser
  57 engine, so it interprets CSS in a fairly predictable fashion but also
  58 has almost no concept of paged media.  It does not recognise CSS rules
  59 for setting page sizes or margins and has limited support for
  60 controlling page breaks.  (There are actually ways in which margins
  61 can be customised with Webkit but Objavi2 does not yet expose them).
  62 Webkit has very well tested Unicode support and it handles
  63 bidirectional text.
  64
  65 The page-break CSS properties supported by Webkit are
  66 page-break-before and page-break-after, which is sufficient to have
  67 each chapter start on a new page, but not to avoid breaking up
  68 paragraphs in unfortunate ways.
  69
  70 Objavi2 is somewhat faster than Objavi beta.
  71
  72
  73 The FLOSS Manuals Book Format
  74 =============================
  75
  76 FLOSS Manuals source HTML
  77 ~~~~~~~~~~~~~~~~~~~~~~~~~
  78 The subset of HTML used in FLOSS Manuals books has been pragmatically
  79 determined rather than specified.  The constraints that have shaped it
  80 are that the source must be:
  81
  82  1. easily producible and editable using the Xinha editor and by hand,
  83  2. printable using Objavi beta,
  84  3. organised into chapters, and
  85  4. conformant to the instincts and habits of the authors.
  86
  87 This has led to simplified HTML that has the following properties:
  88
  89  * Each chapter starts with an <h1> heading and contains no other <h1>
  90    elements.
  91
  92  * Each chapter is in a separate file.
  93
  94  * Fixed width elements such as images are generally no bigger than
  95    600 pixels wide.
  96
  97  * Inline style, class and id attributes are avoided.
  98
  99  * Many uncommon or irrelevant tags are avoided.
 100
 101  * <pre> blocks use less than about 80 columns, though this is
 102    commonly broken.
 103
 104  * Spurious &nbsp; entities and the like are despised but are left
 105    unmolested in practice unless they cause obvious problems.
 106
 107  * All of these guidelines are regularly broken if the printed page
 108    looks OK.
 109
 110 TOC.txt file
 111 ~~~~~~~~~~~~
 112 In addition to the HTML chapters, the source of a FLOSS Manuals book
 113 contains a file named TOC.txt which orders the chapters and groups
 114 them into sections.
 115
 116 The TOC.txt format is quite simple but fiddly to describe and thus
 117 undocumented.  An example can be seen here:
 118
 119 http://en.flossmanuals.net/pub/Audacity/_index/TOC.txt
 120
 121 and decoding methods can be found in the Objavi2 source.  Much of the
 122 information encoded in the TOC.txt file is useless to Objavi.
 123
 124
 125 The objavi process
 126 ==================
 127
 128 Objavi2 starts with the chapters of a book concatenated in order, as
 129 provided by links like this:
 130
 131 http://en.flossmanuals.net/bin/view/Audacity/_all?skin=text
 132
 133 and separately fetches the TOC.txt file described above.  Using lxml
 134 (an xml/html library), it finds and numbers chapter headings,
 135 canonicalises image links, and inserts section headings which group
 136 related chapters together.  This modified HTML is sent to wkhtmltopdf,
 137 a command-line interface to Webkit that renders a PDF.
 138
 139 At this point the PDF has no page numbers, no gutters, no table of
 140 contents, and is using a too big paper size.  In order to write a
 141 table of contents, an outline of the PDF is extracted and laid out as
 142 html.  The table of contents thus generated is combined with other
 143 preliminary pages and another PDF is created.
 144
 145 Pdfedit is used to crop the pages down to size and to shift them
 146 alternately left and right, creating a gutter for the spine of the
 147 book.  Then pdfedit is used again to add page numbers to both PDFs,
 148 with lowercase roman numbers being used for the preliminary pages.
 149
 150 Finally the two PDFs are combined using pdftk and, optionally, spun
 151 180 degrees so they appear upside down.  If a right-to-left book is
 152 printed like this on a left-to-right printer, the binding will be on
 153 the correct side.
 154
 155 Pdfedit and wkhtmltopdf both require an X server to run, for which
 156 Xvfb is used.
 157
 158 How this differs from Objavi beta
 159 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 160 Because it is integrated into TWiki, Objavi beta doesn't need to fetch
 161 the book or the TOC.txt over the network, and can instead construct
 162 the html using the TWiki library.  Pisa adds page numbers and
 163 generates a table of contents as it goes, and the gutter is set using
 164 its advanced CSS page support.
 165
 166 OpenOffice output
 167 ~~~~~~~~~~~~~~~~~
 168 ODF output was introduced with Objavi 2.1.  This uses an Open Office
 169 instance controlled by pyuno.
 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.