Macros are userdefined placeholders that you can use for different purposes.
When using the !macro command you tell UDO the name of the macro in first place. The name of the macro is followed by its contents which may be empty, too.
Let me show you some examples:
!macro HTML Hypertext Markup Language !macro UDO (!B)U(!b)niversal (!B)Do(!b)cument !macro DOSG (!T)UDO6GDOS.ZIP(!t) !ifdest [html] !macro PICPATH gif/ !else !macro PICPATH img/ !endif [...] The (!HTML) ... The (!UDO) Format ... The archive named (!DOSG) ... !image (!PICPATH)/tiger
Macros can help you to save time when typing often used long words. Furthermore macros can help you to change the contents of your file by simply changing the contents for macros (e.g. if your program name changed and you use a macro for the name of your program). Another example is the usage of standardized text (e.g. a standard disclaimer) where you use macros instead of the name of the program etc. These standardized texts can be included with !include. In the following example a disclaimer is included and the name of the program is defined by a macro:
[doku.u] !macro PRG Windows95 [disclaim.u] (!PRG) is provided ""as is"" without a warranty of any kind. Use it on your own risk.
Since UDO Release 6 you can call macros with parameters. You can set the position of the parameters in the !macro command by inserting `(!1)', `(!2)' till `(!9)'. To call a macro with parameters you have to write brackets (`[...]') around them.
The following small example shows how to use a macro for text that shall be printed in bold-italic style:
!macro BI (!B)(!I)(!1)(!i)(!b) ... This text is printed (!BI [bold and italic]).
The "(!1)" in the macro line will be replaced by the words "bold and italic".
Please note:
Like macros definitions are user-defined placeholders. You can use them to insert special commands inside the text especially for the destination format.
The syntax is !define <word> <text>. In contrast to macros <text> will not be converted in a special way. No special characters are translated inside <text>.
In this example I will demonstrate how to print headlines with HTML:
!ifdest [html] !define H1 <H1> !define h1 </H1> !else !define H1 !define h1 !endif [...] (!H1)A headline(!h1)
As you can see you can use definitions to insert special commands that aren't supported by UDO. UDO Release 4 offered a lot of special commands for LaTeX that you now have to simulate with the !define command:
!ifdest [tex] !define ff "ff !define nolb3 \nolinebreak[3] !define lb2 \linebreak[2] !else !define ff ff !define nolb3 !define lb2 !endif [...] Tell (!LaTeX) a good place (!lb2) for breaking lines.
You can use definitions with parameters, too. Definitions with parameters are used the same way you can use macros with parameters. Definitions with parameters are a great help to expand UDO's support of a destination format.
You declare definitions like in the upper example. You can tell UDO the positions of the parameters by adding `(!1)', `(!2)' till `(!9)'. When you call a definition you have to write brackets (`[...]') around the parameters.
In the upper example I have shown you how to make a heading for HTML. When using parameters it may look like the following example:
!ifdest [html] !define head <H1>(!1)</H1> !else !define head (!1) !endif [...] (!head [A headline])
As you can see in this example you can write format depending commands UDO doesn't support already.
The upper LaTeX example can be defined nicer, too. If you use parameters you can provide all available LaTeX commands in one definition:
!ifdest [tex] !define lb \linebreak[(!1)] !else !define lb (!2) !endif [...] Tell (!LaTeX) a good place (!lb [2]) for breaking lines.
In this example only one parameter is used but the non-LaTeX definition contains a second parameter. You may ask yourself why it has to be like this. Well, if you call the definition with only one parameter the second parameter is empty. When expanding the non-LaTeX definition UDO will replace the definition placeholder by empty space (because there is no second parameter, you understand?). Unfortunately you have to use this work-around when using definition with placeholders.
Please note:
To add entries for the index you can use the !index command or the (!idx ...) placeholder. You can and should use these commands as often as possible.
To add an entry with the !index command use it this way:
!index Index entry
The entry appears inside the index of LaTeX, inside the index of a Texinfo file that was printed with TeX, inside the index of an ST-Guide hypertext, inside the search dialog of Windows Help and inside the index of an RTF file.
To insert a multi-index you can separate the index entries with a double exclamation mark. You can use up to three indices in one line. You should use multi-indices when it's obvious that a potential reader looks for an entry in different ways.
If you think that a reader might look for "Index entry" or "Entry, Index" you should use the following index commands:
!index Index entries !index Entry !! Index
If you use the placeholder (!idx ...) you can use up to four parameters. The following examples show how the commands are converted for LaTeX, Windows Help and RTF:
UDO: an (!idx [entry]) LaTeX: an entry\index{entry} Win: an {K{\footnote K entry}}entry else: an entry UDO: a (!idx [word] [entry]) LaTeX: a Wort\index{entry} Win: a {K{\footnote K entry}}word else: a Wort UDO: a (!idx [word] [entry] [subentry]) LaTeX: a word\index{entry!subentry} Win: a {K{\footnote K entry, subentry}}word else: a word UDO: a (!idx [word] [entry] [subentry] [subsubentry]) LaTeX: a word\index{entry!subentry!subsubentry} Win: a {K{\footnote K entry, subentry, Subsubentry}}word else: a word
Please note:
wrong: (!idx [Copyright (c) 1995] ) right: (!idx [Copyright (c!) 1995] )
UDO offers you two commands and an environment for every destination format that you can use to insert special commands for this format. So you are able to insert small passages or huge blocks written in the destination format (like special tables for LaTeX or HTML).
You have to use abbreviations of the destination formates if you want to use these special commands:
asc | ASCII |
aqv | Apple QuickView |
htag | HP Helptag SGML |
html | HTML |
info | Texinfo |
ldoc | Linuxdoc-SGML |
lyx | LyX |
man | Manualpage |
pch | Pure C Help |
rtf | RTF |
stg | ST-Guide |
tex | LaTeX |
tvh | Turbo Vision Help |
win | Windows Help |
For every destination format UDO offers a command to insert a line with commands for the current destination format, and a command to insert a line for all different formats. The commands are built by a `!' and the abbreviations or `!=' plus the abbreviation.
The next example shows how to insert a line that will only be printed for the ASCII format:
!asc This line appears only in ASCII.
The next example shows how to insert a line that appears in all formats except ASCII:
!=asc This line doesn't appear in ASCII.
The contents of the line will be printed without the command and without converting the text of the line. These commands split up text into different paragraphs like all the other UDO commands. So these commands aren't useful to insert a line into a paragraph!
You can use these commands to insert special commands like parts of the preamble for LaTeX:
!tex \documentstyle[11pt,makeidx]{article} !tex \makeindex [...] !tex \printindex
But it happens that you want to insert large passages only for one format with special commands. You could add one of the upper commands at the beginning of each line, sure. But to make it easier for you to insert these passages UDO has a special environment for this case: the raw environment.
Together with the possibility to check the current destination format you can e.g. insert complex tables for LaTeX or forms for HTML with the raw environment. The following example shows how to enter HTML forms to your source code:
!ifdest [html] !begin_raw <FORM method=post action="mailto:DirkHage@aol.com"> <PRE> <p> Name: <INPUT name="Name" size=60> <p> <p> <INPUT type=submit value="Send"> <p> <INPUT type=reset value="Reset"> </PRE> </FORM> !end_raw !else The HTML version will display a form here. !endif
To say it once more: Text that is part of a raw environment is printed "as is". That means that it's not converted and not indented. If you will insert the upper form source code into a verbatim environment you will see the source code in an HTML browser. But if you insert it inside a raw environment you will see the form!
UDO offers you the commands !include, !vinclude and !rinclude. With these commands you are enabled to split up a document into many files that are included by a main file. Furthermore you can use these commands to include an often used passage that you have to type only once.
This documentation uses this commands intensively. The file udo.u doesn't contain any text and just includes other files. So I have the possibility to find some passages more fast if I have to change the documentation.
You can use !include wherever you want. So you can define macros, definitions or syllabification patterns in external files that can be used by other files, too.
For displaying the preformatted contents of a file you can use the !vinclude command ("verbatim include"). You can use this command e.g. for displaying source files or header files.
If you want to included special commands for a destination format like difficult tables for LaTeX or HTML you can use the !rinclude command ("raw include").
Possible examples of use: