| 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 |
} |