/usr/share/doc/udo-doc-en/html/005009.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/html4/loose.dtd">
<!-- last modified on 2005/10/25 -->
<html lang="en">
<head>
<title>
The guide to UDO: Miscellaneous
</title>
<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<meta http-equiv="Content-Language" content="en">
<meta http-equiv="Content-Style-Type" content="text/css">
<meta http-equiv="Content-Script-Type" content="text/javascript">
<meta name="Generator" content="UDO 6.4 PL1 for Linux">
<meta name="Author" content="Dirk Hagedorn">
<link rel="chapter" href="001.html" title="Introduction">
<link rel="chapter" href="opensrc.html" title="Open Source">
<link rel="chapter" href="003.html" title="Installation">
<link rel="chapter" href="004.html" title="Usage">
<link rel="chapter" href="005.html" title="The syntax of UDO">
<link rel="chapter" href="006.html" title="Tips &amp; tricks">
<link rel="section" href="005001.html" title="A short example">
<link rel="section" href="005002.html" title="Basics">
<link rel="section" href="005003.html" title="Structuring">
<link rel="section" href="005004.html" title="Emphasising text">
<link rel="section" href="005005.html" title="Special characters">
<link rel="section" href="005006.html" title="Syllabification">
<link rel="section" href="005007.html" title="Images">
<link rel="section" href="005008.html" title="Hypertext commands">
<link rel="appendix" href="_a.html" title="Frequently asked questions">
<link rel="appendix" href="_b.html" title="Bugs">
<link rel="appendix" href="_c.html" title="Error messages">
<link rel="appendix" href="_d.html" title="This &amp; that">
<link rel="appendix" href="_e.html" title="History">
<link rel="appendix" href="_f.html" title="Command index">
<link rel="start" href="index.html" title="Begin of the document">
<link rel="home" href="index.html" title="Begin of the document">
<link rel="contents" href="index.html#UDOTOC" title="Contents">
<link rel="toc" href="index.html#UDOTOC" title="Contents">
<link rel="first" href="001.html" title="Introduction">
<link rel="prev" href="005008.html" title="Hypertext commands">
<link rel="previous" href="005008.html" title="Hypertext commands">
<link rel="next" href="006.html" title="Tips &amp; tricks">
<link rel="last" href="_f016.html" title="---">
<link rel="copyright" href="aboutudo.html" title="UDO6">
</head>
<body>

<a href="index.html"><img src="udo_hm.gif" alt="Home" border="0" width="24" height="24"></a>
<a href="005.html"><img src="udo_up.gif" alt="The syntax of UDO" border="0" width="24" height="24"></a>
<a href="005008.html"><img src="udo_lf.gif" alt="Hypertext commands" border="0" width="24" height="24"></a>
<a href="006.html"><img src="udo_rg.gif" alt="Tips &amp; tricks" border="0" width="24" height="24"></a>
<hr>
<h1><a name="Miscellaneous">Miscellaneous</a></h1>
<ul class="content">
<li><a href="#Macros">Macros</a></li>
<li><a href="#Definitions">Definitions</a></li>
<li><a href="#Indices">Indices</a></li>
<li><a href="#Special_20commands">Special commands</a></li>
<li><a href="#Split_20documents">Split documents</a></li>
</ul>
<br>
<h3><a name="Macros">Macros</a></h3>
<p>Macros are userdefined placeholders that you can use for different
purposes.
</p>
<p>When using the <i><a href="_f00c.html#UDO__21macro">!macro</a></i> 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.
</p>
<p>Let me show you some examples:
</p>
<blockquote>
<pre><a href="_f00c.html#UDO__21macro">!macro</a> HTML Hypertext Markup Language
<a href="_f00c.html#UDO__21macro">!macro</a> UDO  (!B)U(!b)niversal (!B)Do(!b)cument
<a href="_f00c.html#UDO__21macro">!macro</a> DOSG (!T)UDO6GDOS.ZIP(!t)
<a href="_f00a.html#UDO__21ifdest">!ifdest</a> [html]
  <a href="_f00c.html#UDO__21macro">!macro</a> PICPATH gif/
<a href="_f006.html#UDO__21else">!else</a>
  <a href="_f00c.html#UDO__21macro">!macro</a> PICPATH img/
<a href="_f006.html#UDO__21endif">!endif</a>
[...]
The (!HTML) ...
The (!UDO) Format ...
The archive named (!DOSG) ...
<a href="_f00a.html#UDO__21image">!image</a> (!PICPATH)/tiger
</pre>
</blockquote>
<p>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 <i><a href="_f00a.html#UDO__21include">!include</a></i>.
In the following example a disclaimer is included and the name of the
program is defined by a macro:
</p>
<blockquote>
<pre>[doku.u]
<a href="_f00c.html#UDO__21macro">!macro</a> PRG Windows95
[disclaim.u]
(!PRG) is provided ""as is"" without a
warranty of any kind.
Use it on your own risk.
</pre>
</blockquote>
<br>
<p>Since UDO Release 6 you can call macros with parameters. You can
set the position of the parameters in the <i><a href="_f00c.html#UDO__21macro">!macro</a></i> command by
inserting `<tt>(!1)</tt>', `<tt>(!2)</tt>' till `<tt>(!9)</tt>'. To
call a macro with parameters you have to write brackets (`[...]')
around them.
</p>
<p>The following small example shows how to use a macro for text that
shall be printed in bold-italic style:
</p>
<blockquote>
<pre><a href="_f00c.html#UDO__21macro">!macro</a> BI (!B)(!I)(!1)(!i)(!b)
...
This text is printed (!BI [bold and italic]).
</pre>
</blockquote>
<p>The &quot;(!1)&quot; in the macro line will be replaced by the
words &quot;bold and italic&quot;.
</p>
<br>
<p><b>Please note:</b>
</p>
<ol>
<li> When naming the macros you should be cautious not to use
pre-defined UDO command names like &quot;B&quot; or &quot;nl&quot;. If
you don't you will get problems with bold text ((!B)) or the newline
command (<a href="_f00d.html#UDO__28_21nl_29">(!nl)</a>).
<br>&nbsp;
</li>
<li> You shouldn't use too many macros because every additional macro
slows down the conversion of the source file. The maximum number of
macro is 128.
<br>&nbsp;
</li>
</ol>
<h3><a name="Definitions">Definitions</a></h3>
<p>Like macros definitions are user-defined placeholders. You can use
them to insert special commands inside the text especially for the
destination format.
</p>
<p>The syntax is <tt><a href="_f005.html#UDO__21define">!define</a> &lt;word&gt; <a href="_f001.html#UDO__26lt_3Btext_26gt_3B">&lt;text&gt;</a></tt>. In
contrast to macros <tt><a href="_f001.html#UDO__26lt_3Btext_26gt_3B">&lt;text&gt;</a></tt> will not be converted in a
special way. No special characters are translated inside
<tt><a href="_f001.html#UDO__26lt_3Btext_26gt_3B">&lt;text&gt;</a></tt>.
</p>
<p>In this example I will demonstrate how to print headlines with
HTML:
</p>
<blockquote>
<pre><a href="_f00a.html#UDO__21ifdest">!ifdest</a> [html]
  <a href="_f005.html#UDO__21define">!define</a> H1 &lt;H1&gt;
  <a href="_f005.html#UDO__21define">!define</a> h1 &lt;/H1&gt;
<a href="_f006.html#UDO__21else">!else</a>
  <a href="_f005.html#UDO__21define">!define</a> H1
  <a href="_f005.html#UDO__21define">!define</a> h1
<a href="_f006.html#UDO__21endif">!endif</a>
[...]
(!H1)A headline(!h1)
</pre>
</blockquote>
<br>
<p>As you can see you can use definitions to insert special commands
that aren't supported by UDO. UDO <a href="_e004.html">Release 4</a> offered a lot of special
commands for LaTeX that you now have to simulate with the
<i><a href="_f005.html#UDO__21define">!define</a></i> command:
</p>
<blockquote>
<pre><a href="_f00a.html#UDO__21ifdest">!ifdest</a> [tex]
  <a href="_f005.html#UDO__21define">!define</a> ff &quot;ff
  <a href="_f005.html#UDO__21define">!define</a> nolb3 \nolinebreak[3]
  <a href="_f005.html#UDO__21define">!define</a> lb2 \linebreak[2]
<a href="_f006.html#UDO__21else">!else</a>
  <a href="_f005.html#UDO__21define">!define</a> ff ff
  <a href="_f005.html#UDO__21define">!define</a> nolb3
  <a href="_f005.html#UDO__21define">!define</a> lb2
<a href="_f006.html#UDO__21endif">!endif</a>
[...]
Tell <a href="_f00b.html#UDO__28_21LaTeX_29">(!LaTeX)</a> a good place
(!lb2) for breaking lines.
</pre>
</blockquote>
<br>
<p>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.
</p>
<p>You declare definitions like in the upper example. You can tell
UDO the positions of the parameters by adding `<tt>(!1)</tt>',
`<tt>(!2)</tt>' till `<tt>(!9)</tt>'. When you call a definition you
have to write brackets (`[...]') around the parameters.
</p>
<p>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:
</p>
<blockquote>
<pre><a href="_f00a.html#UDO__21ifdest">!ifdest</a> [html]
  <a href="_f005.html#UDO__21define">!define</a> head &lt;H1&gt;(!1)&lt;/H1&gt;
<a href="_f006.html#UDO__21else">!else</a>
  <a href="_f005.html#UDO__21define">!define</a> head (!1)
<a href="_f006.html#UDO__21endif">!endif</a>
[...]
(!head [A headline])
</pre>
</blockquote>
<p>As you can see in this example you can write format depending
commands UDO doesn't support already.
</p>
<p>The upper LaTeX example can be defined nicer, too. If you use
parameters you can provide all available LaTeX commands in one
definition:
</p>
<blockquote>
<pre><a href="_f00a.html#UDO__21ifdest">!ifdest</a> [tex]
  <a href="_f005.html#UDO__21define">!define</a> lb \linebreak[(!1)]
<a href="_f006.html#UDO__21else">!else</a>
  <a href="_f005.html#UDO__21define">!define</a> lb (!2)
<a href="_f006.html#UDO__21endif">!endif</a>
[...]
Tell <a href="_f00b.html#UDO__28_21LaTeX_29">(!LaTeX)</a> a good place
(!lb [2]) for breaking lines.
</pre>
</blockquote>
<p>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.
</p>
<br>
<p><b>Please note:</b>
</p>
<ol>
<li> Characters of text of the <i><a href="_f005.html#UDO__21define">!define</a></i> command won't be
converted.
<br>&nbsp;
</li>
<li> Characters of the parameters you pass to the definition will be
converted.
<br>&nbsp;
</li>
<li> UDO supports the <i><a href="_f009.html#UDO__21heading">!heading</a></i> command for displaying
headlines. The upper HTML example is only used for demonstration.
<br>&nbsp;
</li>
<li> When naming the definitions you should be cautious not to use
pre-defined UDO command names like &quot;B&quot; or &quot;nl&quot;. If
you don't you will get problems with bold text ((!B)) or the newline
command (<a href="_f00d.html#UDO__28_21nl_29">(!nl)</a>).
<br>&nbsp;
</li>
<li> 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 128.
<br>&nbsp;
</li>
</ol>
<h3><a name="Indices">Indices</a></h3>
<p>To add entries for the index you can use the <i><a href="_f00a.html#UDO__21index">!index</a></i>
command or the <i>(!idx ...)</i> placeholder. You can and should use
these commands as often as possible.
</p>
<p>To add an entry with the <i><a href="_f00a.html#UDO__21index">!index</a></i> command use it this way:
</p>
<blockquote>
<pre><a href="_f00a.html#UDO__21index">!index</a> Index entry
</pre>
</blockquote>
<p>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.
</p>
<p>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.
</p>
<p>If you think that a reader might look for &quot;Index entry&quot;
or &quot;Entry, Index&quot; you should use the following index
commands:
</p>
<blockquote>
<pre><a href="_f00a.html#UDO__21index">!index</a> Index entries
<a href="_f00a.html#UDO__21index">!index</a> Entry <a href="_f016.html#UDO__21_21">!!</a> Index
</pre>
</blockquote>
<br>
<p>If you use the placeholder <i>(!idx ...)</i> you can use up to
four parameters. The following examples show how the commands are
converted for LaTeX, Windows Help and RTF:
</p>
<blockquote>
<pre>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
</pre>
</blockquote>
<br>
<p><b>Please note:</b>
</p>
<ol>
<li> The conversion of these index commands can be suppressed with the
switch <i><a href="_f00d.html#UDO__21no_index">!no_index</a></i> inside the preamble.
<br>&nbsp;
</li>
<li> Chapter names, labels and aliases aren't added to the index in no
destination format. But you can automatize this with the following
switches: <i><a href="_f012.html#UDO__21use_nodes_inside_index">!use_nodes_inside_index</a></i>,
<i><a href="_f012.html#UDO__21use_label_inside_index">!use_label_inside_index</a></i> and <i><a href="_f012.html#UDO__21use_alias_inside_index">!use_alias_inside_index</a></i>.
<br>&nbsp;
</li>
<li> If a chapter contains the command <i><a href="_f00a.html#UDO__21ignore_index">!ignore_index</a></i> the
chapter name won't be added to the index even if you use the switch
<i><a href="_f012.html#UDO__21use_nodes_inside_index">!use_nodes_inside_index</a></i> inside the preamble of your source
file.
<br>&nbsp;
</li>
<li> If you convert to LaTeX and you use <i><a href="_f00a.html#UDO__21index">!index</a></i> commands
inside your source file UDO will add the commands that are necessary
for &quot;Makeindex&quot; automatically. <a href="005005.html">Special characters</a> of an
index entry are converted especially for &quot;Makeindex&quot;.
<br>&nbsp;
</li>
<li> You have to use the parameters inside brackets. If you want to
use a bracket inside a parameter you have to insert a `!'. If you
don't UDO will think that the placeholder ended. An example:
<br>&nbsp;
<blockquote>
<pre>wrong:  (!idx [Copyright (c) 1995] )
right:  (!idx [Copyright (c!) 1995] )
</pre>
</blockquote>
</li>
</ol>
<h3><a name="Special_20commands">Special commands</a></h3>
<p>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).
</p>
<p>You have to use abbreviations of the destination formates if you
want to use these special commands:
</p>
<table>
<tr><td nowrap valign="top">asc</td><td valign="top"> ASCII
</td></tr>
<tr><td nowrap valign="top">aqv</td><td valign="top"> Apple QuickView
</td></tr>
<tr><td nowrap valign="top">htag</td><td valign="top"> HP Helptag SGML
</td></tr>
<tr><td nowrap valign="top">html</td><td valign="top"> HTML
</td></tr>
<tr><td nowrap valign="top">info</td><td valign="top"> Texinfo
</td></tr>
<tr><td nowrap valign="top">ldoc</td><td valign="top"> Linuxdoc-SGML
</td></tr>
<tr><td nowrap valign="top">lyx</td><td valign="top"> LyX
</td></tr>
<tr><td nowrap valign="top">man</td><td valign="top"> Manualpage
</td></tr>
<tr><td nowrap valign="top">pch</td><td valign="top"> Pure C Help
</td></tr>
<tr><td nowrap valign="top">pdf</td><td valign="top"> PDF
</td></tr>
<tr><td nowrap valign="top">rtf</td><td valign="top"> RTF
</td></tr>
<tr><td nowrap valign="top">stg</td><td valign="top"> ST-Guide
</td></tr>
<tr><td nowrap valign="top">tex</td><td valign="top"> LaTeX
</td></tr>
<tr><td nowrap valign="top">tvh</td><td valign="top"> Turbo Vision Help
</td></tr>
<tr><td nowrap valign="top">win</td><td valign="top"> Windows Help
</td></tr></table>
<p>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.
</p>
<p>The next example shows how to insert a line that will only be
printed for the ASCII format:
</p>
<blockquote>
<pre>!asc This line appears only in ASCII.
</pre>
</blockquote>
<p>The next example shows how to insert a line that appears in all
formats except ASCII:
</p>
<blockquote>
<pre>!=asc This line doesn't appear in ASCII.
</pre>
</blockquote>
<p>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!
</p>
<p>You can use these commands to insert special commands like parts
of the preamble for LaTeX:
</p>
<blockquote>
<pre>!tex \documentstyle[11pt,makeidx]{article}
!tex \makeindex
[...]
!tex \printindex
</pre>
</blockquote>
<a name="raw_20environment"></a>
<h3>The raw environment</h3>
<p>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.
</p>
<p>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:
</p>
<blockquote>
<pre><a href="_f00a.html#UDO__21ifdest">!ifdest</a> [html]
<a href="_f003.html#UDO__21begin_raw">!begin_raw</a>
&lt;FORM method=post action=&quot;mailto:DirkHage@aol.com&quot;&gt;
&lt;PRE&gt;
&lt;p&gt;    Name:  &lt;INPUT name=&quot;Name&quot; size=60&gt;
&lt;p&gt;
&lt;p&gt;           &lt;INPUT type=submit value=&quot;Send&quot;&gt;
&lt;p&gt;           &lt;INPUT type=reset value=&quot;Reset&quot;&gt;
&lt;/PRE&gt;
&lt;/FORM&gt;
<a href="_f006.html#UDO__21end_raw">!end_raw</a>
<a href="_f006.html#UDO__21else">!else</a>
The HTML version will display a form here.
<a href="_f006.html#UDO__21endif">!endif</a>
</pre>
</blockquote>
<p>To say it once more: Text that is part of a raw environment is
printed &quot;as is&quot;. That means that it's not converted and not
indented. If you will insert the upper form source code into a
<a href="005004.html#verbatim_20environment">verbatim environment</a> you will see the source code in an HTML browser.
But if you insert it inside a raw environment you will see the form!
</p>
<h3><a name="Split_20documents">Split documents</a></h3>
<p>UDO offers you the commands <i><a href="_f00a.html#UDO__21include">!include</a></i>, <i><a href="_f013.html#UDO__21vinclude">!vinclude</a></i>
and <i><a href="_f00f.html#UDO__21rinclude">!rinclude</a></i>. 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.
</p>
<p>This documentation uses this commands intensively. The file
<tt>udo.u</tt> 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.
</p>
<p>You can use <i><a href="_f00a.html#UDO__21include">!include</a></i> wherever you want. So you can define
macros, definitions or syllabification patterns in external files that
can be used by other files, too.
</p>
<p>For displaying the preformatted contents of a file you can use the
<i><a href="_f013.html#UDO__21vinclude">!vinclude</a></i> command (&quot;verbatim include&quot;). You can use
this command e.g. for displaying source files or header files.
</p>
<p>If you want to included special commands for a destination format
like difficult tables for LaTeX or HTML you can use the
<i><a href="_f00f.html#UDO__21rinclude">!rinclude</a></i> command (&quot;raw include&quot;).
</p>
<p><b>Possible examples of use:</b>
</p>
<ol>
<li> When writing large source files you can edit a separate file for
each chapter that are included by a main file with <i><a href="_f00a.html#UDO__21include">!include</a></i>.
Thus you can restructure your text by simply moving one line of the
main file.
<br>&nbsp;
</li>
<li> If you split up your text into several file that are included by
a main file you can speed up looking for errors because you can simply
switch off some parts of the text by commenting out one line of the
main file.
<br>&nbsp;
</li>
<li> Together with macros you can write standardized texts that you
can use for many projects. E.g. you can edit a standard disclaimer
where the name of the software is replaced by macros that are defined
by the main file.
<br>&nbsp;
</li>
<li> A documentation can be written by different persons. Each author
can test his own file with UDO. If everybody has finished his work all
files will be included by a main file.
<br>&nbsp;
</li>
<li> With <i><a href="_f013.html#UDO__21vinclude">!vinclude</a></i> and <i><a href="_f011.html#UDO__21tabwidth">!tabwidth</a></i> you can add source
code to your documentation. This is great for a documentation of a
source code or a library.
<br>&nbsp;
</li>
</ol>
<hr>
<a href="index.html"><img src="udo_hm.gif" alt="Home" border="0" width="24" height="24"></a>
<a href="005.html"><img src="udo_up.gif" alt="The syntax of UDO" border="0" width="24" height="24"></a>
<a href="005008.html"><img src="udo_lf.gif" alt="Hypertext commands" border="0" width="24" height="24"></a>
<a href="006.html"><img src="udo_rg.gif" alt="Tips &amp; tricks" border="0" width="24" height="24"></a>
</body></html>
udo-doc-en 6.4.1-1 / usr / share / doc / udo-doc-en / html / 005009.html
