Seemingly dellivelink.py works properly now, though
[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 CAUTION: 
6 The tools don't really do parsing and
7 the lexical processing is barely adequate for the task.
8
9 They don't understand the % means 'comment', so avoid
10 comments containing latex code or anything like latex.
11
12 The tools are not necessarily equivalent in what
13 details of input they accept.   For example, 
14 Some will handle  \livelink{chap:DWTAGfoo}{  DW\_TAG\_foo  }
15 (notice the spaces around the DW\_TAG\_foo) and some won't.
16 So use \livelink{chap:DWTAGfoo}{DW\_TAG\_foo} instead with
17 no pointless spaces (or newlines). Then you won't be disappointed.
18
19 The tools assume you use \livelink and other local commands.
20 If you use the native latex equivalent the tools won't understand.
21
22
23 The requirement of the \ before _ in latex is annoying.
24 You can avoid work typing that cruft by just typeing
25 DW_TAG_foo  and running  tohyphen.py on the text, which will
26 turn it into   DW\-\_TAG\-\_foo which is what you want.
27 The hyphens result in nicely formatted lines with line breaks in
28 the DW_* strings, at
29 least in some contexts (but not always).
30
31
32 Various character (% - and more) have special meaning to latex.
33 So just typing them and expecting them to appear in the generated
34 document is going to result in disappointment.  See the use
35 of \dash in the document.
36
37
38 Our fundamental approach is to tokenize the input line-by-line
39 and then use trivial pattern matching to determine what
40 tokens need updating on what lines.  Always trying to ensure
41 that unless we intend to change a line that it is emitted
42 byte-for-byte unchanged.  We change lines (in most cases)
43 by simply inserting new tokens on the line (or possibly
44 inserting characters into a token).
45
46 Because latex names are non-traditional (compared to
47 other languages) we adopt an inefficient but
48 simple scanning and lexing approach.
49
50 BORING DETAILS (you can ignore what follows):
51 Every latex source file is read completely into an dwfile object 
52 which contains a 
53 List of lines
54    each line composed of a list of tokens
55        each token described below.
56
57 If we are writing out updated latex source we want all the
58 unchanged text output to match the input.  No spacing changes
59 and no changes except what the task at hand is to do.
60 So the tokens serve that task.
61
62 For example, one task at hand might be to find every DW_*
63 reference and ensure it is either a link target (livetarg) or a
64 link (livelink), and rewrite any that are neither as a link.
65 (see our latex commands livelink and livetarg in latex source).
66
67
68 Another task at hand might be to take every DW_ and rewrite
69 things like  DW\_AT\_foo as DW\-\_AT\-\_foo  so that latex
70 can hyphenate.
71
72 Sometimes we'll want to read a single latex file, sometimes several of them.
73  
74 If we're reading all the files at once (for some reason) we construct
75 an overall 
76    List of LFile (LFile mentioned above).
77
78
79 TOKENS:
80 This part is idiosyncratic to reflect our other goals.
81
82 INDIVIDUAL TOKEN characters:
83 {
84 }
85 [
86 ]
87 space-character
88 tab-character
89 are individual tokens.
90 All 4 forms (tex, underbar, std, label) are identical.
91
92 The space or tab character is an individual token.
93 All 4 forms (tex, underbar, std, label) are identical.
94
95 We swallow the input linefeed (or CR-LF) on input,
96 it does not appear in the tokens.
97
98 IDENTIFIER:
99 The letters in \-_A-Za-z0-9 allowed in an identifier.
100 An identifier begins with one of _ \ letter and has
101 at least one letter in it.
102 Identifers are held in multiple strings in a token
103         tex:   (meaning with \_ and possibly \-)
104         underbar:  (meaning with \_, no \-)
105         std:   (meaning with _ no \, as in the DWARF std)  
106         label: (meaning with no _ or \ the form used as part of labels )
107
108 OTHER:
109 All other characters are considered letters which are
110 to be reproduced on output.  A glob of such are simply considered
111 a non-identifier single token. 
112 All 4 forms (tex, underbar, std, label) are identical.
113
114
115 Performance:
116 We simply don't care about performance as long as a task takes
117 less than a few minutes. There are only about 70,000 words in a complete
118 document so we ignore efficiency issues.