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 : Sets to call the font described in ; all defaults to the values of the !metafont parameter. If 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 Typesets in italics. \bold Typesets in bold. \scap Typesets in small caps. \rom Typesets in roman. \emph Typesets in italics or roman, depending on whether the current font is roman or italics, respectively. \underline Underlines . 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 Typesets with , 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 Creates a new section type with . This is not necessary to make \sectioncommand work with , but with it all declared sections of level larger than are reset (i.e. their counters are set to 0). Sections with chapter, section, subsection and paragraph are already declared. \incrementsection Increments the counter of section . If hasn't been declared, a new is created, but without a level. \getsectioncounter Returns the value of section 's counter, or -1 if there is no section of that type. \sectioncommand <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.