interpreter.lua under tex/luatex per author preference

git-svn-id: svn://tug.org/texlive/trunk@23399 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 253 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/luatex/interpreter/i-doc.lua b/Master/texmf-dist/doc/luatex/interpreter/i-doc.lua
new file mode 100644
index 00000000000..b8b3c106a46
--- /dev/null
+++ b/Master/texmf-dist/doc/luatex/interpreter/i-doc.lua
@@ -0,0 +1,253 @@
+--[[
+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,
+}