Initial commit

1 files changed, 1057 insertions, 0 deletions

diff --git a/macros/plain/contrib/pitex/pitex-doc.txt b/macros/plain/contrib/pitex/pitex-doc.txt
new file mode 100644
index 0000000000..168e7e7b18
--- /dev/null
+++ b/macros/plain/contrib/pitex/pitex-doc.txt
@@ -0,0 +1,1057 @@
+Introduction
+============
+
+If you're reading this, either you saw "\input pitex" at the beginning
+of the documentation of one of my packages, or you spend desperate hours
+browsing CTAN, or you're Arnaud Schmittbuhl. In any case, you're welcome
+to use the PiTeX macros, provided that you don't forget that: nothing
+is guaranteed; changes might occur without warning nor retrocompatibility;
+the documentation isn't necessarily up-to-date; and, if you still want
+to, you must load PiTeX with "\input pitex" on top of plain TeX, using
+LuaTeX.
+
+What is PiTeX? Originally, it was a set of files I loaded with plain TeX
+to typeset documentation for my packages. But it's not just a few macros
+anymore, but rather a format in progress. The format might never see the
+public light, but if it does, its originality (compared to existing
+format) will be an organization based on the Gates package: everything
+will be highly customizable, not because there are tons of options
+(although that can be the case too), but because big operations are
+divided into gates, i.e. macros with a handle that you can control without
+having to rewrite (nor understand) the big operation you're modifying;
+which big operation also keeps its integrity, because removing or adding
+something is neatly done. It also means that PiTeX can be changed
+piecewise, and made into something that bears little resemblance to the
+original code. In other words, there is nothing private, nothing forbidden.
+For the moment, only sectionning commands and the output routine, plus
+callback management in Lua and \everypar, are written with gates. See
+the Gates documentation for further information.
+
+Another thing with PiTeX is that it will rely heavily on external packages.
+There will be as little PiTeX-only code as possible. Rather, in line
+with Gates, each area will be independant code able to work with other
+formats. That is no simple task, though, and far from complete. For
+instance, the user's interface is made with YaX, which can be used (and
+is used) elsewhere.
+
+PiTeX uses three types of files: mandatory external packages, i.e.
+independant code that PiTeX can't do without, optional external packages,
+i.e. independant code that can be used, but is not automatically loaded,
+and mandatory PiTeX-only files. All mandatory files aren't necessary to
+the same degree, though, and in the future switches might be available
+to load only some of them. Currently, the files are:
+
+------------------------------------------------------------------
+|                **Mandatory external packages**                 |
+------------------------------------------------------------------
+| texapi    | Macros to write independant code.                  |
+| YaX       | User's interface (and convenient programming tool) |
+|           | with "key = value" style).                         |
+| Gates     | Overall architecture for modular code.             |
+| Navigator | PDF features (links, bookmarks...)                 |
+|           | Currently used by sections, but might become       |
+|           | non-mandatory (although strongly recommended).     |
+------------------------------------------------------------------
+
+---------------------------------------------------------------------------
+|                        **Mandatory PiTeX files**                        |
+---------------------------------------------------------------------------
+| pitex.tex            | The main file that inputs the other,             |
+|                      | and contains a few macros.                       |
+| lua.ptx              | Lua-related macros.                              |
+| base.ptxlua          | Lua functions, input in the previous file.       |
+| files.ptx            | Dealing with files.                              |
+| fonts.ptx            | Interface for fonts; relies on the next file.    |
+| fonts.ptxlua         | The Lua fontloader; should become independant    |
+|                      | some day.                                        |
+| foundry-settings.lua | Default settings for the fontloader.             |
+| sections.ptx         | Sectionning commands.                            |
+| blocks.ptx           | Blocks (delimited text with special formatting). |
+| references.ptx       | Labels and references.                           |
+| verbatim.ptx         | Typesetting verbatim material.                   |
+| inserts.ptx          | Footnotes and figures.                           |
+| output.ptx           | Page layout and output routine.                  |
+---------------------------------------------------------------------------
+
+The following can be used with PiTeX; actually I only list the packages
+I've written, but anything working with plain TeX (e.g. TikZ) works with
+PiTeX.
+
+----------------------------------------------------------------------------
+|                      **Optional external packages**                      |
+----------------------------------------------------------------------------
+| Librarian   | To create bibliographies without BibTeX.                   |
+| Lecturer    | For screen presentations.                                  |
+| Interpreter | To write text with non-TeX markup (as this documentation); |
+|             | Interpreter does the conversion on the fly.                |
+----------------------------------------------------------------------------
+
+The PiTeX distribution also contains "i-pitex.lua", an interpretation
+file for Interpreter used to typeset documentations, like the one you
+are currently reading. Which is why you can read it quite comfortably
+as a plain text file in a text editor (see "pitex-doc.txt").
+
+The rest of this document is a terse description of existing commands,
+parameters, and of course, gates.
+
+
+
+
+
+Fonts (fonts.ptx and fonts.ptxlua)
+==================================
+
+The fontloader uses gates, but only superficially. They won't be
+documented here.
+
+\setfont <command>:<attributes>
+Sets <command> to call the font described in <attributes>; all defaults
+to the values of the !metafont parameter. If <command> is \mainfont, the
+font is called at once. Also, \codefont is used in some places (e.g.
+verbatim).
+
+> name
+The family name of the font; e.g. Chaparral Pro for the main text of
+this document.
+
+> size (dimension)
+The size of the font.
+
+> small (dimension)
+The size of the font when \small is called. Can be a relative value by
+prefixing it with "-" or "+", in which case it is set relative to ?size.
+
+> verysmall (dimension)
+The size (possibly relative) for \verysmall.
+
+> big (dimension)
+The size (possibly relative) for \big.
+
+> verybig (dimension)
+The size (possibly relative) for \verybig.
+
+> bold (font modifier)
+The modifier used for the bold version of the font, without the leading slash;
+!metafont sets it to "Bold".
+
+> italic (font modifier)
+Same as !bold for the italic version; set to "Italic" by !metafont.
+
+> math (true or false)
+If true, math fonts will be created.
+
+> features
+Well, err, font features...
+
+> slant (angle)
+The slant applied to the font to create a fake italic.
+
+> slantsc (angle)
+The slant applied to the font to create fake italic smallcaps; if not
+given, defaults to ?slant.
+
+There's actually much more going under the hood, but "font.ptxlua" (the
+font loader itself) is a work in progress, and undocumented.
+
+The same macros as in plain TeX can be used, except they're cumulative,
+i.e. "\it\bf" switches to a bold italic.
+
+\it
+Switches to italics.
+
+\rm
+Switches to roman.
+
+\bf
+Switches to bold.
+
+\rg
+Switches to regular weight.
+
+\sc
+Switches to small capitals.
+
+\lc
+Switches to lower case (i.e. not small caps).
+
+\ital <text>
+Typesets <text> in italics.
+
+\bold <text>
+Typesets <text> in bold.
+
+\scap <text>
+Typesets <text> in small caps.
+
+\rom <text>
+Typesets <text> in roman.
+
+\emph <text>
+Typesets <text> in italics or roman, depending on whether the current
+font is roman or italics, respectively.
+
+\underline <text>
+Underlines <text>. Wow.
+
+\small
+Switches to small font.
+
+\verysmall
+Switches to very small font.
+
+\big
+Switches to big font.
+
+\verybig
+Got it?
+
+\normalsize
+Switches to default size.
+
+\smaller
+Switches to the font smaller than the current one (e.g. \normalsize if
+you're currently using \big).
+
+\bigger
+Same as \smaller, the other way around.
+
+\color <color><text>
+Typesets <text> with <color>, which should be a triplet "R G B" with
+each value between 0 and 1.
+
+
+
+
+
+Sections (sections.ptx)
+=======================
+
+Sections are among the victims of my fanaticism for grid-typesetting.
+
+
+
+  Main sectioning commands
+  ~~~~~~~~~~~~~~~~~~~~~~~~
+
+\declaresection <type><level>
+Creates a new section type with <level>. This is not necessary to make
+\sectioncommand work with <type>, but with it all declared sections of
+level larger than <level> are reset (i.e. their counters are set to 0).
+Sections with <type> chapter, section, subsection and paragraph are
+already declared.
+
+\incrementsection <type>
+Increments the counter of section <type>. If <type> hasn't been declared,
+a new <type> is created, but without a level.
+
+\getsectioncounter <type>
+Returns the value of section <type>'s counter, or -1 if there is no
+section of that type.
+
+\sectioncommand <type><title><alternate title>[<label>]
+Creates a section heading of type <type> with <title>. See the details
+of the gates involved below. The <type> refers to the parameter of the
+same name. The <alternate title> is very likely to disappear.
+
+\chapter <title>[<label>]
+Equivalent to \sectioncommand{chapter}{<title>}{<title>}[<label>].
+
+\section <title>[<label>]
+Equivalent to \sectioncommand{section}{<title>}{<title>}[<label>].
+
+\subsection <title>[<label>]
+Equivalent to \sectioncommand{subsection}{<title>}{<title>}[<label>].
+
+\paragraph <title>[<label>]
+Equivalent to \sectioncommand{paragraph}{<title>}{<title>}[<label>].
+
+\ifsectiontitle
+A conditional that is true when the section title is being typeset (sets by
+the section_pre gate below.
+
+\sectioninfile <optional star><title><space><type><space><file><space>
+Creates a section with the contents of a file, unless there's an optional
+star (useful to typeset only parts of a big document); <title> is a
+\freedef argument, hence it can be given between braces, double quotes
+or slashes (but the <space> is nonetheless mandatory); <type> is a section
+type, and <file> is a file to be input: it shouldn't have an extension
+(tex files are searched), but it can be a path with "/" as a separator.
+A \label is also created, with the tail of <file> as its argument. In
+other words, the following:
+
+          \sectioninfile "A chapter" chapter mydir/myfile
+
+is equivalent to:
+
+          \chapter{A chapter}
+          \label{myfile}
+          \input mydir/myfile.tex
+
+The \sectioncommand macro only contains a list gate, "section", itself
+containing the gates typesetting a section heading; all the gates belong
+to the "Section" family associated with the \Section command. Here are
+all the gates involved; the first number between parentheses indicates
+how many arguments the gate should receive, the second how many it
+returns.
+
+-------------------------------------------------------------------------------
+| section | (4, 0) | section_break     | (1, 0) | section_vmode      | (1, 0) |
+|         |        |                   |        | section_clearpage  | (1, 0) |
+|         |        |                   |        | section_beforeskip | (1, 0) |
+|         |        | section_advance   | (1, 0) |                    |        |
+|         |        | section_advance   | (1, 0) |                    |        |
+|         |        | section_bookmark  | (4, 0) |                    |        |
+|         |        | section_toc       | (3, 0) |                    |        |
+|         |        | section_pre       | (0, 0) |                    |        |
+|         |        | section_typeset   | (2, 2) | section_number     | (2, 3) |
+|         |        |                   |        | section_heading    | (3, 2) |
+|         |        |                   |        | section_addfont    | (2, 2) |
+|         |        |                   |        | section_addcolor   | (2, 2) |
+|         |        |                   |        | section_do         | (2, 0) |
+|         |        | section_post      | (0, 0) |                    |        |
+|         |        | section_afterskip | (1, 0) |                    |        |
+-------------------------------------------------------------------------------
+
+Here's how the gates work:
+
+> section <type><title><alternate title><label>
+The main list gate that contains all sections. In what follows, when I
+mention an attribute, I mean the attribute of the parameter <type>.
+
+> section_break <type>
+An l-gate managing whatever must happen before the section title is
+typeset.
+
+> section_vmode <type>
+Inserts a \par and removes last skip. (Conditional: ?vmode is =true.)
+
+> section_clear <type>
+Inserts a \clearpage. (Conditional: ?clear is =true.)
+
+> section_beforeskip <type>
+Creates a vertical skip before the heading. If the current page cannot
+accommodate ?beforeskip + ?minimum + ?afterskip worth of lines, then
+the section heading is typeset on the next page (using \breakpage). If
+the current page can accommodate the section, a skip of ?beforeskip
+lines is inserted. The gate doesn't return anything. (Conditional:
+?clear is not =true.)
+
+> section_advance <type>
+Increments the section counter, and resets the counters of those sections
+whose level is larger than <type>'s level (provided <type> has been
+declared with \declaresection and thus given a level). The gate doesn't
+return anything.
+
+> section_bookmark <type><title><alternate title><label>
+The bookmark is created with Navigator's \outline command as follows:
+
+          \outline[meta = <type>bookmark]{<bookmarklevel>}[<label>]{<alternate title>}
+
+only if ?bookmarklevel is defined. For types chapter, section, subsection
+and paragraph, the related !chapterbookmark, !sectionbookmark,
+!subsectionbookmark and !paragraphbookmark parameters are predefined,
+with simply ?meta set to =navigator. The <alternate title> is likely
+to disappear, since Navigator can handle things correctly. The gate
+doesn't return anything. (Conditional: ?link is =true.)
+
+> section_toc <type><title><alternate title>
+Writes what should be written to the auxiliary file for the next run
+to produce a table of contents. The gate doesn't return anything.
+(Conditional: ?toc is =true.)
+
+> section_pre
+Prepares the typesetting: open a group, sets \maintextfalse and
+\sectiontitletrue, and sets a LuaTeX attribute to 0 (so the section title
+is marked and can be spotted in the output routine). The gates doesn't
+return anything.
+
+> section_typeset <type><title>
+A list gate containing the gates used to typeset the section heading.
+It returns its final two arguments if only because list gate automatically
+return. See description below.
+
+> section_post
+Closes the group opened in section_pre. The gate doesn't return anything.
+
+> section_afterskip <type>
+Creates a vertical skip of ?afterskip lines. Also, calls \removenextindent
+if ?removenextindent is =true. The gate doesn't return anything.
+(Conditional: ?inline is not =true.)
+
+Here are the gates contained in section_pre. Beware, there the nature
+of the passed arguments slightly changes.
+
+> section_indent <type>
+Goes into horizontal mode and inserts an indent of width ?indent. The
+gate doesn't return anything.
+
+> section_number <type><title>
+Sets the section number, if ?number isn't =none. The number is surrounded
+by ?beforenumber and ?afternumber, converted to roman or arabic number
+according to the value of ?number, and the whole is passed to ?numbercommand
+(if it exists). The gate returns the following three arguments:
+<type><number><title>, where <number> is what's just been described.
+
+> section_heading <type><number><title>
+Sets the <title>: it is prefixed with <number>, passed to ?function if
+it exists, and suffixed with ?aftertitle if any. The gate returns <type>
+and <title> as just described.
+
+> section_addfont <type><title>
+Prefixes <title> with the value of font and returns its two arguments.
+
+> section_addcolor <type><title>
+Adds color to the title and returns its two arguments. (Conditional:
+?color is =true.)
+
+> section_do <type><title>
+At last! Inserts an horizontal skip of width ?indent, typesets <title>,
+and if ?inline isn't =true, sets \rightskip to ?ragged. Oh, yes, this
+could be divided into smaller gates. The gates doesn't return anything.
+
+The relevant parameters are the one corresponding to the type of the
+section, i.e. !chapter, !section, !subsection, !paragraph, which all
+have !metasection as their meta-parameter. The relevant attributes are:
+
+> vmode (true or false)
+If =true, goes into vertical mode before typesetting the heading.
+
+> clear (true or false)
+If =true, the section starts on a new page.
+
+> beforeskip (glue)
+The skip added before the heading.
+
+> afterskip (glue)
+The skip added after the heading.
+
+> minimum (number)
+The minimum number of lines that should be present on the page after the
+section heading. The "section_skip" gate above starts a new page if
+?beforeskip + ?afterskip + ?minimum can't be accommodated.
+
+> inline (true or false)
+If =true, the section heading is inserted at the beginning of the following
+paragraph.
+
+> number (arabic, roman or none)
+The way the section number should be typeset; =none means the number
+isn't typeset.
+
+> beforenumber
+Material to be added before the section number.
+
+> afternumber
+Material to be added after the section number.
+
+> numbercommand (control sequence)
+A macro to which the section number (surrounded by ?beforenumber and
+?afternumber) is passed.
+
+> function (control sequence)
+A macro to which the section title is passed.
+
+> aftertitle
+Material added after the section title.
+
+> font
+Font for the heading.
+
+> color (a triplet of values)
+Color for the heading.
+
+> indent (glue)
+The value of the glue added before the section title.
+
+> ragged (glue)
+The value of \rightskip for the heading.
+
+> toc (true or false)
+Sets whether the section should be added to the table of contents or
+not.
+
+> removenextindent (true or false)
+Sets whether the next paragraph should be unindented.
+
+> link (true or false)
+Sets whether a bookmark should be created with the section's title.
+
+> bookmarklevel (number)
+The level of the bookmark created for the section (how surprising).
+Further specification of the bookmark is done with !chapterbookmark,
+!sectionbookmark, !subsectionbookmark, !paragraphbookmark, whose only
+specification is that ?meta is set to =navigator. New "<type>bookmark"'s
+can be created, of course. See the documentation of Navigator for advanced
+use.
+
+
+
+  Various commands
+  ~~~~~~~~~~~~~~~~
+
+\tableofcontents
+Writes the table of contents (needs two runs). Not customizable for the
+time being!
+
+\newbreakpenalty <command>
+Defines <command> as a number below "-10000", suffixed with a \relax.
+The idea is to use it to break a page and check it in the output routine.
+
+\clearpage
+Fills the rest of the page with white space.
+
+\clearpagepenalty
+Penalty associated with \clearpage.
+
+\breakpage
+Same as \clearpage. They shouldn't be used for the same reasons. I use
+\clearpage at the end of a chapter, and \breakpage elsewhere (e.g. when
+a section heading would be orphaned and must move to the next page). The
+latter triggers nothing special, but the former can be identified in the
+output routine and for instance suppress footers.
+
+\breakpagepenalty
+Penalty associated with \breakpage.
+
+\needspace <dimen>
+Moves to the next page if there's less than <dimen>.
+
+\iflines <number><true><false>
+Executes <true> if there's at least <number> lines left on the page, and
+<false> otherwise.
+
+\ignorepars <material>
+Ignores incoming \par commands (and spaces too) and executes <material>.
+Useful when a blank line looks good in the source but you don't want it
+to signal a paragraph's end. The command is used by sectionning commands,
+so that if the section's title is supposed to be inserted at the beginning
+of the next paragraph (e.g. if ?inline is =true), you can nonetheless
+leave a blank line after the command.
+
+
+
+References (references.ptx)
+===========================
+
+There is a nice reference system, but it is a mess and should be rewritten
+in Lua. So it isn't fully described here.
+
+\label <name>
+Sets a label with <name>.
+
+\ref [<pre>][<post>] <reference type> {<name>}
+Makes a reference. Beware of the syntax: label should be enclosed between
+braces, because the left brace is the delimiter for <reference name>,
+which in turn should be enclosed in braces. E.g. a call is:
+
+          \ref page {mylabel}
+
+What is returned depends on <reference type>. If it is empty, then what
+is returned is the value of \ptx@label when \label{<name>} was issued.
+I think some commands define \ptx@label (nice in blocks, for instance).
+Otherwise, <reference type> can be page, chapter, section, subsection,
+paragraph or footnote (the latter if and only if \label was issued in a
+footnote). The returned text is prefixed with <pre> and suffixed with
+<post>.
+
+Also, if <reference type> is page, it may take three runs to make things
+work, because it is checked whether the returned value is the current
+page, in which case nothing is printed (it's stupid to refer to the
+current page). As mentioned above, this is a mess.
+
+There also are commands like "\sref{label}" and the like, which are
+shorthands for e.g. "\ref[ section~][] section {label}".
+
+
+
+
+
+Blocks (blocks.ptx)
+===================
+
+
+Blocks are what are called environments elsewhere: they mark up a section
+of the document, and generally apply some special operations. Given a
+block myblock, it is launched with "\myblock", closed with "\myblock/"
+and continued with "\myblock|". As you might imagine, this implies poking
+at the next token, which in some rare case might be troublesome; hence,
+\myblock can be followed by an optional ">" whose only goal is to protect
+the next token. (You can also use a \relax, of course.)
+
+\newblock <optional star><command><pre><optional start><optional middle><post>
+Defines <command> as a block. If the first optional star is present, the
+block is executed inside a group. If the second optional star is present,
+then the <middle> argument should be present too. The block is defined
+as follow: <pre> is executed at the beginning (i.e. "\myblock" or
+"\myblock>"), <middle> is executed when the block is continued (i.e.
+"\myblock|"), and <post> is executed when the block is closed (i.e.
+"\myblock/"). If <middle> is not given, then "\myblock|" does nothing.
+For instance, the following defines a grouped block (so the \rightskip
+setting doesn't affect the rest of the document); note the \par at the
+end, so the paragraph is built before the group is closed:
+
+          \newblock*\raggedblock{\rightskip=0pt plus 1fil\relax}{\par}
+
+And here's a simple example with a middle part:
+
+          \newblock\listblock{\vskip\baselineskip-- }
+                            *{\par-- }
+                             {\vskip\baselineskip}
+
+The continuation part can be used as a partial block opening: some markers
+are repeated (the dash) others are not (the vertical space).
+
+\newblocktype <command><pre><middle><post>
+Defines <command> as a block definition command like \newblock with
+<pre>, <middle> and <post> to be executed by default before the user-supplied
+versions. The \newblock command itself has been thus defined, with empty
+arguments. Arguments, after:
+
+          \newblocktype\newlist{\vskip\baselineskip--}
+                               {\par--}
+                               {\vskip\baselineskip}
+
+Then \newlist\listblock{}{} will have the same definition as in the
+previous example (no need to supply a <middle> part, it's in the default),
+and a variation can be created.
+
+\removenextindent
+Removes the indentation box of the next paragraph (used by section
+macros). Technically, it sets ajar the "noindent" gate in the "everypar"
+gate list (itself registered in the \everypar token list, which shouldn't
+be handled otherwise if flexibility is to be ensured). Those two gates
+belong to the "Everypar" family associated with the \Everypar command.
+
+\Indent
+Indents the next paragraph even if it \removenextindent has been issued
+(a \kern is added).
+
+
+
+
+
+
+Dealing with files (files.ptx)
+==============================
+
+\iffile [<format>]<file><true><false>
+Executes <true> if "kpse.find_file" (from the LuaTeX "kpse" library,
+implementing "kpathsea") with file type <format> (default: "tex"), and
+<false> otherwise.
+
+\ifffile [<format>]<file><true>
+Same as \iffile, except nothing happens when the file isn't found. Yes,
+three *f*'s.
+
+\inputfileor [<format>]<file><no file>
+Reads file <file> or executes <no file>.
+
+\writeout <optional star><general text>
+Writes <general text> to the auxilary file that is read at the beginning
+of each job. Without a star, writing happens at once (it's \immediate),
+with it writing is delayed until the current page is shipped out.
+
+
+
+
+
+Verbatim (verbatim.ptx)
+=======================
+
+\verbcatcodes
+A catcode table with usual verbatim catcodes: special characters have
+catcode 12, except space and end-of-line, which have catcode 13 and are
+defined to \quitvmode\spacecs and \quitvmode\par by default.
+
+\newverbatim <command>[<catcode table>]<pre><post>
+Defines a new block <command> with <catcode table>, <pre> at the beginning
+and <post> at the end. If <catcode table> is missing, \verbcatcodes is
+used. Verbatim blocks work as follows: first, there is no continuation
+command, i.e. only "\myverbatimblock" and "\myverbatimblock/" are allowed,
+not "\myverbatimblock|" (it might exist somewhere in the future). Second,
+the block opening takes one optional argument between brackets, which
+is the name of the verbatim block. Third, <pre> is executed at the
+beginning, and <post> at the end, as defined with \newverbatim. Fourth,
+the end statement "\myverbatimblock/" should be on a line of its own.
+What a verbatim block does is the following (not taking into account
+what <pre> and <post> execute): it stores its contents as is, along with
+the <catcode table> the block was declared with, and that's it. Then
+come the following two functions.
+
+\doverbatim [<name>]
+Executes the contents of <name> (with the current catcode regime). If
+name is missing, last is used, a special name which refers to the last
+verbatim block.
+
+\printverbatim [<name>]
+Executes the contents of <name> (or last if <name> is missing) with the
+catcode table associated with the block <name> was stored with. Since
+that catcode table is \verbcatcodes by default, it generally results in
+the contents being typeset.
+
+As an example:
+
+          \newverbatim\myverbatim{\vskip\baselineskip}
+          {\printverbatim\vskip\baselineskip}
+          \myverbatim[example]
+          \def\foo{hello !}%
+          \foo
+          \myverbatim/
+          And now we are going to print: \doverbatim[example].
+
+\verbatim
+A predefined verbatim block, designed as follows:
+
+          \newverbatim\verbatim{\codefont\parindent0pt}
+                               {\vskip\baselineskip\printverbatim\relax
+                                \vskip\baselineskip\removenextindent}
+
+I.e. it switches to the console-like font, sets the paragraph indentation
+to nothing, prints its contents between two blank lines and removes the
+indentation of the paragraph to follow.
+
+Each verbatim block adds a table to the Lua table "pitex.verbatims" (yes,
+with an *s*); the key is the block's name, and the value is a table with
+lines as values, indexed by numbers, plus a "regime" key which returns
+the catcode table's number of the block. For instance, the core operation
+performed by "\printverbatim[<name>]" is:
+
+          tex.print(pitex.verbatims[<name>].regime, pitex.verbatims[<name>])
+
+
+
+
+
+Insertions (inserts.ptx)
+========================
+
+Insertions are still a mess, and not related to parameters. Yet you can
+use:
+
+\footnote <text>
+Typesets <text> in a footnote. How astounding.
+
+\figure [<title>]
+A block creating a figure with title <title>.
+
+\table [<title>]
+The same as <figure>, except "Table" will be used instead of "Fig" in
+the caption.
+
+\infigure
+Ablock creating a figure in the main text, i.e. between paragraphs.
+
+
+
+
+Layout and output routine (output.ptx)
+=====================================
+
+The page layout can be specified with the !page parameter, whose attributes
+are:
+
+> width (dimension)
+The width of the page.
+
+> height (dimension)
+The height of the page.
+
+> baselineskip (glue)
+The baseline distance.
+
+> topskip (glue)
+The distance between the top of the textblock and the first baseline.
+
+> top (dimension)
+The height of the upper margin.
+
+> lines
+The number of lines on a page.
+
+> hsize (dimension)
+The width of the textblock.
+
+> left (dimension)
+Width of the left margin.
+
+> right (dimension)
+Width of the right margin. If specified, ?hsize is ignored and the
+texblock's width is set to ?width - ?left - ?right.
+
+> parindent (dimension)
+The width of the indentation.
+
+> parskip (glue)
+The glue between paragraphs.
+
+The output routine holds nothing very interesting for the moment. I
+used to redefine it for each job. Now it is set up with gates, but I
+haven't taken the time yet to make it really powerful. Plus I should
+rewrite everything in Lua as much as possible. Anyway, \output contains
+the "output" gate, from the "OutputRoutine" family associated with the
+\OutputRoutine command; the gates work as follows (passed arguments
+aren't indicated, because there isn't any; although someday perhaps the
+gates will pass a box between them, to be less dependant on \outputbox,
+which is used, by the way, instead of box 255, so any box register can
+be used):
+
+---------------------------------------------------------------
+| output | precheck  |                    |                   |
+|        | shipout   | processmarginalia  |                   |
+|        |           | inserts            | inserts_figures   |
+|        |           |                    | inserts_footnotes |
+|        |           | headers            |                   |
+|        |           | ship               |                   |
+|        |           | postship           |                   |
+---------------------------------------------------------------
+
+> output
+The main list gate, holding the following.
+
+> precheck
+Checks whether \outputpenalty is smaller than \widowpenalty. If not,
+\vsize is increased or decreased (if there are inserts) by \baselineskip,
+so that the widow is accommodated or a line is given to the next page.
+In any case, the output box is repassed to TeX with "\holdinginserts=0".
+The gate is then set to "skip", so it isn't executed again.
+
+> shipout
+A list gate containing gates to write the page. By default it is skipped,
+so it isn't executed when the previous gate is, and vice-versa.
+
+> processmarginalia
+Insert the marginal notes (see \marginnote below). Can be obviously
+removed if there are no such notes.
+
+> inserts
+An l-gate containing the following two m-gates.
+
+> inserts_figures
+Adds the figures. (Conditional: the box "\ptx@insert_figures" isn't
+empty.)
+
+> inserts_footnotes
+Adds the footnotes. (Conditional: the box "\ptx@insert_footnotes" isn't
+empty.)
+
+> headers
+Inserts headers or footers, i.e. page number, running title, etc.
+
+> ship
+Ships out the page.
+
+> postship
+Resets some stuff (set "output_shipout" back to "skip"), and increments
+the page number.
+
+And now a lonely command:
+
+\marginnote [options]<text>
+Produces a marginal note with <text>. Uses the attributes (font,
+baselineskip, hsize) of the !marginnote parameter, with the following
+attributes:
+
+> hsize (dimension)
+Width of the textblock in the note.
+
+> hpos (ff, fr, rf, rr)
+Justification of the text: flushed on both sides, ragged on the right,
+ragged on the left, ragged on both sides.
+
+> font
+Font used to typeset the note.
+
+> parindent (dimension)
+Paragraph indentation for the note.
+
+> side (left or right)
+Side of the note relative to the textblock. That should depend on whether
+the note is on an odd or even side, but for the moment that is not the
+case.
+
+> gap (dimension)
+Distance between the textblock and the note.
+
+
+
+
+
+Lua facilities (lua.ptx and base.ptxlua)
+========================================
+
+\inputluafile <file>
+Shorthand for \directlua{dofile(kpse.find_file(<file>))}.
+
+\luacatcodes
+A catcode table with Lua-convenient catcodes: "#", "~", "%" and the end
+of file "^^M" are set to catcode 12.
+
+\luacode
+A block to write Lua code with the catcodes above.
+
+Lua code in PiTeX is organized mostly in gates; "pitex" is a gate table
+associated with family "pitex", "pitex.callback" is another table
+associated with family "pitex.callback", and "pitex.misc" is a third
+table associated (how surprising) with family "pitex.misc". The
+division of labour isn't perfectly defined, to say the least.
+
+The "pitex" family holds general commands, namely:
+
+> pitex.log (<message>, ...)
+Writes a <message> formatted as "string.format(<message>, ...)"
+
+> pitex.error (<message>, ...)
+Same as the previous function, but less friendly.
+
+The "pitex.callback" family is concerned with callback management. It
+has one interesting function (well, a gate) devoted to handling functions
+in callbacks as gates:
+
+> pitex.callback.register (<callback>, <gate>)
+An l-gate is registered in the callback, with subgates added to it; the
+name of the l-gate is the same as the callback where it is registered
+(with the family prefix "pitex.callback" added when necessary). For
+instance the list gate containing functions to used in "process_input_buffer"
+is called "process_input_buffer". Ordinary you would add a subgate to
+such a callback with the "add" action:
+
+          pitex.callback.add ("mygate", "process_input_buffer")
+
+However, the l-gate associated with the callback isn't created by
+default, nor registered in the callback. This means that "add" above
+will fail miserably if "process_input_buffer" hasn't been created
+beforehand. This function is meant to circumvent that: if the l-gate
+exists, it boils down to "add"; otherwise it creates it and registers
+it in the callback, and then add the gate. Note that the syntax follows
+the original "callback.register" function, with the callback first and
+the function second, even though you're adding gates to l-gates, with
+the syntax of "add" being subgates first, l-gate second. To manage the
+gates, thus created, you can then rely on the original gate actions.
+
+So, when I say `gates "X" and "Y" are registered in callback "Z"', it
+means `gates "X" and "Z" are subgates of l-gate "pitex.callback:Z",
+itself registered in callback "Z"'; unless otherwise indicated, "X" and
+"Z" belong to the "pitex.callback" family.
+
+And here are the gates registered in callbacks: "process_input_buffer"
+contains "convert", which turns latin1 into UTF-8. Verbatim blocks also
+register "process_verbatim", which is removed when the block ends. The
+"kerning" callback contains "french_punctuation", meant to add thin
+space before some punctuation mark, and "original_kerning", which is
+just a gate version of the "node.kerning" function. In "post_linebreak_filter"
+you'll find "pitex.misc:underline", which deals with material to be
+underline and "pitex.misc:mark_lines", which marks lines where a margin
+note is to be added. Those last two gates should be rewritten as complex
+l-gates (they're just big functions for the moment) some day. If you
+neither underline nor use marginal notes, you can remove them.
+
+
+
+
+Things that didn't make it elsewhere (pitex.tex)
+================================================
+
+General properties of the document can be set with the !document parameter,
+with the following attributes (the !navigator parameter has a ?meta
+attribute set to !document, which is why you'll find attributes here
+used by Navigator):
+
+> author
+The author of the document.
+
+> title
+The title of the document.
+
+> pdftitle
+The title that Navigator will use for the document's properties (defaults
+to ?title).
+
+> date
+The date of the document
+
+> pdfdate
+The date that Navigator will use for the document's properties; should
+be a properly formatted PDF date (this corresponds to the ?date attribute
+in the !navigator parameter; note that ?pdfdate doesn't defaults to
+?date, because the latter is supposed to hold a readable date).
+
+> subject
+For the document's properties.
+
+> keywords
+Again, the properties.
+
+> mode (outlines, bookmarks, thumbs, thumbnails, attachments, files, oc)
+What should be displayed in the navigation bar when the document is
+opened. See the documentation to Navigator.
+
+> layout (onepage, onecolumn, twopage, twocolumn, twopage*, twocolumn*)
+How the document is displayed when opened. See the documentation of
+Navigator.
+
+\newattribute <command>
+Defines <command> as an attribute register.
+
+\unsetattribute <command>
+Unsets attribute <command>.
+
+\attributenumber <command>
+Returns the number of attribute register <command> (not its value; you
+get the value with \the; this is to pass to Lua).
+
+\freedef <command>{<definition>}
+Same as "\def\foo#1{...}", except <command> can take its argument between
+double quotes (°") or slahes (/), and of course as single token or
+brace-delimited.
+
+\ifmaintext
+Conditional that is true when in main text; inserts, section headings,
+etc., should turn it to false, and sets their own to true.
+
+\newcatcodetable <command><catcode settings>
+Defines <command> as a catcode table with <catcode settings>; the latter
+are "<list of characters> = catcode" pairs, separated by commas, like
+the argument of texapi's \setcatcodes.
+
+\texcatcodes
+A code catcode table with the traditional catcodes.
+
+\inputpitexfile <file><space>
+Inputs <file> unless the initialization script says otherwise. If <file>
+has no extension, ".ptx" is used.
+
+\antigobblespace
+Adds a space if the next character has catcode 11 or is an opening
+parenthesis. For instance, after "\def\tex{\TeX\antigobblespace}", you
+can type "\tex is typesetting program" without worrying for gobbled
+space. Note that only ASCII letters have catcode 11 by default (not
+accented characters).
+
+\strut <height><depth>
+Produces an invisible vertical rule with the specified dimensions.
+
+\colorbox [<dimensions>]<RGB color><text>
+Puts <text> in a colored box with background color <RGB color> (e.g.
+three space-separated numbers between 0 and 1) and with padding <dimensions>.
+If <dimensions> is missing, padding is done according to the \extraboxspace
+length. Otherwise, if <dimensions> contains one value, it is used on all
+side; if there are two values (separated by commas), the first is used
+for top and bottom padding, and the second for left and right padding;
+with three value, the third specifies bottom padding, and a fourth
+specifies left padding. Very unlikely to remain in its present state or
+to remain at all.
+
+\extraboxspace
+Default padding for the previous command.
+
+\og
+Produces an opening guillemet: "«" (character "0x00AB").
+
+\fg
+Produces a closing guillemet: "»" (character "0x00BB"). Uses \antigobblespace.
+
+\trace
+Sets \tracingcommands to 3 and \tracingmacros to 2.
+
+\untrace
+Sets \tracingcommands and \tracingmacros to 0.