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