1With the advent of YODL V 2.00, em(raw macros files) are introduced. A raw
2macro file defines one macro, and em(all) of its conversions. The raw macro
3files must be organized as follows:
4        verb(
5    <STARTDOC>
6    macro(name(arg1)(arg2)(etc))
7    (
8
9        Description of the macro `name', having arguments `arg1', `arg2',
10        `etc', each argument is given its own parameter list. The names of the
11        arguments in this description should be chosen in such a way that they
12        suggest their function or purpose. All macro descriptions starting
13        with tt(<STARTDOC>) will be included in both the `man yodlmacros'
14        manpage and the description of the macro in the user guide. If this is
15        not considered appropriate (e.g., tt(XX...()) macros are not described
16        in these documents) then use tt(<COMMENT>) rather than
17        tt(<STARTDOC>).
18    )
19    <>
20    DEFINEMACRO(name)(#)(
21        statements of macro `name' expecting `#' arguments used by all
22        conversions. This section is optional
23    <html>
24        statements that should be executed by the HTML converter
25    <man ms>
26        statements that should be executed by two converters. In this case,
27        the `man' and `ms' converters
28    <else>
29        statements that should be executed by all converters not explicitly
30        mentioned above
31    <>
32        statements of macro `name' expecting `#' arguments used by all
33        conversions, having processed their specific statements.
34        This section is also optional
35    )
36        )
37    When setting up these macro definitions, the tt(<>) tags must appear with
38the initial documentation section. It must also appear when at least one
39specific converter tag is used. For a macro which is converter independent,
40the macro definition doesn't contain these pointed-arrow tags.
41
42    When writing standard YODL macros, each macro should be stored in a file
43tt(`name'.raw), where tt(`name') is the lower-case name of the macro. This
44file should then be kept in the tt(macros/rawmacros) directory. The
45tt(macros/build std) call will then add the macro (filtering only the required
46statements per conversion) to each of the standard conversion formats.
47
48    If the macro requires a counter or symbol, consider defining the counter
49or symbol in, respectively, tt(@counters) and tt(@symbols). Furthermore,
50consider em(pushing) and em(popping) these `variables', rather than plain
51assigning them, to allow other macros to use the variables as well. A case in
52point is the counter tt(XXone) which was added to the set of counters
53representing a em(local counter). Macros may em(always) push tt(XXone) and pop
54tt(Xxone), but should never reassign tt(XXone) before its value has been
55pushed. For YODL version 2.00 only tt(XXone) was required, but other local
56counters might be considered useful in the future. In that case, tt(XXtwo),
57tt(XXthree) etc. will be used. For local symbold tt(XXs) prefixes will be
58used: tt(XXsone), tt(XXstwo), etc.
59