084d240266d41e09622685f3b99e1ee63e1352cb
[dwarf-doc.git] / dwarf5 / latexdoc / README
1
2 On undefined references while building the document: In
3 early latex passes forward references tend to be reported as
4 'undefined'.   An example is:
5
6 LaTeX Warning: Reference `chap:generaldescription' on page
7 3 undefined on input line 59.
8
9 Because the side-files latex generates help resolve those in
10 later passes the simple existence of 'undefined' in a 'make'
11 on a 'clean' directory should not be alarming as these will
12 usually be from an early pass.  Run a second 'make' without
13 doing a 'make clean' (thus using the side-files from the first
14 'make') and if all is well the second 'make' will not generate
15 any messages about 'undefined'.
16
17 ============================
18
19 On Linux:
20 On modern linux, here is the set of steps to build a pdf.
21 While pdflatex might seem simpler to use (than the following)
22 it will not correctly generate a pdf as complex as this one.
23
24         latex dwarf5.tex
25         latex dwarf5.tex
26         makeindex dwarf5
27         latex dwarf5.tex
28         latex dwarf5.tex
29         dvips dwarf5.dvi -o dwarf5.ps
30         ps2pdf dwarf5.ps dwarf5.pdf
31
32
33
34 On Windows:
35 This Editor has used TeXworks on Windows successfully.
36 The About TeXworks tab describes it as "a simple
37 environment for edititing, typesetting and previewing
38 TeX documents". It is based on MiKTeX, which is Open
39 Source (and free). See
40     http://www.tug.org/texworks/
41 and/or
42     http://code.google.com/p/texworks/downloads/list
43 for full details. It is supported on Windows XP/Vista/7
44 and installed easily.
45
46 TeXworks presents two windows--one for editing and one
47 for viewing the final .pdf. The DWARF document build is 
48 fast enough to use TeXworks as an "almost WYSIWYG" 
49 environment.
50
51
52 On Mac OS X:
53 To Be added
54
55
56 ============================
57
58 The DWARF5 latex document was first added here May 10, 2012.
59 The plan is to achieve a complete (insofar as is possible)
60 identical-to-DWARF4 document (which is referred to as DWARF
61 4.1).  Mark that with a git tag.   Then proceed to change
62 the document with DWARF5 changes.
63
64 ============================
65
66 A limitation of LaTex is that it does not handle multipage
67 figures at all (they just run off the bottom of the page).
68 It appears the best that can be done is to split figures
69 "by hand" into multiple figures. Advise on how to do this
70 was found at
71
72 www.staff.science.uu.nl/~oostr102/floats/node4.html#SECTION00022000000000000000
73
74 and included here:
75
76 "There isn't an equivalent longfigure solution, so for figures
77 you will usually have to split it yourself. In general this is 
78 less of a problem. However, the problem you get now is how to 
79 keep them together, i.e. how to get the parts on subsequent 
80 pages, and how to get a single entry in the list of figures.
81
82 "You will have to split the figure into pieces and put each part 
83 in a separate figure environment. To keep them together it is 
84 best to use only the [p] placement, so that they will be put on 
85 floatpages. As they are bigger than a page this is appropriate. 
86 The first part would then get a \caption, the subsequent parts 
87 would be used without a caption. If you want to add a caption-
88 like text, enter it as normal text rather than a \caption, so 
89 that it will not be entered in the list of figures. It may also 
90 be desirable to issue a \clearpage first, just like we did for 
91 the longtable, and to encapsulate this in the \afterpage command. 
92 E.g.
93
94 \afterpage{\clearpage\input{myfigure}}
95
96 where myfigure.tex contains:
97
98 \begin{figure}[p]
99 \includegraphics{myfig1.eps}
100 \caption{This is a multipage figure}
101 \label{fig:xxx}
102 \end{figure}
103 \begin{figure}[p]
104 \includegraphics{myfig2.eps}
105 \begin{center}
106 Figure~\ref{fig:xxx} (continued)
107 \end{center}
108 \end{figure}
109
110 "You have to make sure that the last part is big enough, otherwise 
111 LaTeX could decide to postpone it until it has collected some more 
112 floats. This can be done either by making the figure big enough 
113 (e.g. by adding some \vspace), or by tweaking the \floatpagefraction 
114 floatpagefraction parameter.
115
116 "If you want your multipage figure to start at a lefthand-side (even-
117 numbered) page you can use a test in the \afterpage command (using 
118 the ifthen package):
119
120 \afterpage{\clearpage
121 \ifthenelse{\isodd{\value{page}}{\afterpage{\input{myfigure}}} % odd page
122     {\input{myfigure}}}} % even page
123
124 "If there are too many floats on the skipped page, this may still fail 
125 to start your multipage figure on an even page, however."
126
127 This is basically the strategy used in the DWARF V4.1 and later documents.
128 See especially Appendices D (Examples) and E (Compresion) for numerous
129 examples.
130