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