diff options
Diffstat (limited to 'Master/texmf-dist/doc/plain')
| -rw-r--r-- | Master/texmf-dist/doc/plain/pitex/README | 36 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/plain/pitex/foundry-settings.lua | 19 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/plain/pitex/i-pitex.lua | 163 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/plain/pitex/pitex-doc.pdf | bin | 0 -> 96941 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/plain/pitex/pitex-doc.tex | 106 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/plain/pitex/pitex-doc.txt | 1057 |
6 files changed, 1370 insertions, 11 deletions
diff --git a/Master/texmf-dist/doc/plain/pitex/README b/Master/texmf-dist/doc/plain/pitex/README index 0322fcdc5a3..13fd5c71927 100644 --- a/Master/texmf-dist/doc/plain/pitex/README +++ b/Master/texmf-dist/doc/plain/pitex/README @@ -3,22 +3,36 @@ typeset documentations for my packages (that's why it is archived on CTAN). Perhaps in the future, when this achieves some kind of -format-like completude, there'll be a documentation and -it'll be publicly announced. +format-like completude, it'll be publicly announced. In the +meanwhile, a documentation exists (pitex-doc.pdf, also readable +in a text editor as pitex-doc.txt). You can of course use those macros, but you are on your own, and the files will probably be modified without announcement. -The file is supposed to be \input on plain TeX with LuaTeX, at least v.0.6. - +The file is supposed to be \input on plain TeX with LuaTeX, at least v.0.7. The files needed are: -texapi.tex (an independent package) -yax.tex (an independent package) -fonts.ptx (piTeX font "management") -luaotfload.sty (an independent package (not by me)) -sections.ptx (piTeX sectionning commands) +texapi.tex (an independent package for programming) +yax.tex (an independent package for key=value interface) +gates.tex and gates.lua (an independant package for overall architecture) +navigator.tex (an independant package for PDF features) +lua.ptx and base.ptxlua (Lua side) +files.ptx (file management) +fonts.ptx, fonts.ptxlua and foundry-settings.lua + (fonts, should be independant some day; actually + fonts.ptxlua can be used independantly, but there is + no doc) +sections.ptx (sectionning commands) +blocks.ptx (text blocks) +references.ptx (labels and references) +verbatim.ptx (typesetting verbatim) +inserts.ptx (footnotes and figures, a mess, like most files here anyway) +output.ptx (output routine) + +The file i-pitex.lua is needed only to typeset the documentation +with the Interpreter package. -Date: July 2010. +Date: November 2011. -Licensing of these files is covered by LPPL.
\ No newline at end of file +Licensing of these files is covered by LPPL. diff --git a/Master/texmf-dist/doc/plain/pitex/foundry-settings.lua b/Master/texmf-dist/doc/plain/pitex/foundry-settings.lua new file mode 100644 index 00000000000..5c24caa9378 --- /dev/null +++ b/Master/texmf-dist/doc/plain/pitex/foundry-settings.lua @@ -0,0 +1,19 @@ +return { + + features = { + kern = true, + liga = true, + trep = true, + tlig = true, + script = "latn", + lang = "dflt", + --stretch = 30, + --shrink = 20, + --step = 10, + }, + + normal = { + "Normal", "Regular", "Book", + }, + +} diff --git a/Master/texmf-dist/doc/plain/pitex/i-pitex.lua b/Master/texmf-dist/doc/plain/pitex/i-pitex.lua new file mode 100644 index 00000000000..4559a1901db --- /dev/null +++ b/Master/texmf-dist/doc/plain/pitex/i-pitex.lua @@ -0,0 +1,163 @@ +local gsub, match, gmatch = string.gsub, string.match, string.gmatch +local insert = table.insert +local add_pattern = interpreter.add_pattern + +-- CLASS 1: things that prevent other things, thanks to protection. +interpreter.default_class = 1 + +-- "> foo ..." as the first line of a paragraph signals a description +-- of foo. +local function describe (buffer, num) + if num == 1 then + local line = buffer[num] + line = line .. " " + line = gsub(line, "^> ", "") + line = gsub(line, "{<(.-)>}", "\\hskip1pt\\hbox{\\barg{%1}}") + line = gsub(line, "^(.-)%s+", "\\describe{%1}{") + line = gsub(line, "%[<(.-)>%]", "\\hskip1pt\\hbox{\\oarg{%1}}") + line = gsub(line, "<(.-)>", "\\hskip1pt\\hbox{\\arg{%1}}") + line = gsub(line, "\\hfil", "", 1) + line = gsub(line, "%s*$", "}", 1) + buffer[num] = line + interpreter.protect(num) + else + return 2 + end +end +add_pattern{pattern = "^[\\>]", call = describe} + +-- Verbatim material is marked by a 10-space indent. +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","", 1) + end + insert(buffer, 1, [[\verbatim]]) + if gsub(buffer[#buffer], + interpreter.paragraph, "") == "" then + buffer[#buffer] = [[\verbatim/]] + else + insert(buffer, [[\verbatim/]]) + end + interpreter.protect() +end +add_pattern{pattern = "^%s%s%s%s%s%s%s%s%s%s", call = verbatim} + +-- CLASS 2: protecting control sequences, so they're verbatim. +interpreter.default_class = 2 +add_pattern { + pattern = "(\\[%a@]+)", + replace = '"%1"'} + + +-- CLASS 3: things that precede other things. +interpreter.default_class = 3 + +-- Tables. +local function table (buffer) + buffer[1] = "PROTECT\\tablePROTECT" + if buffer[#buffer] == "" then + buffer[#buffer-1] = "PROTECT\\table/PROTECT" + else + buffer[#buffer] = "PROTECT\\table/PROTECT" + end + local cells = 0 + for i, l in ipairs(buffer) do + if match(l, "^%-%-%-") then + l = "%" + else + l = gsub(l, "^|", "") + l = gsub(l, "|%s*$", "PROTECT\\crPROTECT") + local c = 0 + l = gsub(l, "|", function () c = c + 1 return "&" end) + cells = c > cells and c or cells + end + buffer[i] = l + end + for i, l in ipairs(buffer) do + if match(l, "\\cr") then + local c = 0 + for tab in gmatch(l, "&") do + c = c + 1 + end + for x = 1, cells - c do + buffer[i] = gsub(l, "\\cr", "\\span\\cr") + end + end + end +end +add_pattern{pattern = "^%-%-%-", call = table} + +-- Sections. +local function make_header(buffer, num, _, pattern) + if num + 1 == #buffer then + local l = buffer[1] + l = gsub(l, "^%s*", "") + l = "\\" .. pattern.type .. "{" .. l + if match(l, ":([%S]+)%s*$") then + l = gsub(l, "%s*:([%a_]+)%s*$", "}PROTECT[%1]PROTECT") + else + l = l .. "}" + end + buffer[1] = l + buffer[num] = "" + end +end +add_pattern {pattern = "^%s*===", call = make_header, type = "section"} +add_pattern {pattern = "^%s*~~~", call = make_header, type = "subsection"} +add_pattern {pattern = "^%s%s%s*%-%-%s+(.-)%s+%-%-", + call = function (buffer, line, _, pattern) + buffer[line] = gsub(buffer[line], pattern.pattern, "\\paragraph{%1}") + buffer[line] = gsub(buffer[line], "%s*:(%S+)", "PROTECT[%1]PROTECT") + end} + + +-- CLASS 4: things with no order of preference. +interpreter.default_class = 4 + +add_pattern {pattern = "%*(.-)%*", replace = "\\emph{%1}"} +add_pattern {pattern = "%*%*(.-)%*%*", replace = "\\bold{%1}"} +add_pattern {pattern = "%?([a-zA-Z]+)", replace = "\\attr{%1}"} +add_pattern {pattern = "!([a-zA-Z]+)", replace = "\\param{%1}"} +add_pattern {pattern = "=([a-zA-Z]+)", replace = "\\value{%1}"} +add_pattern {pattern = "|(.-)|", replace = "\\gateaction{%1}"} +add_pattern {pattern = "<(.-)>", replace = "\\arg{%1}"} +add_pattern {pattern = "{<(.-)>}", replace = "\\barg{%1}", offset = 7} +add_pattern {pattern = "%[<(.-)>%]", replace = "\\oarg{%1}", offset = 7} +add_pattern {pattern = "TeX", replace = "\\TeX{}", offset = 2} + +add_pattern {pattern = "(texapi)(.?)", offset = 7, + replace = function (a, b) + a = "\\emph{texapi}" + if b == "'" then + a = a .. "\\kern.2em'" + else + a = a .. b + end + return a + end} + +-- Links. +add_pattern {pattern = "%s*%[see%s+([%a_]+)%]", + call = function (buffer, line, index, pattern) + local l = buffer[line] + local pre, post = l:sub(1, index-1), l:sub(index) + local text + if pre:match("{.-}$") then + pre, text = match(pre, "(.*){(.-)}$") + else + pre, text = match(pre, "(.-)(%a+)$") + end + post = gsub(post, pattern.pattern, "\\jumplink{PROTECT%1PROTECT}{" .. text .. "}", 1) + buffer[line] = pre .. post + end} +add_pattern {pattern = ":([%a_]+)", replace = "\\anchor{PROTECT%1PROTECT}"} + + +-- CLASS 0: the broom wagon +interpreter.default_class = 0 + +interpreter.protector('"') +add_pattern {pattern = '"(.-)"', replace = "\\verb`%1`", class = 0} + +interpreter.protector("PROTECT") +add_pattern {pattern = "PROTECT(.-)PROTECT", replace = "%1", class = 0} diff --git a/Master/texmf-dist/doc/plain/pitex/pitex-doc.pdf b/Master/texmf-dist/doc/plain/pitex/pitex-doc.pdf Binary files differnew file mode 100644 index 00000000000..dbcbfa7e96e --- /dev/null +++ b/Master/texmf-dist/doc/plain/pitex/pitex-doc.pdf diff --git a/Master/texmf-dist/doc/plain/pitex/pitex-doc.tex b/Master/texmf-dist/doc/plain/pitex/pitex-doc.tex new file mode 100644 index 00000000000..63c6281717d --- /dev/null +++ b/Master/texmf-dist/doc/plain/pitex/pitex-doc.tex @@ -0,0 +1,106 @@ +\input pitex + +\setparameter document : + author = "Paul Isambert" + title = "The PiTeX documentation" + date = "November 2011" + layout = onecolumn + mode = bookmarks + +\setparameter page: + height = 24cm + left = 4cm + hsize = 32pc + +\setfont\mainfont : + name = "Chaparral Pro" + size = 10pt + bold = Semi + big = 50pt + +\setfont\codefont : + name = "Lucida Console" + size = 8pt + slant = .15 + features = "space = mono" + bold italic = none + +\setparameter marginnote: + baselineskip = 9pt + font = "\small\it" + +\setparameter section: + font = \sc + + +\OutputRoutine remove {headers, inserts}{shipout} + +\newblock\table + {\ifdim\lastskip=\baselineskip + \needspace{2\baselineskip}% + \else + \needspace{3\baselineskip}% + \vskip\baselineskip + \fi + \halign\bgroup##\unskip\hfil&&\kern1em##\unskip\hfil\cr} + {\egroup + % This is a horrible hack to circumvent a bug in LuaTeX (\prevdepth not + % updated after \halign) (rev 4277). + \directlua{% + local n = tex.lists.page_head + while n.next do + n = n.next + end + tex.nest[tex.nest.ptr].prevdepth = n.depth}% + \vskip\baselineskip + }% + + +\def\describe#1#2{% + \needspace{2\baselineskip}% + \bgroup\codefont + \noindent\color{.8 0 0}{\llap{\string#1\kern.3em}% + #2\par\egroup}\removenextindent + \ignorespaces} + +\def\comarg{\arg{command}\antigobblespace} +\def\textarg{\arg{text}} + +\def\filesection#1{\section{File: \tcode{#1}}} +\pdfdef\verb`#1`{#1} + +\def\attr#1{{\codefont\color{0 .5 0}{#1}}} +\def\param#1{{\codefont\color{.8 0 0}{#1}}} +\def\value#1{{\codefont\color{.3 .3 .6}{#1}}} + +\def\texapi{\emph{texapi}} +\def\navigator{\emph{Navigator}} +\def\tex{\TeX\antigobblespace} + +%%% Redefining \TeX to look better with Chaparral. +\def\TeX{% + T\kern-.13em + \lower.5ex \hbox {E}% + \kern-.03em X% + } + + + + + +\vbox to 50pt{% + \vfil + \hbox{% + \hbox{\big\sc Pi\kern-.08em\TeX}% + \kern1cm + \vbox{% + \hbox{Paul Isambert}% + \hbox{\codefont zappathustra@free.fr}% + \hbox{November 2011}}}% + \vfil + } + +\input interpreter +\interpretfile{pitex}{pitex-doc.txt} + +\bye diff --git a/Master/texmf-dist/doc/plain/pitex/pitex-doc.txt b/Master/texmf-dist/doc/plain/pitex/pitex-doc.txt new file mode 100644 index 00000000000..168e7e7b18a --- /dev/null +++ b/Master/texmf-dist/doc/plain/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. |