An initial set of text tools to help with
[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
5 Our fundamental approach is to tokenize the input line-by-line
6 and then use trivial pattern matching to determine what
7 tokens need updating on what lines.  Always trying to ensure
8 that unless we intend to change a line that it is emitted
9 byte-for-byte unchanged.  We change lines (in most cases)
10 by simply inserting new tokens on the line (or possibly
11 inserting characters into a token).
12
13 Because latex names are non-traditional (compared to
14 other languages) we adopt an inefficient but
15 simple scanning and lexing approach.
16
17 Every latex source file is read completely into an dwfile object 
18 which contains a 
19 List of lines
20    each line composed of a list of tokens
21        each token described below.
22
23 If we are writing out updated latex source we want all the
24 unchanged text output to match the input.  No spacing changes
25 and no changes except what the task at hand is to do.
26 So the tokens serve that task.
27
28 For example, one task at hand might be to find every DW_*
29 reference and ensure it is either a link target (livetarg) or a
30 link (livelink), and rewrite any that are neither as a link.
31 (see our latex commands livelink and livetarg in latex source).
32
33
34 Another task at hand might be to take every DW_ and rewrite
35 things like  DW\_AT\_foo as DW\-\_AT\-\_foo  so that latex
36 can hyphenate.
37
38 Sometimes we'll want to read a single latex file, sometimes several of them.
39  
40 If we're reading all the files at once (for some reason) we construct
41 an overall 
42    List of LFile (LFile mentioned above).
43
44
45 TOKENS:
46 This part is idiosyncratic to reflect our other goals.
47
48 INDIVIDUAL TOKEN characters:
49 {
50 }
51 [
52 ]
53 space-character
54 tab-character
55 are individual tokens.
56 All 4 forms (tex, underbar, std, label) are identical.
57
58 The space or tab character is an individual token.
59 All 4 forms (tex, underbar, std, label) are identical.
60
61 We swallow the input linefeed (or CR-LF) on input,
62 it does not appear in the tokens.
63
64 IDENTIFIER:
65 The letters in \-_A-Za-z0-9 allowed in an identifier.
66 An identifier begins with one of _ \ letter and has
67 at least one letter in it.
68 Identifers are held in multiple strings in a token
69         tex:   (meaning with \_ and possibly \-)
70         underbar:  (meaning with \_, no \-)
71         std:   (meaning with _ no \, as in the DWARF std)  
72         label: (meaning with no _ or \ the form used as part of labels )
73
74 OTHER:
75 All other characters are considered letters which are
76 to be reproduced on output.  A glob of such are simply considered
77 a non-identifier single token. 
78 All 4 forms (tex, underbar, std, label) are identical.
79
80
81 Performance:
82 We simply don't care about performance as long as a task takes
83 less than a few minutes. There are only about 70,000 words in a complete
84 document so we ignore efficiency issues.