Next: Simple d4c&b files Prev: Documenting tcl files
Some applications define data files which are not in some conventional language, but whose format is specific to that application. An application file can be documented provided it's format is simple enough - each entry occupies one line and entry name (and it's value if applicable) can be captured in one regular expression. Specification of an application file appears in a language specification line. For example,
/* -@- ( // / "[[:blank:]]*\([^[:blank:]]*\)" ) -@- */The first argument specifies how a comment starts, and the second what is added to a that start to make an element auto comment. The above obviously describes a ``C++'' comment. The next argument is a regular expression. The expression should contain one or more sub expressions. By default, the first subexpression matches the element name. The rest, if given, are concatenated to create the element value.
The default may be overridden by an optional fourth and fifth arguments. The fourth argument explicitly defines the value using Backreferences. For example
# -@- ( # # "[[:blank:]]*\([^[:blank:]]*\)[[:blank:]]*\(.*\)" "@code{\1}" ) -@-
As the above demonstrates, a replacement string may contain texinfo commands, including @ref!!
Similarly, the fifth argument is a replacement pattern for element name. If an empty replacement pattern `""' is given, the default is used.
The six (and last) optional argument is a replacement pattern for element tag, the name used to reference the element. If not present, tag is the same as element name. With `""', referencing the element is disabled.
A specification need not be duplicated in each file. It is possible to define it once in the preferences file with a `UserFile' line. For example,
UserFile dtopic "def" // / DTOPIC([[:blank:]]*\([^[:blank:]]*\)[[:blank:]]*)`dtopic' is the type name, and the second item is a list of suffixes of files of this type. Those two are followed by the specification explained above. Now it is possible to place the language specification line `// -@- dtopic -@-' in such files.