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 usually
   8 converted to PDF, epub, or ODF for distribution or printing.  Programs
   9 which perform this task are called objavi (pronounced "ob-Yah-vee"),
  10 after the Croatian word "objavi!" meaning "publish!".
  11
  12 The previous objavi, Objavi beta, could produce very good PDF
  13 documents using Latin text, but did not cope well with other scripts,
  14 and could not produce other output.  Objavi 2 was originally written
  15 just to provide fully internationalised PDFs, but it has since been
  16 adapted to produce other formats.
  17
  18 Objavi 2 is free software, distributed under the version 2 or greater
  19 of the GNU General Public License.  The source can be viewed at
  20
  21  http://booki-dev.flossmanuals.net/git?p=objavi2.git
  22  (or, alternatively, http://repo.or.cz/w/objavi2.git)
  23
  24 which also contains instructions for cloning the git repository.  If
  25 you want a source tarball without worrying about git, try this link:
  26
  27  http://repo.or.cz/w/objavi2.git?a=snapshot;h=HEAD;sf=tgz
  28
  29 It is primarily written in Python, with a substantial amount of
  30 QSAScript (an ECMAscript variant) and some Javascript, HTML, and CSS.
  31
  32 The development of Objavi2 was supported by Internews.  It was
  33 extended to produce epub documents with support from the Internet
  34 Archive.
  35
  36
  37 The objavi process
  38 ==================
  39
  40 Objavi2 starts with a "booki-zip", as defined in the file
  41 "booki-zip-standard/txt".  This might be sourced from a Booki
  42 instance, or from Twiki via the booki-twiki-gateway script, or perhaps
  43 form an epub imported via Espri.
  44
  45 PDF Output
  46 ~~~~~~~~~~
  47 If a PDF is required, the HTML is concatenated, various extra bits are
  48 inserted, and the wkhtmltopdf program rederes it using WebKit.
  49
  50 At this point the PDF has no page numbers, no gutters, no table of
  51 contents, and is using a too big paper size.  In order to write a
  52 table of contents, an outline of the PDF is extracted and laid out as
  53 html.  The table of contents thus generated is combined with other
  54 preliminary pages and another PDF is created.
  55
  56 If a book PDF is required, Pdfedit is used to crop the pages down to
  57 size and to shift them alternately left and right, creating a gutter
  58 for the spine of the book.  Then pdfedit is used again to add page
  59 numbers to both PDFs, with lowercase roman numbers being used for the
  60 preliminary pages.
  61
  62 Finally the two PDFs are combined using pdftk and, optionally, spun
  63 180 degrees so they appear upside down.  If a right-to-left book is
  64 printed like this on a left-to-right printer, the binding will be on
  65 the correct side.
  66
  67 Pdfedit and wkhtmltopdf both require an X server to run, for which
  68 Xvfb is used.
  69
  70 For newspaper format, the page size is set to the column width, and
  71 pdfnup is used to arrange the columns on another page.
  72
  73 OpenOffice output
  74 ~~~~~~~~~~~~~~~~~
  75 ODF output was introduced with Objavi 2.1.  This uses an Open Office
  76 instance controlled by pyuno.
  77
  78 Epub output
  79 ~~~~~~~~~~~
  80 The html in the booki-zip is manipulated into xhtml using lxml, and
  81 the structural information and metadata is converted into epub form.
  82
  83
  84 Future plans
  85 ============
  86
  87 See http://booki-dev.flossmanuals.net/report
  88
  89 Installation
  90 ============
  91
  92 See the INSTALL file.  Apologies for its inadequacy.