tools/README: Added another quick check that finds
[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 Install the MacTeX distribution from http://www.tug.org/mactex/ 
54 All of the necessary tools will be installed in a directory like
55 /usr/local/texlive/2012/bin/x86_64-darwin/
56
57 The same instructions for Linux will now work.
58
59
60 ============================
61
62 The DWARF5 latex document was first added here May 10, 2012.
63 The plan is to achieve a complete (insofar as is possible)
64 identical-to-DWARF4 document (which is referred to as DWARF
65 4.1).  Mark that with a git tag.   Then proceed to change
66 the document with DWARF5 changes.
67
68 ============================
69
70 A limitation of LaTex is that it does not handle multipage
71 figures at all (they just run off the bottom of the page).
72 It appears the best that can be done is to split figures
73 "by hand" into multiple figures. Advise on how to do this
74 was found at
75
76 www.staff.science.uu.nl/~oostr102/floats/node4.html#SECTION00022000000000000000
77
78 and included here:
79
80 "There isn't an equivalent longfigure solution, so for figures
81 you will usually have to split it yourself. In general this is 
82 less of a problem. However, the problem you get now is how to 
83 keep them together, i.e. how to get the parts on subsequent 
84 pages, and how to get a single entry in the list of figures.
85
86 "You will have to split the figure into pieces and put each part 
87 in a separate figure environment. To keep them together it is 
88 best to use only the [p] placement, so that they will be put on 
89 floatpages. As they are bigger than a page this is appropriate. 
90 The first part would then get a \caption, the subsequent parts 
91 would be used without a caption. If you want to add a caption-
92 like text, enter it as normal text rather than a \caption, so 
93 that it will not be entered in the list of figures. It may also 
94 be desirable to issue a \clearpage first, just like we did for 
95 the longtable, and to encapsulate this in the \afterpage command. 
96 E.g.
97
98 \afterpage{\clearpage\input{myfigure}}
99
100 where myfigure.tex contains:
101
102 \begin{figure}[p]
103 \includegraphics{myfig1.eps}
104 \caption{This is a multipage figure}
105 \label{fig:xxx}
106 \end{figure}
107 \begin{figure}[p]
108 \includegraphics{myfig2.eps}
109 \begin{center}
110 Figure~\ref{fig:xxx} (continued)
111 \end{center}
112 \end{figure}
113
114 "You have to make sure that the last part is big enough, otherwise 
115 LaTeX could decide to postpone it until it has collected some more 
116 floats. This can be done either by making the figure big enough 
117 (e.g. by adding some \vspace), or by tweaking the \floatpagefraction 
118 floatpagefraction parameter.
119
120 "If you want your multipage figure to start at a lefthand-side (even-
121 numbered) page you can use a test in the \afterpage command (using 
122 the ifthen package):
123
124 \afterpage{\clearpage
125 \ifthenelse{\isodd{\value{page}}{\afterpage{\input{myfigure}}} % odd page
126     {\input{myfigure}}}} % even page
127
128 "If there are too many floats on the skipped page, this may still fail 
129 to start your multipage figure on an even page, however."
130
131 This is basically the strategy used in the DWARF V4.1 and later documents.
132 See especially Appendices D (Examples) and E (Compresion) for numerous
133 examples.
134