INTERNALS

   1 =================================================================
   2 how it works
   3 =================================================================
   4 The books are written in LaTeX. There are two things that make the
   5 setup more complex than just compiling a normal LaTeX file:
   6 - I've written some software to make it easier to do the type of
   7   visual layout I want, with figures positioned in the margins.
   8   The software makes sure the figures don't go off the top or
   9   bottom of the page, and also produces a warning if figures
  10   overlap.
  11 - I've also written some software to produce html output. Although
  12   this software makes use of tex4ht for certain functionality
  13   (tables), it's mainly bespoke. The math is converted using
  14   a script I wrote called footex, which is basically a wrapper
  15   for blahtex and texvc, with some extra functionality added on
  16   top.
  17 - I also use the m4 macro preprocessor to handle certain things,
  18   especially to avoid duplication between books by including content
  19   from the shared directory 9share. Although LaTeX is also a macro
  20   engine, the point of doing this is that LaTeX isn't my only output
  21   format.
  22
  23 =================================================================
  24 makefiles
  25 =================================================================
  26 To build a book in pdf format from scratch, do:
  27   make book
  28 The default target only recompiles the book once, which won't get the
  29 indexing, table of contents, etc. right:
  30   make
  31 This is only for doing further iterations once an initial "make book"
  32 has been done.
  33
  34 Options for pdf output:
  35   POPT='only01' make
  36       Only processes chapter 1 of the book in pdftex. Uses the latex
  37       includeonly mechanism, so page numbers are not mesed up.
  38
  39 The software for generating html output has various options that
  40 can be used on the command line. Example:
  41   WOPT='--test' make web
  42 Options:
  43   --test
  44       Generates html output in test mode, for local viewing
  45      (no ads, refers to local copy of css file).
  46   --no_write
  47       Don't actually write output.
  48   --redo_all_equations
  49       Don't used cached copies of equations. For use after
  50       modifying the software for translation of math.
  51   --redo_all_tables
  52       Similar, for tables.
  53
  54 =================================================================
  55 sectioning
  56 =================================================================
  57 Sections, subsections, etc., are created like this
  58   <% begin_sec("Rules of Randomness") %>
  59   <% end_sec() %>
  60 If the same text is going to be included in two different books,
  61 then this may end up being a section in one book, and a subsection
  62 in the other. If you give the title in titlecase, then it will
  63 automatically be converted to non-titlecase in the book where it's
  64 the title of a subsection.
  65 There are two optional arguments to begin_sec. The first is an integer
  66 from 0 to 4 that controls the likelihood of a page break, as with the
  67 latex \pagebreak[n] command. The second optional argument is a latex
  68 label, e.g., giving an argument 'foo' would make a label like 'sec:foo'
  69 or 'subsec:foo'.
  70
  71 =================================================================
  72 m4
  73 =================================================================
  74 Every chapter gets a bunch of m4 files prepended to it:
  75   lm.m4 (applies to all books, not just LM series)
  76   sn.m4 or lmseries.m4
  77   book.m4
  78   chapter.m4
  79 These are in appropriate locations in the directory hierarchy.
  80 It's OK if one of these files doesn't actually exist.
  81 M4 is invoked with the -P option, so all built-in m4 macros have
  82 to have the prefix m4_ on the front. By convention, my own m4 macros
  83 have __ on the front. In lm.m4, the quoting characters for m4 are
  84 defined to be [: and :], and comments are defined as //%, extending
  85 to the end of the line, so //%% makes something that's guaranteed to
  86 be a LaTeX comment, and //%# is a ruby comment.
  87 Macros I define:
  88   macro        example             defined in
  89   __web        0,1                 run_eruby.pl
  90   __share      ../share/optics/    run_eruby.pl
  91   __incl                           lm.m4
  92   __sincl                          lm.m4
  93   __calc       1,0                 sn.m4, lmseries.m4
  94   __lm_series  0,1                 sn.m4, lmseries.m4
  95   __sn         0,1
  96   __cp         0,1
  97   __me         0,1
  98   __pe         U,PE                sn.m4, lmseries.m4
  99 Conditionals:
 100   m4_ifelse(__calc,1,[:calculus:],[:no, calculus is scary:])
 101   m4_ifelse(__pe,PE,[:magnetic potential energy:],[:magnetic energy:])
 102   I have a separate mechanism for doing conditional includes, described below.
 103 Includes:
 104   __incl(eg/steam_engine) ... includes eg/steam_engine.tex
 105   __sincl(maybe) ... no error if it doesn't exist
 106   m4_include(../share/optics/lens.tex) ... include from a directory that's not the standard one for this chapter
 107 Conditional includes:
 108   See my m4 notes for why this is so hard to get right.
 109   Can use __share/text here, which, e.g., may be defined as ../share/optics.
 110   <% begin_if(__me) %>m4_include(__share/text/foo.tex)<% end_if %>
 111     foo.tex can contain eruby and m4, and everybody plays nicely together
 112     foo.tex gets included and processed through m4 and eruby no matter what; but if the conditional fails, then
 113            latex doesn't actually produce output for the included material;
 114     because of current implementation using LaTeX comment package, I force line breaks at begin and end;
 115     argument of begin_if can be 0, 1, true, false; in ruby, !0 is false, so don't do stuff like !__me
 116 References to sections and chapters:
 117   Typically a section in SN is a chapter in LM.
 118   __section_or_chapter(foo) expands to "section \ref{sec:foo}" in SN, "chapter \ref{ch:foo}" in LM
 119   __uc_section_or_chapter(foo) expands to "Section \ref{sec:foo}" in SN, "Chapter \ref{ch:foo}" in LM
 120   __bare_section_or_chapter(foo) expands to "\ref{sec:foo}" in SN, "\ref{ch:foo}" in LM
 121   __pageref_subsection_or_section(foo) expands to a pageref
 122   __subsection_or_section(foo)
 123   __uc_subsection_or_section(foo)
 124   __bare_subsection_or_section(foo)
 125   *** Names are all little_or_big; think of little things growing big.
 126
 127 =================================================================
 128 figures, fonts, rendering figures
 129 =================================================================
 130 The main font in the figures is 10-point Bitstream Vera Sans or its drop-in
 131 replacement Deja Vu Sans. Figures should be rendered to PDF or JPG format
 132 using the script render_one_figure.pl, which makes sure that there aren't
 133 problems with RIP associated with transparency or with fonts that aren't
 134 embedded.
 135
 136 =================================================================
 137 figure positioning
 138 =================================================================
 139 Figures are positioned using a feedback loop. We run pdftex, and use pdflatex commands (\pdfsavepos,
 140 \recordpos) to record the location on the page where each figure actually ended up.
 141 The next time through the loop, eruby_util.rb uses this information to reposition the
 142 figure in case, e.g., it ended up falling off the bottom of the page.
 143 scripts
 144   process_geom_file.pl
 145     filters geom.pos, converting points to millimeters
 146   check_for_colliding_figures.rb
 147     reads chNN.pos, prints warnings
 148   eruby_util.rb
 149     height_of_marg() reads marg.pos, chNN.pos
 150 files:
 151   geom.pos:
 152       11.40  63.40 154.40 206.40  28.00 258.00
 153       written by tex, filtered by process_geom_file.pl
 154   marg.pos:
 155     fig:guitar-harmonic,nmarg=10,ch=4
 156     fig:fourier,nmarg=10,ch=4
 157     fig:fourier-spectra,nmarg=11,ch=4
 158     Written by fig(). Used to record what figures are associated with what margin blocks.
 159     Read by height_of_marg().
 160     It might seem weird to write this and then just read it back myself, but it tells me about
 161     figures that I haven't yet enountered in this margin block on this run.
 162     Grows every time you run an iteration, but that's necessary, and we always take the most recent record.
 163   chNN.pos:
 164     fig,label=fig:lowest-modes-of-air-column,page=94,x=11822068,y=48015505,at=begin
 165     fig,label=fig:lowest-modes-of-air-column,page=94,x=11822068,y=33727285,at=endgraphic
 166     fig,label=fig:lowest-modes-of-air-column,page=94,x=11530797,y=29008693,at=endcaption
 167     Renamed from all.pos by latex code generated by end_chapter() in eruby_util.rb.
 168     Read by height_of_marg() in eruby_util.rb
 169     Read by process_pos_file.pl, to give warnings. (script doesn't exist?)
 170     In cases where the figure mysteriously ends up on a different page than the one where it was invoked, this file
 171     gives the page number where they really ended up.
 172   all.pos
 173     Written by \recordpos in lmfigs.sty, based on \pdfsavepos and code emitted by ruby. Later gets renamed to chNN.pos by latex code in book.tex.
 174   figfeedbackNN:
 175      10,page=90,refx=13500281,refy=37922604,deltay=40
 176      11,page=91,refx=6041561,refy=41061462,deltay=40
 177      Written by \begin{margin}, read by marg() the next time around.
 178      Purpose is to find out where the user is asking to have the margin block placed vertically,
 179         and to figure out whether the page number is odd or even, so we can do horizontal placement as well.
 180     In cases where the figure mysteriously ends up on a different page than the one where it was invoked, this file
 181     gives the page number on which it was invoked.
 182
 183 =================================================================
 184 data about problems
 185 =================================================================
 186 When you compile a book, it makes a CSV file for each chapter,
 187 chNN_problems.csv, which looks like this:
 188   cl,4,3,planes,0
 189 The fields are book, chapter, problem number, name, and a flag that
 190 equals 1 if there's a solution in the back of the book. These can be
 191 compiled into one big file, data/problems.csv. To compile the big file,
 192 build all the books, and then do a "make problems". The names are supposed
 193 to correlate with the names of the files in which the solutions are
 194 stored. It also makes problems.m4, with lines like this:
 195   m4_define(__hw_cl_4_planes,3)m4_dnl
 196 The m4 file makes it possible to refer to problems across books, or from one
 197 solution to another problem, but I'm
 198 not actually using this mechanism yet, and I'd prefer to refine it
 199 to avoid having such a huge m4 symbol table; should make it so that an
 200 m4 definition is written only if I somehow flag that one as being necessary.
 201
 202 Problems have symbolic names in three different places:
 203   1) book's source code (and CSV generated from it)
 204   2) name of file containing the solution
 205   3) spotter file
 206 If 1 and 2 are inconsistent, it's an error. The same homework problem may
 207 also occur in more than one book, and should then preferably have the same name.
 208 If 3 is inconsistent with 1 and 2, it can be fixed by doing a howdy --rename.
 209
 210 Renaming a problem:
 211   - change name in book's source code
 212   - change name of file containing solution
 213   - check for references like \ref{hw:foo} and \pageref{hw:foo}
 214   - optionally, change name in spotter file
 215
 216 Renumbering a problem:
 217   - reorder it in book's source code
 218   - change it in spotter file (or run howdy --renumber)
 219   - change syllabi