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