| blob | 00da0d3168307244fcca9886b4d9a696253e9788 |
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.
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.
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.
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.
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'.
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.
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.
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.
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.
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.
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
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