diff options
author | Karl Berry <karl@freefriends.org> | 2011-08-03 22:44:16 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2011-08-03 22:44:16 +0000 |
commit | 91657def4de77bdba974dff0de99882f8e349120 (patch) | |
tree | 6cc8c768ee30e3ffcdeea8bdd49250a299923591 /Master/texmf-dist/scripts/interpreter/i-doc.lua | |
parent | dddd7485ffb2ffd0fd906fce49bb136d9bcc747f (diff) |
interpreter.lua under tex/luatex per author preference
git-svn-id: svn://tug.org/texlive/trunk@23399 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/scripts/interpreter/i-doc.lua')
-rwxr-xr-x | Master/texmf-dist/scripts/interpreter/i-doc.lua | 253 |
1 files changed, 0 insertions, 253 deletions
diff --git a/Master/texmf-dist/scripts/interpreter/i-doc.lua b/Master/texmf-dist/scripts/interpreter/i-doc.lua deleted file mode 100755 index b8b3c106a46..00000000000 --- a/Master/texmf-dist/scripts/interpreter/i-doc.lua +++ /dev/null @@ -1,253 +0,0 @@ ---[[ -Here's a description of "i-doc.lua", the file containing the interpretation -used for Interpreter's documentation. Remember that none of the TeX macros -used here is defined by Interpreter; instead, they are my own and should be -adapted if necessary. Also several options taken here are far from optimal but -are convenient examples. - -Shorthands for often used functions. ---]] -local gsub, match = string.gsub, string.match -local add_pattern = interpreter.add_pattern -local nomagic = interpreter.nomagic - ---[[ -Class 1 and 2 will be used for verbatim (thus protecting) and ``normal'' -patterns go into class 3 or higher. ---]] -interpreter.default_class = 3 - ---[[ -The reader might have observed that "interpreter-doc.txt" begins with a table -of contents. This table is useful for the source file only, and isn't typeset -by TeX, because the following pattern suppresses it: the entire paragraph -containing "TABLE OF CONTENTS" on a line of its own is deleted. Protecting the -paragraph is useless, but it makes things a little bit faster because the -paragraph won't be pointlessly searched for other patterns. ---]] -local function contents (buffer) - for n in ipairs(buffer) do - buffer[n] = "" - end - interpreter.protect() -end -add_pattern{ - pattern = "^%s*TABLE OF CONTENTS%s*$", - call = contents, - class = 1 -} - ---[[ -Sections headers are typeset as - - ====================================== section_tag - === Section title ==================== - ====================================== - -The first and third line are decorations and they are removed. The -"section_tag" is meant for the source only again (linking the section to the table -of contents). I could have used it to create PDF destinations, but that seemed -unnecessary in such a small file. The associated pattern is: at least four -equals signs. ---]] -add_pattern{ - pattern = "^====+.*", - replace = "" -} - ---[[ -The middle line is spotted with the tree equals sign at the beginning of the -line (the previous pattern being longer, the decoration lines have been -already removed and they won't be taken for section titles). The signs are -removed and replaced with "\section{" and "}". ---]] -local function section (buffer, num) - local l = buffer[num] - l = gsub(l, "^===%s*", "\\section{") - l = gsub(l, "%s*=+%s*", "}") - buffer[num] = l -end -add_pattern{ - pattern = "^===", - call = section -} - ---[[ -The following pattern simply turns "Interpreter" into "\ital{Interpreter}". The -meaning of the "\ital" command is obvious, I suppose. Note the offset: -starting at the backslash, this leads to the _n_ in Interpreter, thus avoiding -matching the pattern again. The Lua notation with double square brackets is -used for strings with no escape character (hence "\ital" and not "\\ital" as -would be necessary with a simple string). ---]] -add_pattern{ - pattern = "Interpreter", - replace = [[\ital{Interpreter}]], - offset = 7 -} - ---[[ -Turning "TeX" into TeX. This illustrates the use of a function as "replace"; -the point is that "\TeX" should be suffixed with a space if initially followed -by anything but a space or end of line (so as not to form a control sequence -with the following letters), and it should be suffixed with a control space if -initially followed by a space or end of line (so as to avoid gobbling the -space). So the function checks the second capture. Note that simply replacing -"TeX" with "\TeX{}" would be much simpler, but less instructive! ---]] -local function maketex (tex, next) - if next == " " or next == "" then - return [[\TeX\ ]] - else - return [[\TeX ]] .. next - end -end -add_pattern{ - pattern = "(TeX)(.?)", - replace = maketex, - offset = 2 -} - ---[[ -The following turns "<text>" into <text> and "_text_" into _text_. Setting a -class just so the patterns inherit the "nomagic" feature is of course an -overkill, but that's an example. ---]] -interpreter.set_class(4, {nomagic = true}) -add_pattern{ - pattern = "<...>", - replace = [[\arg{%1}]], - class = 4 -} -add_pattern{ - pattern = "_..._", - replace = [[\ital{%1}]], - class = 4 } - ---[[ -I use double quotes as protectors; they are replaced with a "\verb" command at -the very end of the processing (with class 0). ---]] -interpreter.protector('"') -add_pattern{ - pattern = nomagic'"..."', - replace = [[\verb`%1`]], - class = 0 -} - ---[[ -The description of functions (in red in the PDF file) are handled with the -"\describe" macro, which takes the function as its first argument and -additional information as its second one (typeset in italics in the PDF file). -In the source, it is simply marked as - - > function (arguments) [Additional information] - -with "[Additional information]" sometimes missing (i.e. there is no empty -pairs of square brackets). Descriptions of entries in pattern tables follows -the same syntax, except the line begins with ">>". So the pattern first spots -lines beginning with ">[>]" followed by at least one space, adds an empty pair of -brackets at the end if there isn't any, and turn the whole into "\describe". -The number of ">" symbols sets "\describe"'s third argument, which specifies -the level of the bookmark. ---]] -local function describe (buffer, num) - local l = buffer[num] - if not match (l, "%[.-%]%s*$") then - l = l .. " []" - end - local le = match(l, ">>") and 4 or 3 - buffer[num] = gsub(l, ">+%s+(.-)%s+%[(.-)%]", - [[\describe{%1}{%2}{]] .. le .. "}") -end -add_pattern{ - pattern = "^>+%s+", - call = describe -} - ---[[ -Here's how multiline verbatim is handled; in the source it is simply marked by -indenting the line with ten spaces; thus code is easily spotted when reading -the source without useless and annoying "<code>"/"</code>" or anything similar -to mark it. To be properly processed by TeX, the code should be surrounded by -"\verbatim" and "\verbatim/" (my way of signalling blocks). Those must be on -their own lines, so we insert a line at the beginning and at the end of the -paragraph: for the closing "\verbatim/", we can simply replace the last line -of the paragraph, which is the boundary line, unless we're at the end of the -file. But for the opening "\verbatim" a line must be added at the beginning of -the paragraph; thus line numbers in the original source file and in its -processed version don't match anymore, and this might be annoying when TeX -reports erros. Besides, blank verbatim lines aren't handled correctly and -create a new verbatim block instead. So this way of marking verbatim material -is good for small documents, but explicit marking is cleaner and more -powerful (albeit not so good-looking in the source file). - -Note that the verbatim pattern belongs to class 2 and the entire paragraph is -protected, so Interpreter leaves it alone afterward (remember the default -class is 3). Of course, the first ten space characters are removed. ---]] -local function verbatim (buffer) - for n, l in ipairs(buffer) do - buffer[n] = gsub(l, "%s%s%s%s%s%s%s%s%s%s","") - end - table.insert(buffer, 1, [[\verbatim]]) - if gsub(buffer[#buffer], - interpreter.paragraph, "") == "" then - buffer[#buffer] = [[\verbatim/]] - else - table.insert(buffer, [[\verbatim/]]) - end - interpreter.protect() -end -add_pattern{ - pattern = "^%s%s%s%s%s%s%s%s%s%s", - call = verbatim, - class = 2 -} - ---[[ -And now comes the fun part. I wanted "i-doc.lua" to be self-describing. The -source of what you're reading right now isn't "interpreter-doc.txt", but -"i-doc.lua" itself input in the latter file with - - \intepreterfile{doc}{i-doc.lua} - -How should code and comment be organized in "i-doc.lua"? Well, there is little -choice, since the file is a normal Lua file: comment lines should be prefixed -with "--" or surrounded with -\tcode{--[{}[} and \tcode{--]{}]}. % Sorry for the braces, I can't nest Lua comments! -I chose the latter option, which is simpler. But normal code should also be -typeset as verbatim material; I could have begun all lines with ten spaces, -but that would have seemed strange. Instead, \tcode{--]{}]} is turned into -"\source" and "\source/" is added at the end of the paragraph ("\source" is -just "\verbatim" with a different layout). Which means all paragraphs have the -same structure: comments between -\tcode{--[{}[} and \tcode{--]{}]} -and code immediately following (\tcode{--[{}[} is simply removed). The pattern -is in class 1 and the paragraph is protected, so that lines indented with ten -spaces or more aren't touched by the previous verbatim pattern (in class 2). ---]] -local function autoverbatim (buffer, line) - buffer[line] = [[\source]] - for n = line + 1, #buffer do - interpreter.protect(n) - end - if gsub(buffer[#buffer], - interpreter.paragraph, "") == "" then - buffer[#buffer] = [[\source/]] - else - table.insert(buffer, [[\source/]]) - end -end -add_pattern{ - pattern = nomagic"%^--]]", - call = autoverbatim, - class = 1 -} -local function test () - return "" -end -add_pattern{ - pattern = nomagic"%^--[[", - replace = test, -} |