To get refer.py to work at all these 3 .tex changes
[dwarf-doc.git] / dwarf5 / tools / README
1 These tools are intended to help updating the latex
2 source of a DWARF document to get its references
3 complete and correct.
4 A list of the python source files with the purpose
5 of each is near the end of this FILE.
6
7 SPELLCHECK: 
8 One way to do a spell check on the final document,
9 and to get a simple text output to look for word repeats
10 is to do the following (assuming you have the necessary
11 tools):
12    # -enc Latin1 to avoid utf8, we do not need utf8 here.
13    pdftotext -enc Latin1 dwarf5.pdf
14    # Now you have dwarf5.txt
15    # The _ are not understood by spell
16    sed -e 's/_//g' <dwarf5.txt >dwarf5.txt2
17    # Let upper and lower case compare equal
18    spell dwarf5.txt2 |sort -f |uniq -i
19
20 CAUTION: 
21 The tools don't really do parsing and
22 the lexical processing is barely adequate for the task.
23
24 They don't understand the % means 'comment', so avoid
25 comments containing latex code or anything like latex.
26
27 The tools are not necessarily equivalent in what
28 details of input they accept.   For example, 
29 Some will handle  \livelink{chap:DWTAGfoo}{  DW\_TAG\_foo  }
30 (notice the spaces around the DW\_TAG\_foo) and some won't.
31 So use \livelink{chap:DWTAGfoo}{DW\_TAG\_foo} instead with
32 no pointless spaces (or newlines). Then you won't be disappointed.
33
34 The tools assume you use \livelink and other local commands.
35 If you use the native latex equivalent the tools won't understand.
36
37
38 The requirement of the \ before _ in latex is annoying.
39 You can avoid work typing that cruft by just typeing
40 DW_TAG_foo  and running  tohyphen.py on the text, which will
41 turn it into   DW\-\_TAG\-\_foo which is what you want.
42 The hyphens result in nicely formatted lines with line breaks in
43 the DW_* strings, at
44 least in some contexts (but not always).
45
46
47 Various character (% - and more) have special meaning to latex.
48 So just typing them and expecting them to appear in the generated
49 document is going to result in disappointment.  See the use
50 of \dash in the document.
51
52
53 Our fundamental approach is to tokenize the input line-by-line
54 and then use trivial pattern matching to determine what
55 tokens need updating on what lines.  Always trying to ensure
56 that unless we intend to change a line that it is emitted
57 byte-for-byte unchanged.  We change lines (in most cases)
58 by simply inserting new tokens on the line (or possibly
59 inserting characters into a token).
60
61 Because latex names are non-traditional (compared to
62 other languages) we adopt an inefficient but
63 simple scanning and lexing approach.
64
65 BORING DETAILS (you can ignore what follows):
66 Every latex source file is read completely into an dwfile object 
67 which contains a 
68 List of lines
69    each line composed of a list of tokens
70        each token described below.
71
72 If we are writing out updated latex source we want all the
73 unchanged text output to match the input.  No spacing changes
74 and no changes except what the task at hand is to do.
75 So the tokens serve that task.
76
77 For example, one task at hand might be to find every DW_*
78 reference and ensure it is either a link target (livetarg) or a
79 link (livelink), and rewrite any that are neither as a link.
80 (see our latex commands livelink and livetarg in latex source).
81
82
83 Another task at hand might be to take every DW_ and rewrite
84 things like  DW\_AT\_foo as DW\-\_AT\-\_foo  so that latex
85 can hyphenate.
86
87 Sometimes we'll want to read a single latex file, sometimes several of them.
88  
89 If we're reading all the files at once (for some reason) we construct
90 an overall 
91    List of LFile (LFile mentioned above).
92
93
94 TOKENS:
95 This part is idiosyncratic to reflect our other goals.
96
97 INDIVIDUAL TOKEN characters:
98 {
99 }
100 [
101 ]
102 space-character
103 tab-character
104 are individual tokens.
105 All 4 forms (tex, underbar, std, label) are identical.
106
107 The space or tab character is an individual token.
108 All 4 forms (tex, underbar, std, label) are identical.
109
110 We swallow the input linefeed (or CR-LF) on input,
111 it does not appear in the tokens.
112
113 IDENTIFIER:
114 The letters in \-_A-Za-z0-9 allowed in an identifier.
115 An identifier begins with one of _ \ letter and has
116 at least one letter in it.
117 Identifers are held in multiple strings in a token
118         tex:   (meaning with \_ and possibly \-)
119         underbar:  (meaning with \_, no \-)
120         std:   (meaning with _ no \, as in the DWARF std)  
121         label: (meaning with no _ or \ the form used as part of labels )
122
123 OTHER:
124 All other characters are considered letters which are
125 to be reproduced on output.  A glob of such are simply considered
126 a non-identifier single token. 
127 All 4 forms (tex, underbar, std, label) are identical.
128
129
130 Performance:
131 We simply don't care about performance as long as a task takes
132 less than a few minutes. There are only about 70,000 words in a complete
133 document so we ignore efficiency issues.
134
135 SOURCE FILES:
136 The change to internal use of DWTAGfoo etc in the document
137 instead of DW\_AT\_foo (see dwarfnamecmds.tex) 
138 means many of these commands are not as useful
139 as they were originally.  But even so they may form useful
140 examples.
141
142 anylink.py: Looks for designated prefixes like DW_ADDR etc.
143   Used by other code, this was never that useful alone.
144
145 attrlink.py: Uses anylink.py to turn DW_AT_ into \livelink
146
147 copyfile.py: Uses fileio.py to parse and output a .tex file.
148  So we can use diff to verify the result is byte-for-byte
149  identical to the input.
150
151 dellivelink.py: This uses fileio.py and replaces \livelink
152  and \livetarg with \DWXXXyyy per Ron Brender email of
153  Oct 4, 2013. Strives to be idempotent so rerunning
154  produces no further changes.  A few cases not
155  handled perfectly (where a } is at end of line?) 
156  so if needed again could use a bit of fixing.
157  The list of files to process are built into the source,
158  and the list is not totally up to date.
159  The program is obsolete now though, as we
160  use \DW* very differently in the source (from when
161  this was written).
162
163 fileio.py:  Given a list of file (.tex) names, it reads in
164   and tokenizes each file.  Functions here let
165   code eventually write stuff back out (changed or not)
166   but the output file always has a ".out" appended, it won't
167   overwrite the input.
168
169 formlink.py: Using anylink.py, this transforms DW_FORM_ into
170   \livelink and \livetarg.
171
172 printnameswithinteger.py: Identical to dellivelink.py, 
173   so it is horribly misnamed!  This one needs 
174   an input list of files to process supplied on the
175   command line.
176
177
178 printstandard.py:  Print the DW_* entries (and only them)
179   in the files named on the command line
180   one per line.   With any \- or \_ removed.
181   use example:
182   python printstandard.py ../latexdoc/*.tex  |sort|uniq 
183
184 printtokens.py: Reads and tokenizes files named on the command
185   line . Prints the tokenized data.
186   Solely for debugging the tokenizing.
187
188 refclassfixup.py:  Fixes up certain strings
189   (specified in this file) to use \livelink
190
191 removehyphen.py: Turns \-\_ into \_ .
192   This was once a needed task. But run long ago, so
193   This is now a useless bit of code.
194
195 removeutf8.py:  The pdf we started from had
196   various utf-8 characters. These got in the way of
197   our text processing, so this app deleted those.
198   This is now a useless bit of code.
199   
200 taglink.py:  Finds all the instances of DW_TAG_ in 
201   .tex files named on the command line.
202
203 tohyphen.py: The opposite of removehyphen.
204   This is now a useless bit of code.
205
206 uses.py: Looks for duplicate uses and definitions of 
207   latex tags.  
208   This is based on the original approach to naming
209   and linking in .tex, not the
210   latest use using dwarfnamecmds.tex
211   
212
213