Next: , Previous: term ansi-color, Up: Top


36 (texinfo)

36.1 Overview

Texinfo processing in scheme

This module parses texinfo into SXML. TeX will always be the processor of choice for print output, of course. However, although makeinfo works well for info, its output in other formats is not very customizable, and the program is not extensible as a whole. This module aims to provide an extensible framework for texinfo processing that integrates texinfo into the constellation of SXML processing tools.

Notes on the SXML vocabulary

Consider the following texinfo fragment:

      @deffn Primitive set-car! pair value
      This function...
      @end deffn

Logically, the category (Primitive), name (set-car!), and arguments (pair value) are “attributes” of the deffn, with the description as the content. However, texinfo allows for @-commands within the arguments to an environment, like @deffn, which means that texinfo “attributes” are PCDATA. XML attributes, on the other hand, are CDATA. For this reason, “attributes” of texinfo @-commands are called “arguments”, and are grouped under the special element, `%'.

Because `%' is not a valid NCName, stexinfo is a superset of SXML. In the interests of interoperability, this module provides a conversion function to replace the `%' with `texinfo-arguments'.

36.2 Usage

— Function: call-with-file-and-dir filename proc

Call the one-argument procedure proc with an input port that reads from filename. During the dynamic extent of proc's execution, the current directory will be (dirname filename). This is useful for parsing documents that can include files by relative path name.

— Variable: texi-command-specs

A list of (name content-model . args)

name
The name of an @-command, as a symbol.
content-model
A symbol indicating the syntactic type of the @-command:
EMPTY-COMMAND
No content, and no @end is coming
EOL-ARGS
Unparsed arguments until end of line
EOL-TEXT
Parsed arguments until end of line
INLINE-ARGS
Unparsed arguments ending with #\}
INLINE-TEXT
Parsed arguments ending with #\}
ENVIRON
The tag is an environment tag, expect @end foo.
TABLE-ENVIRON
Like ENVIRON, but with special parsing rules for its arguments.
FRAGMENT
For *fragment*, the command used for parsing fragments of texinfo documents.

INLINE-TEXT commands will receive their arguments within their bodies, whereas the -ARGS commands will receive them in their attribute list.

EOF-TEXT receives its arguments in its body.

ENVIRON commands have both: parsed arguments until the end of line, received through their attribute list, and parsed text until the @end, received in their bodies.

EOF-TEXT-ARGS receives its arguments in its attribute list, as in ENVIRON.

There are four @-commands that are treated specially. @include is a low-level token that will not be seen by higher-level parsers, so it has no content-model. @para is the paragraph command, which is only implicit in the texinfo source. @item has special syntax, as noted above, and @entry is how this parser treats @item commands within @table, @ftable, and @vtable.

Also, indexing commands (@cindex, etc.) are treated specially. Their arguments are parsed, but they are needed before entering the element so that an anchor can be inserted into the text before the index entry.

args
Named arguments to the command, in the same format as the formals for a lambda. Only present for INLINE-ARGS, EOL-ARGS, ENVIRON, TABLE-ENVIRON commands.

— Function: texi-command-depth command max-depth

Given the texinfo command command, return its nesting level, or #f if it nests too deep for max-depth.

Examples:

          (texi-command-depth 'chapter 4)         1
          (texi-command-depth 'top 4)             0
          (texi-command-depth 'subsection 4)      3
          (texi-command-depth 'appendixsubsec 4)  3
          (texi-command-depth 'subsection 2)      #f

— Function: texi-fragment->stexi string-or-port

Parse the texinfo commands in string-or-port, and return the resultant stexi tree. The head of the tree will be the special command, *fragment*.

— Function: texi->stexi port

Read a full texinfo document from port and return the parsed stexi tree. The parsing will start at the @settitle and end at @bye or EOF.

— Function: stexi->sxml tree

Transform the stexi tree tree into sxml. This involves replacing the % element that keeps the texinfo arguments with an element for each argument.

FIXME: right now it just changes % to texinfo-arguments – that doesn't hang with the idea of making a dtd at some point