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