############################################################
# @(#) Definitions, Dirk Hagedorn, 1996/04/17
############################################################

!subsubnode Definitions

Like macros definitions are user-defined placeholders. You can use them to
insert special commands inside the text especially for the destination
format.

!index !/define
The syntax  is (!T)!/define <word> <text>(!t). In contrast to macros
(!T)<text>(!t) will not be converted in a special way. No special
characters are translated inside (!T)<text>(!t).

In this example I will demonstrate how to print headlines with HTML:

!begin_quote
!begin_verbatim
!ifdest [html]
  !define H1 <H1>
  !define h1 </H1>
!else
  !define H1
  !define h1
!endif
[...]
(!H1)A headline(!h1)
!end_verbatim
!end_quote

!smallskip

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
(!I)!/define(!i) command:

!index \linebreak
!index \nolinebreak

!begin_quote
!begin_verbatim
!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.
!end_verbatim
!end_quote

!smallskip

!index Parameters !! Definitions
!index Definitions !! Parameters

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 ''(!T)(!/1)(!t)'', ''(!T)(!/2)(!t)''
till ''(!T)(!/9)(!t)''. 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:

!begin_quote
!begin_verbatim
!ifdest [html]
  !define head <H1>(!1)</H1>
!else
  !define head (!1)
!endif
[...]
(!head [A headline])
!end_verbatim
!end_quote

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:

!begin_quote
!begin_verbatim
!ifdest [tex]
  !define lb \linebreak[(!1)]
!else
  !define lb (!2)
!endif
[...]
Tell (!LaTeX) a good place
(!lb [2]) for breaking lines.
!end_verbatim
!end_quote

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.

!smallskip

(!HINTS)

!begin_enumerate

!item	Characters of text of the (!I)!/define(!i) command won't be
converted.

!item	Characters of the parameters you pass to the definition will be
converted.

!index !/heading
!item	UDO supports the (!I)!/heading(!i) command for displaying headlines.
The upper HTML example is only used for demonstration.

!item When naming the definitions you should be cautious not to use
pre-defined UDO command names like ""B"" or ""nl"". If you don't you will
get problems with bold text ((!/B)) or the newline command ((!/nl)).

!item You shouldn't use too many definitions because every additional
definition slows down the conversion of the source file. The maximum number
of definitions is (!MAXMACRO).

!end_enumerate
