|
|
Yodl builtin functions(7) Your Own Document Language Yodl builtin functions(7) NAME
yodlbuiltins - Builtins for the Yodl converters SYNOPSIS
This manual page lists the standard builtins of the Yodl package. DESCRIPTION
The following list shows the builtins defined by the Yodl converters define and which can be used in Yodl documents. Refer to the Yodl user guide, distributed with the Yodl package, for a full description. The following list shows all builtins of the package in alphabetical order. NOTE: Starting with Yodl version 3.00.0 Yodl's default file inclusion behavior has changed. The current working directory no longer remains fixed at the directory in which Yodl is called, but is volatile, changing to the directory in which a yodl-file is located. This has the advantage that Yodl's file inclusion behavior now matches the way C's #include directive operates; it has the disadvantage that it may break some current documents. Conversion, however is simple but can be avoided altogether if Yodl's -L (--legacy-include) option is used. The builtins INCLUDEFILE, NOEXPANDINCLUDE and NOEXPANDPATHINCLUDE are affected by this new behavior. Yodl's builtin commands As mentioned previously, YODL's input consists of text and of commands. YODL supports a number of built-in commands which may either be used in a YODL document, or which can be used to create a macro package. Don't despair if you find that the description of this section is too technical. Exactly for this reason, YODL supports the macro packages to make the life of a documentation writer easier. E.g., see chapter [MACROPACKAGE] that describes a macro package for YODL. Most built-in functions and macros expand the information they receive the way they receive the information. I.e., the information itself is only evaluated by the time it is eventually inserted into an output medium (usually a file). However, some builtin func- tions will evaluate their argument(s) once the argument is processed. They are: o The ERROR() built-in function (see section [ERROR]); o The EVAL() built-in function (see section [EVAL]); o The FPUTS() built-in function (see section [FPUTS]); o The INTERNALINDEX() built-in function (see section [INTERNALINDEX]); o The TYPEOUT() built-in function (see section [TYPEOUT]); o The UPPERCASE() built-in function (see section [UPPERCASE]); o The WARNING() built-in function (see section [WARNING]); All other built-in functions will not evaluate their arguments. See the mentioned functions for details, and in particular EVAL() for a description of this evaluation process. ADDTOCOUNTER The ADDTOCOUNTER function adds a given value to a counter. It expects two parameter lists: the counter name, and the value to add. The counter must be previously created with DEFINECOUNTER. The value to add can be negative; in that case, a value is of course subtracted from the counter. See further section [COUNTERS]. ADDTOSYMBOL Since Yodl version 2.00 symbols can be manipulated. To add text to an existing symbol the builtin ADDTOSYMBOL is available. It expects two parameter lists: the symbol's name, and the text to add to the symbol. The symbol must have been created earlier using DEFINECOUNTER (see section [DEFINECOUNTER]). The macro's second argument is not evaluated while ADDTOSYMBOL is processed. Therefore, it is easy to add the text of another symbol or the expansion of a macro to a symbol value. E.g., ADDTOSYMBOL(one)(SYMBOLVALUE(two)XXnl()) This will add the text of symbol two, followed by a new line, to the contents of symbol one only when symbol one is evaluated, not when ADDTOSYMBOL is evaluated. Example: ADDTOSYMBOL(LOCATION)(this is appended to LOCATION) ATEXIT ATEXIT takes one parameter list as argument. The text of the parameter list is appended to the output file. Note that this text is subject to character table translations etc.. An example using this function is the following. A document in the LaTeX typesetting language requires end{document} to occur at the end of the document. To automatically append this string to the output file, the following specification can be used: ATEXIT(NOEXPAND(end{document})) Several ATEXIT lists can be defined. They are appended to the output file in the reverse order of specification; i.e., the first ATEXIT list is appended to the output file last. That means that in general the ATEXIT text should be specified when a `matching' starting command is sent to the output file; as in: COMMENT(Start the LaTeX document.) NOEXPAND(egin{document}) COMMENT(Ensure its proper ending.) ATEXIT(NOEXPAND(end{document})) CHAR The command CHAR takes one argument, a number or a character, and outputs its corresponding ASCII character to the final output file. This command is built for `emergency situations', where you need to typeset a character despite the fact that it may be rede- fined in the current character table (for a discussion of character tables, see [CHARTABLES]). Also, the CHAR function can be used to circumvent Yodl's way of matching parentheses in a parameter list. The following arguments may be specified with CHAR (attempted in this order): o A decimal number indicating the number of the character in the ascii-table (for example CHAR(41)); o A plain, single character (for example CHAR(#)). So, when you're sure that you want to send a printable character that is not a closing parenthesis to the output file, you can use the form CHAR(c), c being the character (as in, CHAR(;)). To send a non-printable character or a closing parenthesis to the output file, look up the ASCII number of the character, and supply that number as argument to the CHAR command. Example: The following two statements send an A to the output file. CHAR(65) CHAR(A) The following statement sends a closing parenthesis: CHAR(41) Another way to send a string to the output file without expansion by character tables or by macro interpretation, is by using the function NOTRANS (see section [NOTRANS]). If you want to send a string to the output without macro interpretation, but with charac- ter table translation, use NOEXPAND (see section [NOEXPAND]). CHDIR The command CHDIR takes one argument, a directory to change to. This command is implemented to simplify the working with includefile (see includefile in yodlmacros(7)). As a demonstration, consider the following fragment: includefile(subdir/onefile) includefile(subdir/anotherfile) includefile(subdir/yetanotherfile) This fragment can be changed to: CHDIR(subdir) includefile(onefile) includefile(anotherfile) includefile(yetanotherfile) CHDIR(..) The current directory, as given to CHDIR, only affects how includefile will search for its files. Note that this example assumes that the current working directory is a member of Yodl's include-path specification (cf., Yodl's --include option). COMMENT The COMMENT function takes one parameter list. The text in the list is treated as comment. I.e., it is ignored. The text is not copied to the final output file. COUNTERVALUE COUNTERVALUE expands to the value of a counter. Its single parameter list must contain the name of a counter. The counter must have been created earlier using the builtin DEFINECOUNTER. Example: The counter has value COUNTERVALUE(MYCOUNTER). See also section [COUNTERS]. DECWSLEVEL DECWSLEVEL requires one (empty) parameter list. It reduces the current white-space level. The white-space level typically is used in files that only define Yodl macros. When no output should be generated while processing these files, the white-space level can be used to check for this. If the white-space level exceeds zero, a warning will be generated if the file produces non-whitespace out- put. The builtin function DECWSLEVEL is used to reduce the whitespace level following a previous call of INCWSLEVEL. Once the white space level exceeds zero, no output will be generated. White space, therefore will effectively be ignored. The white space level cannot be reduced to negative values. A warning is issued if that would have happened if it were allowed. Example: INCWSLEVEL() DEFINESYMBOL(....) DEFINEMACRO(...)(...)(...) DECWSLEVEL() Without the INCWSLEVEL and DECWSLEVEL, calls, the above definition would generate four empty lines to the output stream. The INCWSLEVEL and DECWSLEVEL calls may be nested. The best approach is to put an INCWSLEVEL at the first line of a macro-defining Yodl-file, and a matching DECWSLEVEL call at the very last line. DEFINECHARTABLE DEFINECHARTABLE is used to define a character translation table. The function expects two parameterlists, containing the name of the character table and character table translations on separate lines. These character table translations are of the form character = quoted-string Here, character is always a value within single quotes. It may be a single character, an octal character value or a hexadecimal character value. The single character may be prefixed by a -character (e.g., '\'). The octal character value must start with a backslash, followed by three octal digits (e.g., '