README

   1 =================================================================
   2 producing pdf output
   3 =================================================================
   4 Compiling the book into pdf format is fairly easy on a Linux
   5 machine. Basically you just need to install some open-source
   6 software. The following are the relevant packages on a Debian-based
   7 system such as Ubuntu:
   8   texlive-full
   9   m4
  10   inkscape
  11   imagemagick
  12   libjson-ruby
  13   libjson-perl (version 2.0 or higher)
  14   ruby 1.9.2, packaged as ruby1.9 (karmic koala) or simply as ruby (lucid lynx)
  15   xml-twig-tools
  16   qpdf
  17   poppler-utils
  18
  19 Go to the main directory (the one where you found this README).
  20
  21 Make sure you have at least inkscape 0.47 and ruby 1.9. The following
  22 command will make all the necessary scripts executable, and will
  23 also test whether your version of ruby is new enough to use:
  24   make setup
  25
  26 Convert all the figures from editable svg format to pdf format:
  27   make lm_cover
  28   make all_figures
  29 Ignore the warnings that say "WARNING **: No export filename given
  30 and no filename hint. Nothing exported."
  31
  32 Produce pdf output of all the books:
  33   make books_all
  34
  35 If you have trouble getting this to work, see the section below titled
  36 "troubleshooting, bugs, and workarounds."
  37
  38 I haven't tried compiling the books on MacOS X or Windows. I suspect
  39 it could be done on MacOS X without any heroic measures, and I suspect
  40 that it would be a real pain on Windows.
  41
  42 =================================================================
  43 producing html, epub, and mobi output
  44 =================================================================
  45 To produce html output requires a little more software. First, you
  46 need the following additional Debian packages:
  47   xpdf imagemagick tex4ht dvipng
  48 (The xpdf dependency is because of pdftoppm, which comes bundled
  49 with it.)
  50
  51 You'll also need footex:
  52   http://www.lightandmatter.com/footex/footex.html
  53
  54 If you want to produce epub and mobi output, you'll also need
  55 to install calibre.
  56
  57 Once you've done this, you can use this command:
  58   make web
  59
  60 =================================================================
  61 troubleshooting, bugs, and workarounds
  62 =================================================================
  63 If you modify a file between compiles, it may cause ruby errors.
  64   Workaround: recompile from scratch.
  65   I think this may happen if your edits change which figure groups exist.
  66 Figures are positioned on the wrong side of the page, as if odd and even
  67 are confused. This continues through the end of the chapter.
  68   This happened to me in May '08 with ch. 10 of SN. Doing a
  69   make clean && make book to start fresh didn't help. However,
  70   when I got up the next morning and tried again, it didn't happen!
  71   This may be a problem where iterations of pdflatex don't converge
  72   on pagination.
  73 Narrowfigwidecaption doesn't reliably detect even/odd page.
  74 Goofy typesetting of symbols at end of hw in SN.
  75   Don't use \hwendpart macro at the very end of a problem.
  76 'Make prepress' dies with an error from ghostscript,
  77   "ExtGState 's6' is unknown".
  78   This happens with some figures when the figure is saved as
  79   pdf by inkscape, e.g., gravity-probe-g-geodetic. The workaround
  80   is to save it as a bitmap. The error can be detected by opening
  81   the file with xpdf; uses same lib as gs, gives same error.
  82   https://bugs.launchpad.net/inkscape/+bug/681512
  83   This is a problem with cairo, can be fixed by upgrading from
  84   ubuntu maverick to natty.
  85 Figure positioning doesn't work, no feedback loop.
  86   This can happen because there is no end_chapter in the rbtex file.
  87
  88 ====================
  89
  90 More technical details about the software setup are in INTERNALS.