README.twiki

   1 Notes regarding Objavi's interaction with TWiki
   2 ===============================================
   3
   4 These were once part of the main README, but are less relevant now
   5 that Booki is becoming established.  However, they might still be of
   6 use to someone. so here they are.
   7
   8 Which Objavi should I use?
   9 ==========================
  10
  11 Short answer
  12 ~~~~~~~~~~~~
  13 Try both and see which you like, unless the book in question has
  14 right-to-left text, in which case you want Objavi2.
  15
  16 Details
  17 ~~~~~~~
  18 Objavi beta (written in 2008 by Aleksandar Erkalovic and Luka Frelih)
  19 is a TWiki extension that uses Pisa to make PDFs.  Pisa lets you use
  20 CSS rules to avoid widowed or orphaned text and to adjust margins.  In
  21 other regards, its CSS support is variable.  This means Objavi beta
  22 makes well laid-out books, but people writing style rules need to be
  23 aware of its quirks and use peculiar workarounds to achieve certain
  24 effects.  It only works with left-to-right scripts and possibly
  25 mis-renders some of those (due to not understanding combining
  26 characters).
  27
  28 Objavi2 uses Webkit to make PDFs.  Webkit is a common web browser
  29 engine, so it interprets CSS in a fairly predictable fashion but also
  30 has almost no concept of paged media.  It does not recognise CSS rules
  31 for setting page sizes or margins and has limited support for
  32 controlling page breaks.  (There are actually ways in which margins
  33 can be customised with Webkit but Objavi2 does not yet expose them).
  34 Webkit has very well tested Unicode support and it handles
  35 bidirectional text.
  36
  37 The page-break CSS properties supported by Webkit are
  38 page-break-before and page-break-after, which is sufficient to have
  39 each chapter start on a new page, but not to avoid breaking up
  40 paragraphs in unfortunate ways.
  41
  42 Objavi2 is somewhat faster than Objavi beta.
  43
  44
  45 The FLOSS Manuals Book Format
  46 =============================
  47
  48 FLOSS Manuals source HTML
  49 ~~~~~~~~~~~~~~~~~~~~~~~~~
  50 The subset of HTML used in FLOSS Manuals books has been pragmatically
  51 determined rather than specified.  The constraints that have shaped it
  52 are that the source must be:
  53
  54  1. easily producible and editable using the Xinha editor and by hand,
  55  2. printable using Objavi beta,
  56  3. organised into chapters, and
  57  4. conformant to the instincts and habits of the authors.
  58
  59 This has led to simplified HTML that has the following properties:
  60
  61  * Each chapter starts with an <h1> heading and contains no other <h1>
  62    elements.
  63
  64  * Each chapter is in a separate file.
  65
  66  * Fixed width elements such as images are generally no bigger than
  67    600 pixels wide.
  68
  69  * Inline style, class and id attributes are avoided.
  70
  71  * Many uncommon or irrelevant tags are avoided.
  72
  73  * <pre> blocks use less than about 80 columns, though this is
  74    commonly broken.
  75
  76  * Spurious &nbsp; entities and the like are despised but are left
  77    unmolested in practice unless they cause obvious problems.
  78
  79  * All of these guidelines are regularly broken if the printed page
  80    looks OK.
  81
  82 TOC.txt file
  83 ~~~~~~~~~~~~
  84 In addition to the HTML chapters, the source of a FLOSS Manuals book
  85 contains a file named TOC.txt which orders the chapters and groups
  86 them into sections.
  87
  88 The TOC.txt format is quite simple but fiddly to describe and thus
  89 undocumented.  An example can be seen here:
  90
  91 http://en.flossmanuals.net/pub/Audacity/_index/TOC.txt
  92
  93 and decoding methods can be found in the Objavi2 source.  Much of the
  94 information encoded in the TOC.txt file is useless to Objavi.
  95