Debian Codegraph @

texmf-dist/doc/luatex/interpreter/i-doc.lua

raw
1 --[[
2 Here's a description of "i-doc.lua", the file containing the interpretation
3 used for Interpreter's documentation. Remember that none of the TeX macros
4 used here is defined by Interpreter; instead, they are my own and should be
5 adapted if necessary. Also several options taken here are far from optimal but
6 are convenient examples.
7
8 Shorthands for often used functions.
9 --]]
10 local gsub, match = string.gsub, string.match
11 local add_pattern = interpreter.add_pattern
12 local nomagic = interpreter.nomagic
13
14 --[[
15 Class 1 and 2 will be used for verbatim (thus protecting) and ``normal''
16 patterns go into class 3 or higher.
17 --]]
18 interpreter.default_class = 3
19
20 --[[
21 The reader might have observed that "interpreter-doc.txt" begins with a table
22 of contents. This table is useful for the source file only, and isn't typeset
23 by TeX, because the following pattern suppresses it: the entire paragraph
24 containing "TABLE OF CONTENTS" on a line of its own is deleted. Protecting the
25 paragraph is useless, but it makes things a little bit faster because the
26 paragraph won't be pointlessly searched for other patterns.
27 --]]
28 local function contents (buffer)
29 for n in ipairs(buffer) do
30 buffer[n] = ""
31 end
32 interpreter.protect()
33 end
34 add_pattern{
35 pattern = "^%s*TABLE OF CONTENTS%s*$",
36 call = contents,
37 class = 1
38 }
39
40 --[[
41 Sections headers are typeset as
42
43 ====================================== section_tag
44 === Section title ====================
45 ======================================
46
47 The first and third line are decorations and they are removed. The
48 "section_tag" is meant for the source only again (linking the section to the table
49 of contents). I could have used it to create PDF destinations, but that seemed
50 unnecessary in such a small file. The associated pattern is: at least four
51 equals signs.
52 --]]
53 add_pattern{
54 pattern = "^====+.*",
55 replace = ""
56 }
57
58 --[[
59 The middle line is spotted with the tree equals sign at the beginning of the
60 line (the previous pattern being longer, the decoration lines have been
61 already removed and they won't be taken for section titles). The signs are
62 removed and replaced with "\section{" and "}".
63 --]]
64 local function section (buffer, num)
65 local l = buffer[num]
66 l = gsub(l, "^===%s*", "\\section{")
67 l = gsub(l, "%s*=+%s*", "}")
68 buffer[num] = l
69 end
70 add_pattern{
71 pattern = "^===",
72 call = section
73 }
74
75 --[[
76 The following pattern simply turns "Interpreter" into "\ital{Interpreter}". The
77 meaning of the "\ital" command is obvious, I suppose. Note the offset:
78 starting at the backslash, this leads to the _n_ in Interpreter, thus avoiding
79 matching the pattern again. The Lua notation with double square brackets is
80 used for strings with no escape character (hence "\ital" and not "\\ital" as
81 would be necessary with a simple string).
82 --]]
83 add_pattern{
84 pattern = "Interpreter",
85 replace = [[\ital{Interpreter}]],
86 offset = 7
87 }
88
89 --[[
90 Turning "TeX" into TeX. This illustrates the use of a function as "replace";
91 the point is that "\TeX" should be suffixed with a space if initially followed
92 by anything but a space or end of line (so as not to form a control sequence
93 with the following letters), and it should be suffixed with a control space if
94 initially followed by a space or end of line (so as to avoid gobbling the
95 space). So the function checks the second capture. Note that simply replacing
96 "TeX" with "\TeX{}" would be much simpler, but less instructive!
97 --]]
98 local function maketex (tex, next)
99 if next == " " or next == "" then
100 return [[\TeX\ ]]
101 else
102 return [[\TeX ]] .. next
103 end
104 end
105 add_pattern{
106 pattern = "(TeX)(.?)",
107 replace = maketex,
108 offset = 2
109 }
110
111 --[[
112 The following turns "<text>" into <text> and "_text_" into _text_. Setting a
113 class just so the patterns inherit the "nomagic" feature is of course an
114 overkill, but that's an example.
115 --]]
116 interpreter.set_class(4, {nomagic = true})
117 add_pattern{
118 pattern = "<...>",
119 replace = [[\arg{%1}]],
120 class = 4
121 }
122 add_pattern{
123 pattern = "_..._",
124 replace = [[\ital{%1}]],
125 class = 4
126 }
127
128 --[[
129 I use double quotes as protectors; they are replaced with a "\verb" command at
130 the very end of the processing (with class 0).
131 --]]
132 interpreter.protector('"')
133 add_pattern{
134 pattern = nomagic'"..."',
135 replace = [[\verb`%1`]],
136 class = 0
137 }
138
139 --[[
140 The description of functions (in red in the PDF file) are handled with the
141 "\describe" macro, which takes the function as its first argument and
142 additional information as its second one (typeset in italics in the PDF file).
143 In the source, it is simply marked as
144
145 > function (arguments) [Additional information]
146
147 with "[Additional information]" sometimes missing (i.e. there is no empty
148 pairs of square brackets). Descriptions of entries in pattern tables follows
149 the same syntax, except the line begins with ">>". So the pattern first spots
150 lines beginning with ">[>]" followed by at least one space, adds an empty pair of
151 brackets at the end if there isn't any, and turn the whole into "\describe".
152 The number of ">" symbols sets "\describe"'s third argument, which specifies
153 the level of the bookmark.
154 --]]
155 local function describe (buffer, num)
156 local l = buffer[num]
157 if not match (l, "%[.-%]%s*$") then
158 l = l .. " []"
159 end
160 local le = match(l, ">>") and 4 or 3
161 buffer[num] = gsub(l, ">+%s+(.-)%s+%[(.-)%]",
162 [[\describe{%1}{%2}{]] .. le .. "}")
163 end
164 add_pattern{
165 pattern = "^>+%s+",
166 call = describe
167 }
168
169 --[[
170 Here's how multiline verbatim is handled; in the source it is simply marked by
171 indenting the line with ten spaces; thus code is easily spotted when reading
172 the source without useless and annoying "<code>"/"</code>" or anything similar
173 to mark it. To be properly processed by TeX, the code should be surrounded by
174 "\verbatim" and "\verbatim/" (my way of signalling blocks). Those must be on
175 their own lines, so we insert a line at the beginning and at the end of the
176 paragraph: for the closing "\verbatim/", we can simply replace the last line
177 of the paragraph, which is the boundary line, unless we're at the end of the
178 file. But for the opening "\verbatim" a line must be added at the beginning of
179 the paragraph; thus line numbers in the original source file and in its
180 processed version don't match anymore, and this might be annoying when TeX
181 reports erros. Besides, blank verbatim lines aren't handled correctly and
182 create a new verbatim block instead. So this way of marking verbatim material
183 is good for small documents, but explicit marking is cleaner and more
184 powerful (albeit not so good-looking in the source file).
185
186 Note that the verbatim pattern belongs to class 2 and the entire paragraph is
187 protected, so Interpreter leaves it alone afterward (remember the default
188 class is 3). Of course, the first ten space characters are removed.
189 --]]
190 local function verbatim (buffer)
191 for n, l in ipairs(buffer) do
192 buffer[n] = gsub(l, "%s%s%s%s%s%s%s%s%s%s","", 1)
193 end
194 table.insert(buffer, 1, [[\verbatim]])
195 if gsub(buffer[#buffer],
196 interpreter.paragraph, "") == "" then
197 buffer[#buffer] = [[\verbatim/]]
198 else
199 table.insert(buffer, [[\verbatim/]])
200 end
201 interpreter.protect()
202 end
203 add_pattern{
204 pattern = "^%s%s%s%s%s%s%s%s%s%s",
205 call = verbatim,
206 class = 2
207 }
208
209 --[[
210 And now comes the fun part. I wanted "i-doc.lua" to be self-describing. The
211 source of what you're reading right now isn't "interpreter-doc.txt", but
212 "i-doc.lua" itself input in the latter file with
213
214 \intepreterfile{doc}{i-doc.lua}
215
216 How should code and comment be organized in "i-doc.lua"? Well, there is little
217 choice, since the file is a normal Lua file: comment lines should be prefixed
218 with "--" or surrounded with
219 \tcode{--[{}[} and \tcode{--]{}]}. % Sorry for the braces, I can't nest Lua comments!
220 I chose the latter option, which is simpler. But normal code should also be
221 typeset as verbatim material; I could have begun all lines with ten spaces,
222 but that would have seemed strange. Instead, \tcode{--]{}]} is turned into
223 "\source" and "\source/" is added at the end of the paragraph ("\source" is
224 just "\verbatim" with a different layout). Which means all paragraphs have the
225 same structure: comments between
226 \tcode{--[{}[} and \tcode{--]{}]}
227 and code immediately following (\tcode{--[{}[} is simply removed). The pattern
228 is in class 1 and the paragraph is protected, so that lines indented with ten
229 spaces or more aren't touched by the previous verbatim pattern (in class 2).
230 --]]
231 local function autoverbatim (buffer, line)
232 buffer[line] = [[\source]]
233 for n = line + 1, #buffer do
234 interpreter.protect(n)
235 end
236 if gsub(buffer[#buffer],
237 interpreter.paragraph, "") == "" then
238 buffer[#buffer] = [[\source/]]
239 else
240 table.insert(buffer, [[\source/]])
241 end
242 end
243 add_pattern{
244 pattern = nomagic"%^--]]",
245 call = autoverbatim,
246 class = 1
247 }
248 local function remove_comment ()
249 return ""
250 end
251 add_pattern{
252 pattern = nomagic"%^--[[",
253 replace = remove_comment
254 }