### 4.15 Schmooz ¶

Schmooz is a simple, lightweight markup language for interspersing Texinfo documentation with Scheme source code. Schmooz does not create the top level Texinfo file; it creates ‘`txi`’ files which can be imported into the documentation using the Texinfo command ‘`@include`’.

`(require 'schmooz)` defines the function `schmooz`, which is used to process files. Files containing schmooz documentation should not contain `(require 'schmooz)`.

Procedure: schmooz filename.scm … ¶

  Filename.scm should be a string ending with ‘`.scm`’ naming an existing file containing Scheme source code. `schmooz` extracts top-level comments containing schmooz commands from filename.scm and writes the converted Texinfo source to a file named filename.txi.

Procedure: schmooz filename.texi … ¶
Procedure: schmooz filename.tex … ¶
Procedure: schmooz filename.txi … ¶

  Filename should be a string naming an existing file containing Texinfo source code. For every occurrence of the string ‘`@include filename.txi`’ within that file, `schmooz` calls itself with the argument ‘`filename.scm`’.

Schmooz comments are distinguished (from non-schmooz comments) by their first line, which must start with an at-sign (@) preceded by one or more semicolons (`;`). A schmooz comment ends at the first subsequent line which does not start with a semicolon. Currently schmooz comments are recognized only at top level.

Schmooz comments are copied to the Texinfo output file with the leading contiguous semicolons removed. Certain character sequences starting with at-sign are treated specially. Others are copied unchanged.

A schmooz comment starting with ‘`@body`’ must be followed by a Scheme definition. All comments between the ‘`@body`’ line and the definition will be included in a Texinfo definition, either a ‘`@defun`’ or a ‘`@defvar`’, depending on whether a procedure or a variable is being defined.

Within the text of that schmooz comment, at-sign followed by ‘`0`’ will be replaced by `@code{procedure-name}` if the following definition is of a procedure; or `@var{variable}` if defining a variable.

An at-sign followed by a non-zero digit will expand to the variable citation of that numbered argument: ‘`@var{argument-name}`’.

If more than one definition follows a ‘`@body`’ comment line without an intervening blank or comment line, then those definitions will be included in the same Texinfo definition using ‘`@defvarx`’ or ‘`@defunx`’, depending on whether the first definition is of a variable or of a procedure.

Schmooz can figure out whether a definition is of a procedure if it is of the form:

‘`(define (<identifier> <arg> ...) <expression>)`’

or if the left hand side of the definition is some form ending in a lambda expression. Obviously, it can be fooled. In order to force recognition of a procedure definition, start the documentation with ‘`@args`’ instead of ‘`@body`’. ‘`@args`’ should be followed by the argument list of the function being defined, which may be enclosed in parentheses and delimited by whitespace, (as in Scheme), enclosed in braces and separated by commas, (as in Texinfo), or consist of the remainder of the line, separated by whitespace.

For example:

    ;;@args arg1 args ...
    ;;@0 takes argument @1 and any number of @2
    (define myfun (some-function-returning-magic))

Will result in:

    @defun myfun arg1 args @dots{}

    @code{myfun} takes argument @var{arg1} and any number of @var{args}
    @end defun

‘`@args`’ may also be useful for indicating optional arguments by name. If ‘`@args`’ occurs inside a schmooz comment section, rather than at the beginning, then it will generate a ‘`@defunx`’ line with the arguments supplied.

If the first at-sign in a schmooz comment is immediately followed by whitespace, then the comment will be expanded to whatever follows that whitespace. If the at-sign is followed by a non-whitespace character then the at-sign will be included as the first character of the expansion. This feature is intended to make it easy to include Texinfo directives in schmooz comments.