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