                             The guide to

                                 UDO

                        Release 6 Patchlevel 0
                           January 3rd 1997

                                  by

                            Dirk Hagedorn
                              Asmecke 1
                            59846 Sundern
                               Germany

                      Internet: DirkHage@aol.com
                     MausNet: Dirk Hagedorn @ MK2



======================================================================
Contents
======================================================================

 1  Introduction
    1.1  Preface
    1.2  What UDO can('t) do for you
    1.3  Do you need UDO?
    1.4  Once upon a time
    1.5  Contact addresses
    1.6  Thanks

 2  Legal information
    2.1  Copyright
    2.2  Disclaimer
    2.3  Trademarks

 3  Money, money, money
    3.1  Shareware
    3.2  How much does UDO cost?
    3.3  How much do upgrades cost?
    3.4  Registration
    3.5  Registration in Great Britain

 4  Installation
    4.1  Installing the Atari version
    4.2  Installing the DOS version
    4.3  Installing the Macintosh version
    4.4  Installing the Unix versions

 5  Usage
    5.1  Command line version
    5.2  GEM version
    5.3  Macintosh version
    5.4  UDO Shell for Windows

 6  The syntax of UDO
    6.1  A short example
    6.2  Basics
    6.3  Structuring
    6.4  Emphasising text
    6.5  Special characters
    6.6  Syllabification
    6.7  Images
    6.8  Hypertext commands
    6.9  Miscellaneous

 7  Tips & tricks
    7.1  Seven rules for writing UDO source files
    7.2  General tips & tricks
    7.3  Tips & tricks according to LaTeX
    7.4  Tips & tricks according to ST-Guide
    7.5  Tips & tricks concerning Windows Help

Appendix
========

 A  Frequently asked questions
    A.1  General questions
    A.2  Questions concerning ASCII
    A.3  Questions concerning HTML
    A.4  Questions concerning manpages
    A.5  Questions concerning LaTeX
    A.6  Questions concerning Linuxdoc-SGML
    A.7  Questions concerning Pure C Help
    A.8  Questions concerning the Rich Text Format
    A.9  Questions concerning ST-Guide
    A.10  Questions concerning Texinfo
    A.11  Questions concerning Turbo Vision Help
    A.12  Questions concerning Windows Help

 B  Bugs

 C  Error messages

 D  This & that
    D.1  Facts, facts, facts
    D.2  Programming environment
    D.3  Generated files

 E  History
    E.1  Last minute changes
    E.2  Release 6
    E.3  Release 5
    E.4  Release 4
    E.5  Release 3

 F  Command index
    F.1  A...
    F.2  B...
    F.3  C...
    F.4  D...
    F.5  E...
    F.6  F...
    F.7  G...
    F.8  H...
    F.9  I...
    F.10  L...
    F.11  M...
    F.12  N...
    F.13  O...
    F.14  P...
    F.15  R...
    F.16  S...
    F.17  T...
    F.18  U...
    F.19  V...
    F.20  W...
    F.21  X...
    F.22  *...



======================================================================
Chapter 1

Introduction
======================================================================


1.1  Preface
============

Welcome to UDO!

You are  reading  the  revised  documentation  of  the revised program
called UDO written by a quite overworked author that still  is  hoping
that  anybody  outside there understands his quite unrevised knowledge
of writing English documentations.

UDO is a powerful and multipurpose utility for making a  documentation
or  any  other  text  file  that is needed in one text format or more.
Though UDO is powerful it's quite easy to understand and to use.

If you take a look at the size of this documentation you  will  notice
immediately that UDO has to be quite powerful. Many users get deterred
of the size of this documentation and try to use  UDO  without  having
read  it.  Unfortunately,  exactly  these  people  will  ask  lots  of
questions later on without  knowing  that  their  questions  could  be
answered by simply reading this documentation.

Due to this fact I want to note at the beginning of this documentation
that you will only be able to use UDO in an efficient way if you  read
the  complete  documentation  one  time at least and if you experiment
with the added examples.

Please take some time, sit down, take a cup of tea or coffee and  read
this  documentation  from  the beginning to the end. You don't have to
learn everything by heart but  you  should  be  able  to  find  things
quickly if there will be questions later on.

If you  will  detect  parts where things are described in a too short,
wrong or misleading way: please let me know! UDO is "my little  child"
and  it  wouldn't  be  the  first time that an author has forgotten to
describe some important parts.

And if you have any problems with my English: please let me know, too!
I  did  what I can but you without any doubts you will find some awful
parts.

 Please note that UDO is Shareware. I have been spending a lot of my
 spare time for this project. If you want to use UDO please register
                               for it.

I hope that UDO will become an unrenounceable utility for you and  you
will have more time for the really important things.

Dirk Hagedorn

Sundern, December 10th 1996


1.2  What UDO can('t) do for you
================================

UDO has  been  originally developed to make it easier for you to write
software documentations or other kinds of text files that have  to  be
available in more than one format.

UDO can  be  a  great  help  if  you want to make a single destination
format, too. A beginner will have less problems when learning the  UDO
syntax instead of learning LaTeX or HTML. So if you want to make LaTeX
or HTML files it should be easier to get to  know  how  to  make  them
using  UDO  instead of writing them on your own. When writing LaTeX or
HTML files you have to keep attention not to use any of their  special
command  characters.  In  comparison  to  that  UDO will convert these
special characters for you when converting the source file to LaTeX or
HTML. But this is not the only thing UDO can do for you.

UDO is  a  multilingual program. You can make German, English, French,
Italian  and  Swedish  texts.  UDO  knows  how  "Table  of  contents",
"Appendix",  "Figure" or "Table" is called in the other countries. The
date is also printed out in the right way  depended  of  the  selected
language.

The syntax  of UDO is easy to learn. To make some small documentations
you just have to learn about ten to fifteen commands; as many  as  you
have to learn when you try to learn LaTeX or HTML.

When you  have  written an UDO source file you can convert it into the
following formats:

  1. Apple QuickView
  2. ASCII
  3. HTML (Hypertext Markup Language)
  4. LaTeX 2.09, LaTeX2e
  5. Linuxdoc-SGML
  6. LyX
  7. Manualpage
  8. NROFF
  9. Pure C Help
 10. RTF (Rich Text Format)
 11. Source code (C and Pascal)
 12. ST-Guide
 13. Texinfo
 14. Turbo Vision Help
 15. Windows Help

As you  can  see  some  formats  are  just  interesting  for  specific
operating  systems,  but  you can also see that the list contains come
formats that can be used on nearly any existing operating system.

In most cases UDO doesn't make files that are  ready  to  use  because
have to run a further software to view, print or convert the document.
E.g. you have to convert the Windows Help source file (saved  by  UDO)
with  the  Microsoft Help Compiler HC.EXE into a Windows Help file. Or
you have to import the RTF file into a text processor to print it.


UDO tries to help the author of a documentation as much  as  possible.
Next  to the conversion into the destination format UDO offers you the
following features:

    automatically generated title pages,  tables  of  contents,  head
     lines and bottom lines,
    chapter numbering,
    tables,
    automatically generated hypertext links,
    support for different text styles,
    automatic conversion of umlauts and other special characters,
    a  large  variety  of  layout commands for making lists, enumera-
     tions, descriptions, justified text, centred or indented text  or
     text with a right alignment,
    image support,
    automatic line breaks with a half-automatic syllabification.


UDO is  not  the perfect program for all purposes. The conversion into
ASCII, ST-Guide, HTML, LaTeX and Windows Help is nearly perfect.  Some
formats  (like Linuxdoc-SGML and LyX) are quite young and haven't been
tested enough. You will surely find  some  aspects  that  have  to  be
changed in the near future.

There are  some points that UDO can't manage yet but will be implemen-
ted in the very near future: a automatically generated index, list  of
figures and list of tables. Just wait some months and you will get UDO
Release 7 with all these features.


To make complex files like newspapers  that  is  impossible  with  UDO
because  it can't wrap text around images and it can't generated files
with two or more text columns. In addition to that UDO hasn't  got  an
implemented automatic syllabification.

UDO is  just  a  "one way" converter. UDO can't convert LaTeX, HTML or
RTF to the UDO format. It is only able to convert the UDO format  into
LaTeX etc. Maybe there will be a HTML2UDO or SGML2UDO converter in the
near future.

To sum it up it can be said that UDO can't manage the following things
and won't be able to manage them in the future:

  1. UDO  can only convert its format into the upper standing formats.
     UDO can't convert them into its own format. Maybe there  will  be
     some other converters in the near future.
  2. UDO  can't  make  binary formats (like WinWord documents). It can
     only make make formats that are based on ASCII.
  3. UDO doesn't support an automatic  syllabification.  You  have  to
     tell  UDO  explicitely  where  it is allowed to split up words. I
     don't want to  implement  an  automatic  syllabification  because
     there are only some formats that would profit from it.
  4. UDO  can't wrap text around images. UDO can't save multi-columned
     texts, too. These functions are part of  desktop  publishing  and
     not of a software like UDO.


1.3  Do you need UDO?
=====================

If you can answer one or more of the following question with "Yes" UDO
should be worth to take a look at. If can't answer any  question  with
"Yes"  it's  quite  possible  that you don't need UDO and that you can
stop reading this manual right here.

    Have you written a text with a general contents and do  you  want
     to  let  some  people,  that don't run the same operating system,
     read it?

    Are you a programmer and do you want to distribute your  software
     with  an  ASCII  manual  and  an online manual for Windows, Turbo
     Vision, GNU Info or ST-Guide?

    Are you a programmer and do you want to print out the manual with
     LaTeX or a text processor that can import the Rich Text Format?

    Do  you  only  need  an  ASCII  manual  but you always get rid of
     checking the line  breaks,  chapter  numbers  and  the  table  of
     contents?

    Do  you want to publish a hypertext inside the World Wide Web but
     you don't own a  powerful  HTML  editor  that  can  enter  links,
     convert   special  characters  or  split  up  the  document  into
     different files automatically?

    Do you want to make an online manual for a Windows  software  but
     you  don't  want  to pay a lot of money for a software that costs
     more than 20 times the price of UDO but can do only a little  bit
     more?

    Are  you  the  author of a Pure C library for the Atari computers
     and you need a descriptions of the library routines  for  Pure  C
     Help and ST-Guide?

Did you  answer  any  question with "Yes"? Fine! You didn't? Then read
the questions once more. ;-)


1.4  Once upon a time
=====================

It was autumn 1994 when I wrote  some  little  programs  for  which  I
needed an ASCII manual, an online help and a printed documentation.

In all  cases  I  began  writing  the  ASCII manual. In a copy of it I
inserted hypertext commands. Finally the  ASCII  manual  was  imported
into  a  text  processor,  layouted and printed. It didn't take a long
time for me to recognize that this was an inefficient work:  if  there
were any changes in one of the files both the others had to be changed
in the same way. And if there were lots of changes it was necessary to
start the whole procedure right from the beginning.

When I  finished  these  manuals I said to myself: "Oh no, Dirk, there
must be another and easier way to get different versions of  one  text
file!".

January 1995  I  started  to  think  about  a new text format with the
project name "UDO" (as the abbreviation for Universal  DOcument).  The
UDO  syntax  should  be  easy  to  learn  and flexible enough and so I
decided to create a syntax like LaTeX. Next to this  I  began  writing
the software that was able to convert this new text format into ASCII,
ST-Guide and LaTeX: UDO was born!

At this time UDO was really a small program with only  some  features.
The  syntax  contained about 10 commands and the source code was about
10 KB large. Nevertheless this small hack was  of  a  great  help  for
myself and the upper described horror scenario was history.

Since this  time  UDO has been growing up day by day. UDO now supports
many different text formats, it offers a large  variety  of  layouting
commands,  it's  available for different operating system and the size
of its source code and documentation is now  a  hundred  times  larger
than it was in former days.

In these  two years UDO has become to an operating system independent,
very powerful and - proverbially said - universal tool.


1.5  Contact addresses
======================

If you want to register UDO, if you want have questions, if  you  want
to  make  any suggestions or if you want to report bugs please use one
of the following addresses. If possible contact me via email.

 Address:        Dirk Hagedorn
                 Asmecke 1
                 59846 Sundern
                 Germany

 Telephone/Fax:  +49 2933 77979

 MausNet:        Dirk Hagedorn @ MK2 (no mails > 16 KB)

 Internet:       DirkHage@aol.com

 World Wide Web: http://members.aol.com/DirkHage/www/index.htm


1.6  Thanks
===========

At this point I want to  say  "Thank  you"  to  the  following  people
because  of  their  effective  help. Without this help UDO wouldn't be
like it is today.

Thank you

 Denesh Bhabuta for supporting UDO in Great Britain

 Alexander Clauss for compiling the HP-UX 300/400 version

 Dirk Haun, one of the fathers of UDO

 Patrick Jerchel for managing the mailing list

 Peter Klasen, the first registered user of UDO

 Martin Loos for managing the old mailing list

 Martin Osieka for porting UDO to MacOS

 Rainer Riedl for compiling the BeOS version

 Tom Thomasson for supporting UDO in Sweden

In addition to that I want  to  thank  all  users  of  UDO  for  their
indefatigable efforts to make UDO better and better.



======================================================================
Chapter 2

Legal information
======================================================================


2.1  Copyright
==============

UDO and  its  documentation are copyrighted by Dirk Hagedorn, Sundern,
Germany.

UDO is distributed as shareware and may be copied to third persons  in
a noncommercial way if all the following requirements are met:

    You have to copy the software with all and unchanged files.

    You  have to copy the software free of charge. Uploading UDO to a
     noncommercial BBS or FTP server is allowed.

    You aren't allowed to add files to the archives  e.g.  advertise-
     ments  for  a BBS or for Public Domain series. You aren't allowed
     to rename the archives  or  to  to  compress  them  with  another
     archiver.

    If  you want to distribute UDO via Public Domain floppy discs you
     may do this only if the price of a single floppy  disc  is  lower
     than  5  Pounds  Sterling,  6 $US and 10 DM (or the same value in
     another currency).

    If you want to distribute UDO via CD-ROM you may do this only, if
     I,  Dirk  Hagedorn, will get a copy of this CD-ROM free of charge
     and the if the CD-ROM will  be  published  before  December  31st
     1997.  I  want to avoid that old versions of UDO are still copied
     even if there are out of date. If you  read  this  text  1998  or
     later  please  contact  me  to  get  to know if there's a younger
     version existing!


2.2  Disclaimer
===============

Though UDO has been developed thoroughly and has  been  tested  for  a
long  period  of  time  there  is  no  warranty for the program or the
contents of this documentation.

UDO is provided "as is" without warranty of any  kind,  including  but
not  limited to, the implied warranties of merchantability and fitness
for a particular purpose. The entire risk  is  with  you.  Should  UDO
prove defective you assume the cost of all necessary servicing, repair
or correction.

Nevertheless the author will be glad if you send him bug reports.


2.3  Trademarks
===============

This documentation uses names of products and companies  that  may  be
trademarks  or  registered trademarks. You may not conclude that these
names are free of use even if they are not marked explicitly.

Atari, TOS and MultiTOS are trademarks  or  registered  trademarks  of
Atari Corporation.

Arial and  Times  New  Roman  are  registered  trademarks  of Monotype
Corporation PLC.

GEM and GEM Desktop are trademarks or registered trademarks of Digital
Research.

Mac, Macintosh  and  MacOS are registered trademarks of Apple Computer
Inc.

MS-DOS, Windows, Windows 95 and Windows NT are  registered  trademarks
of Microsoft Corporation.

Unix is a registered trademark of X/Open Company Ltd.



======================================================================
Chapter 3

Money, money, money
======================================================================


3.1  Shareware
==============

UDO is distributed as shareware. This means:

    You are allowed to check for exactly four weeks if UDO meets your
     requirements!

    It's forbidden to publish any text you have made with UDO  during
     this trial period.

    After  the  trial period of four weeks you have to decide whether
     you want to buy UDO (see "Registration") or if you don't want  to
     use  it. If you don't want to buy UDO you are obligated to delete
     UDO and all its additional files from  your  hard  disc.  If  you
     don't you will work with a black copy of UDO!

If I will get less registrations than I expect I...

  1. ...will increase the number of limitations (e.g. limited document
     sizes, exchanged characters in the destination file or ugly speed
     limitations), or I...

  2. ...won't  publish  further  versions of UDO and give them only to
     registered users, or I...

  3. ...will stop going on developing UDO.

That's no joke! In the past I was often disappointed due to the amount
of  registrations  I got for other software of mine. Please believe me
that I cannot laugh anymore about users that are too lazy to  pay  for
shareware.

In former  versions  UDO  didn't  have any limitations. But due to the
unsatisfying  resonance  from  Unix  and  DOS  users   I   implemented
limitations in all UDO versions:

  1. UDO will print an ugly message at the end of every page.

  2. The  switch  !use_about_udo is set automatically for all destina-
     tion formats.

When you have paid the shareware  fee  you  will  get  a  personalised
keycode.  With  this  keycode  you  will  be  able  to  disable  these
limitations.


3.2  How much does UDO cost?
============================

You can believe me that I have thought very long about  the  price  of
UDO. So please read this section until the end.

I don't  want  to tell you the price I would have to demand because it
is higher than an averaged user wants to pay for  shareware  nowadays.
But I think that the current price of UDO is a good compromise between
"dream and reality". I hope that it's fair enough for you and  UDO  is
worth paying this amount of money.

The height  of  the  shareware fee depends on your status, whether you
want to use UDO for private, commercial or educational purposes:


The price for private users
===========================

The shareware fee for a systemwide licence of UDO for private users is
50 DM (35 $US, 25 Pounds Sterling, 40 SFR, 350 S, 55 NFL, 150 FF).

You are  a  private user if you make documentations or other texts for
products that cost less than  100 DM  (70  $US,  50  Pounds  Sterling,
80 SFR, 700 S, 110 NFL, 34 FF). Thus all authors that are programming
only freeware, public domain or shareware that cost less  than  100 DM
are private users.

Private users   have  to  pay  the  shareware  only  once.  After  the
registration private users are allowed to use  UDO  simultaneously  on
any operating system UDO is available for.

If you  recognize that you are a commercial user after having paid the
shareware fee for private users you are forced to pay the difference!


The price for commercial users
==============================

The shareware fee for a single licence of UDO for commercial users  is
150 DM (100 $US,   75  Pounds  Sterling,  120 SFR,  1050 S,  165 NFL,
450 FF). "Single licence" means that UDO may only be installed on  one
computer that isn't connected to any kind of network.

If you  want  to use UDO on several computers or in a network you have
to  buy  additional  licences  for  any  additional  working   places.
Additional  licences  costs  50 DM each  (35 $US,  25 Pounds Sterling,
40 SFR, 350 S, 55 NFL,  150 FF).  You  have  to  guarantee  that  the
maximum  number  of  users  of UDO cannot be higher than the amount of
licences you have bought.

If you need 20 or more licences you can ask me for a special price for
your specific needs.

A commercial  user is who uses UDO for writing documentations or other
texts for one or more products that cost more than 100 DM (70 $US,  50
Pounds Sterling, 80 SFR, 700 S, 110 NFL, 34 FF).

Companies, enterprises and other commercial oriented institutions that
use UDO for internal purposes are commercial users, too.


The price for schools and universities
======================================

I offer special prices for schools, universities and other educational
institutions.  Please  ask  me  for the price for the amount of needed
licences.

Please note:

  1. All prices are inclusive value-added tax.

  2. After having paid the shareware fee you will receive  an  invoice
     and a personalized keycode. With this keycode you will be able to
     disable the limitations of the shareware version.

  3. If you think (like myself) that UDO is worth more than the  upper
     shown prices, don't hesitate to pay more.


A last request...
=================

Dear private users, if you want to use UDO without any twinges at your
working place, please try to convince your boss or any other  superior
to buy one ore more licences of UDO.

The low  price  of UDO can be afforded by really every company and can
be completely depreciated.

Every additional income can help me to cover  my  costs  payments  for
books,  compilers  and  telephone/modem  calls. And you can believe me
that these costs aren't low due to the size of this project.


3.3  How much do upgrades cost?
===============================

You have to pay an upgrade fee for upgrading an  old  release  to  the
current one.

The height  of  this  upgrade  fee  depends  on which release you have
currently  registered  and  if  you  are  a  private,  commercial   or
"educational"  user.  The  following  table  shows the upgrade fees in
Deutsche Mark. The second table shows you  the  equivalent  values  in
your currency.


     from           to        | Private | Commercial | Education 
    --------------------------+---------+------------+-----------
     Release 3      Release 6 |   15 DM |   50/10 DM |        -- 
     Release 4      Release 6 |   10 DM |   30/10 DM |        -- 
     Rel. 5 (1996)  Release 6 |    0 DM |       0 DM |      0 DM 
     Rel. 5 (1997)  Release 6 |   10 DM |   50/10 DM |  50/10 DM 


               DM | $US | Pounds | sFR |  S | nFL  FF  
              ----+-----+--------+-----+-----+----------
               10 |   7 |      5 |  13 |  70 |  11  30  
               15 |  10 |      8 |  20 | 105 |  17  45  
               30 |  20 |     15 |  40 | 210 |  34  60  
               50 |  35 |     25 |  65 | 350 |  56  150 

If you have registered UDO Release 5 in 1996 you don't have to pay any
upgrade fee. The new keycodes will be sent to  you  on  demand  (email
preferred).

If you have registered UDO Release 5 in 1997 or later you will have to
pay the upgrade fees listed in the table in the row labelled  "Rel.  5
(1997)".

The values in the columns for commercial and educational users are the
upgrade fees  for  the  first  licence  (left  value)  and  additional
licences (right value).


3.4  Registration
=================

The height of the shareware or upgrade fee depends on your status. How
much money you have to pay you will find in "How much does UDO  cost?"
and "How much do upgrades cost?".

Users from  Great  Britain  are recommended to register UDO via Denesh
Bhabuta. Users from Sweden are recommended to  register  UDO  via  Tom
Thomasson.

The appropriate  amount  of  money  can be paid by sending a cheque, a
Eurocheque or cash or by transferring the amount of money to  my  bank
account.

If you  really want to risk to send cash please send Deutsche Mark and
insert a black piece of paper into the envelope  so  nobody  can  look
inside gets the idea to steal the letter.

Please send cheques, Eurocheques or cash to:

     Dirk Hagedorn
     Asmecke 1
     59846 Sundern
     Deutschland

If you  prefer  transferring  the  money  to my bank account use these
data:

      Account holder: Dirk Hagedorn
      Account number: 3 561 164
      Bank:           Sparkasse Arnsberg-Sundern, Germany
      Bank code:      466 500 05

In all cases please don't forget to send me

    your name
    your complete address
    your email address (if available)
    on which operating system(s) you want to use UDO

After having received  the  money  I  will  send  you  a  bill  and  a
personalized keycode. With the keycode you can disable the limitations
of the shareware version.


Services for registered users
-----------------------------

New releases of UDO are released  two  or  three  times  per  year  at
maximum.  Registered users are enabled to use current beta versions at
any time.

Because UDO is available for many operating systems and I  don't  have
so  much  time to compile new release every time I change some things,
new releases will be published only if the number of changes  is  high
enough.

For registered  users  after  about  two  weeks  updated  versions are
published. In these  version  old  bugs  are  fixed,  new  destination
formats are presented and wishes of registered users are considered if
they may be realised.

Registered users can download these updates via modem or FTP  or  they
can  order  them  by sending a formated floppy disk with a readdressed
envelope and 2 DM for stamps.

It goes without saying that registered users will get  gratis  support
via  via  (e)mail.  Questions  of registered users will be answered as
detailed as possible.


3.5  Registration in Great Britain
==================================

It's recommended that British users register UDO via  Denesh  Bhabuta.
Users from outside Great Britain should register UDO directly via Dirk
Hagedorn.

The shareware fee depends on your status. How much money you  have  to
pay  you  will  find  in  "How  much  does  UDO cost?" or "How much do
upgrades cost?".

To register UDO via Denesh Bhabuta please  send  a  cheque  or  postal
order  for  the  appropriate  amount made payable to "Denesh Bhabuta".
Denesh also accepts Eurocheques and International  Money  Orders  made
payable to him. Send this along with your full address, e-mail address
and a short note which version of UDO on which  operating  system  you
are using to

 Address: Denesh Bhabuta
          CyberSTrider
          203 Parr Lane
          Bury
          BL9 8JW

 E-Mail:  dbhabuta@cix.compulink.co.uk
          danny@micros.hensa.ac.uk
          dbhabuta@mag-net.co.uk

When you register, you are entitled to

    Master Disk with latest version(s) of UDO

    Keycode to register this versions of UDO

    E-mail, snail-mail and telephone support

    Free  update  service  (as  long  as  the  fee doesn't rise or it
     becomes commercial)

Your keycode will initially be sent by e-mail if possible.  Users  who
register  via  Denesh  are  entitled  to this service. To receive free
updates, please send a blank unlabelled floppy  disk  with  a  stamped
self addressed envelope to the above address.



======================================================================
Chapter 4

Installation
======================================================================


4.1  Installing the Atari version
=================================

To install  UDO  onto  an  Atari  or onto a computer with a compatible
operating system (e.g. MagiCMac, MagiC-PC, GEMulator)  just  copy  all
files to a directory that should be named "UDO".

The GEM  version  should  be the application for files with the suffix
`*.u*' so you shall do the neccessary changes in your desktop (Gemini,
Thing, Ease, Magxdesk, ...).

If you  prefer  the TTP version and you are using a command line shell
(e.g. Mupfel by Stefan Eissing) copy or move `udo.ttp' to one  of  the
directories that is part of $PATH (e.g. `\usr\bin').

If you  have  installed  the  ST-Guide  you  should copy or move UDO's
hypertext (udo6eng.hyp and udo6eng.ref) to the directory that contains
all your other hypertexts.

That's all.


4.2  Installing the DOS version
===============================

You need  a  80386  processor  at least to run UDO. UDO doesn't run on
80286 processors or processors of an older type and  I  won't  compile
versions for these old dinosaurs.

If you  find  a  program  or  batch file named SETUP or INSTALL in the
archive please start it and follow the instructions. If the  installa-
tion fails, please go on reading this chapter.

It failed? Ah, you haven't tested it yet? That's fine that you want to
read all the text before you want to experiment. ;-)

Unfortunately the installation of the DOS version is not trivial.  Er,
I  think  it  is trivial but the experiences of the past have shown me
that lots of people have problems installing UDO on a DOS PC  although
the installation is very simple.

If you  haven't  heard anything of RSX and EMXRT until now I recommend
to read the following two chapters completely. If UDO still refuses to
run you have done something wrong or I haven't described the installa-
tion process detailed enough.

If you already know what RSX and EMXRT are good for, because  you  are
using emTeX or the GNU utilities) you can skip the next chapter.


4.2.1  Installation of RSX and EMXRT
------------------------------------

OK, you  haven't  heard  anything  of  RSX and EMXRT yet. That's not a
shame. But if you won't know what RSX and EMXRT  are  good  for  after
having  read this chapter, you should feel ashamed. And if some RSX or
EMXRT experts recognize some stupid stuff I should feel ashamed.

Well, let's go...

UDO was compiled with the GNU C Compiler (GCC), strictly speaking with
EMX-GCC (ported by Eberhard Mattes). GCC is originally a Unix software
and Unix has always used 32 bit software. Thus, the EMX-GCC  makes  32
bit  software,  too. And now we have a problem, because you cannot run
32 bit software with DOS without using any tricks.

EMXRT and RSX are responsible for these tricks. These "drivers"  allow
UDO  to  allocate  huge  blocks  of  memory.  Because  you have to use
different tricks for DOS and Windows there are existing two  different
"drivers": EMXRT for DOS and OS/2, RSX for Windows.

Please note:

    For running UDO exclusively in a DOS box with Windows 3.11/95 you
     will need only RSX. RSX, written by Rainer Schnitker, is  a  DPMI
     server for programs that were compiled with EMX-GCC or DJGPP.

    For  running  UDO  under  OS/2  or exclusively under DOS (without
     Windows) you will need only EMXRT. EMXRT ("emx  runtime  environ-
     ment"), written by Eberhard Mattes, is needed for running EMX-GCC
     compiled software.

    If you don't install neither RSX  nor  EMXRT  there  will  be  no
     chance to run UDO. It will simply print an error message.

    The  installation of RSX and EMXRT is very easy. Just extract the
     archives with paths and enter two lines into the AUTOEXEC.BAT.

    RSX and EMXRT are  no  resident  drivers.  UDO  will  start  them
     automatically. After UDO has finished the drivers terminate, too.

    If  you  haven't  received  the drivers (you haven't EMXRT.ZIP or
     DPMIGCC5.ZIP/RSX503RT.ZIP)  and  the  UDO  distribution   doesn't
     contain  the  archives  you  can download them or you can request
     them by mail:

      FTP:   Current version of EMXRT can be downloaded from ftp.uni-
             stuttgart.de/pub/systems/os2/emx-0.9b/
             Current versions of RSX can be downloaded from: ftp.uni-
             bielefeld.de/pub/systems/msdos/misc/
      Modem: You can download the files from the BBS called "Maus  MK2
             Iserlohn-Kalthof"    (+49    2371    944925)   from   the
             "Gruppenprogrammteil UDO.PUB".
      Mail:  Just send me a formatted floppy disk  and  a  readdressed
             envelope  and 2 DM (or a convertible amount of money) for
             postage.

Let's talk about the installtion of RSX and EMXRT. Of course, you  can
install only one of the drivers if you run exclusively DOS or Windows.
The following descriptions tells you how to install both drivers.

In first place you have to extract the archives. Stop! It's  importand
that  you  extract  the  archives  with  paths!  If you don't let your
archiver generate paths nothing will  function.  I  recommend  to  use
UNZIP.EXE.  If  you extract the RSX archive a directory `RSX\' will be
saved. If you extract EMXRT a directory `EMX\' will be saved.  If  you
don't find these directories something went wrong.

You can  move  the  directories to any position of your file system. I
recommend to move them to  `C:\DRIVERS'.  If  this  directory  doesn't
exist you have to create one.

After having extracted the archives you have to edit your AUTOEXEC.BAT
and to insert the following lines. If you have only  installed  EMXRT,
insert the lines below "Only EMXRT" and so on:

    Only EMXRT:

     SET EMX=C:\DRIVERS\EMX\BIN\EMX.EXE

    EMXRT and RSX:

     SET EMX=C:\DRIVERS\EMX\BIN\EMX.EXE
     SET RSX=C:\DRIVERS\RSX\BIN\RSX.EXE

    Only RSX:

     SET EMX=C:\DRIVERS\RSX\BIN\RSX.EXE
     SET RSX=C:\DRIVERS\RSX\BIN\RSX.EXE

If RSX  and  EMXRT  haven't been installed in `C:\DRIVERS' you have to
adjust the upper paths.

I think  you  already  know  that  changes  of  the   AUTOEXEC.BAT are
activated  when  rebooting  your  computer.  Before  you  reboot  your
computer I just want to summarize what you have done  until  now:  you
have  installed some files and you have inserted one or two lines into
your AUTOEXEC.BAT. That's all.

And now, reboot your computer.


4.2.2  Installation of UDO386.EXE
---------------------------------

Let's talk of the easier part of the installation of UDO. The abridged
version: extract the archive and add the UDO directory to PATH of your
AUTOEXEC.BAT.

But once more I will describe you the installation step by step:

  1. Extract the UDO archvie with paths. If you won't find a directory
     named  `UDO\'  something went wrong. If you will find it move the
     directory named `UDO\' to any position of your file  system.  The
     following  descriptions  assume that you move `UDO\' to your root
     directory.

  2. Now you have to let DOS find the executable:

      (a) Edit the AUTOEXEC.BAT and insert the following line:

          SET PATH=%PATH%;C:\UDO\BIN

          This meand that DOS and Windows will look  for  `UDO386.EXE'
          in   this  directory,  too,  when  you  have  rebootet  your
          computer.

      (b) If you don't like to  extend  your  PATH you  can  move  the
          executables  of `C:\UDO\BIN' to any directory that's already
          listet in PATH. Using this method you don't have  to  reboot
          your computer.


4.3  Installing the Macintosh version
=====================================

After having extracted the archive that contains the Macintosh version
of UDO you can move UDO's files to any place of your file  system  you
want to. In most cases this would be the "Programs" directory.

UDO is  available  as  a  fat-binary  so  it  will  run  both on a 68k
Macintosh and a PowerPC Macintosh. If you want to save some disk space
you may be smaller the program with a certain software.

If you  have  access  to  the hypertext of UDO (`UDO6GER.HYP') you can
read it with "Hyperion". Hyperion is  a  software  written  by  Martin
Osieka  that  can display ST-Guide hypertexts. When using Hyperion you
should copy `UDO.HYP' to the Hyperion directory.


4.4  Installing the Unix versions
=================================

After having extracted  the  archive  copy  the  files  of  `bin/'  to
`/usr/local/bin' or any other directory of $PATH.

Copy the manpage `udo.1' to `/usr/man/man1/'.

To read  the documentation of UDO with GNU Info convert the UDO source
files to  GNU  Texinfo,  run  Makeinfo  and  copy  the  Info  file  to
$INFOPATH.  You  have  to  edit $INFOPATH/dir to get access to the UDO
Info files.

Furthermore you should make some scripts or aliase to simplify calling
UDO. The following script (named `'u2tex`') shows how to tell UDO that
he shall convert the source file to LaTeX):

     #!bin/sh
     udo --tex -o ! $*

You can make similar scripts for the other destination formats if  you
want. The UDO distribution already contains some scripts.

Hint for  users of Linux-SGML: My version doesn't contain all possible
entities. Just take a look ate the Linuxdoc-SGML FAQ in the middle  of
this documentation if Linuxdoc-SGML prints an error message.



======================================================================
Chapter 5

Usage
======================================================================

In this chapter you will get to know which options you have to pass to
the command line version and how to use the versions with a  graphical
user interface.


5.1  Command line version
=========================

The command  line  version  can  be  used identically on any operating
system UDO is available for.


Name
----

udo - convert files from UDO into different formats


Synopsis
--------

udo [-adDghHilmnpqrstvwWxy] source file
udo [-adDghHilmnpqrstvwWxy] -o destination file source file


Description
-----------

UDO converts files from the UDO format  into  Apple-QuickView,  ASCII,
HTML,  Texinfo,  Linuxdoc-SGML,  Manualpage,  Pure-C-Help,  Rich  Text
Format, ST-Guide, LaTeX, Turbo Vision Help or Windows Help.

Using the first method  UDO  prints  the  destination  format  to  the
standard  output  (STDOUT)  and  error  messages to the standard error
output (STDERR). Using the second method UDO  writes  the  destination
format  to  the destination file and error messages to a log file with
the suffix .ul?.

You have to pass single options to UDO: -al isn't the same as -a -l!

The name of the source file has to be the last option.


Options
-------

 -a, --ascii        The source file will be converted to ASCII.

 -D symbol          Set the symbol `symbol' which can be tested in the
                    source file with !ifset.

 -g, --helptag      The  source  file will  be converted to HP Helptag
                    SGML.

 -h, --html         The source file will be converted to HTML.

 -H, --hold         You have to press a key before UDO finishes.

 -i, --texinfo      The source file will be converted to GNU Texinfo.

 --lyx              The source file will be converted to LyX.

 -l, --no-logfile   When using the Option -o UDO doesn't  save  a  log
                    file.

 -m, --man          The source file will be converted to a manualpage.

 -n, --nroff        The source file will be converted to Nroff.

 -o F, --outfile F  UDO writes the output into the file named "F".

 -p, --pchelp       The source file will be converted to Pure C Help.

 -q, --quiet        UDO won't print anything to STDOUT or STDERR.

 -r, --rtf          The source file will be converted to RTF.

 -s, --stg          The source file will be converted to ST-Guide.

 -t, --tex          The source file will be converted to LaTeX.

 -v, --vision       The  source file will be converted to Turbo Vision
                    Help.

 -w, --win          The source file will be converted to Windows Help.

 -W, --no-warnings  Warnings will be suppressed. Error  messages  will
                    still be printed.

 -x, --linuxdoc     The  source  file will  be  converted to Linuxdoc-
                    SGML.

 -y, --no-hypfile   UDO doesn't save a file with syllabification hints
                    when using the option -o.

 --help             Outputs a help page and quits.

 --test             When  using  this option UDO won't save a destina-
                    tion file.

 --tree             When using this option UDO will save a  file  with
                    the  suffix .ut?. In this file you will see a tree
                    with all files your source file includes.

 --verbose          UDO will  print  some  status   information   wile
                    converting the source file.

 --version          Outputs version information and quits UDO.


Examples
--------

 udo file.u
     Convert the source file `file.u' to ASCII (default) and print the
     output to the standard output and error messages to the  standard
     error output.

 udo --tex -o output.tex file.u
     Convert the source file `file.u' to LaTeX and write the output to
     the  file  named  `output.tex'.  Warnings,  error  messages   and
     additional  information  will  be  written  to the log file named
     `output.ult'.

 udo -s -y -l -o ! file.u
     Convert the source file `file.u' to ST-Guide and write the output
     to  `file.stg'. UDO won't save a log file or a file with syllabi-
     fication patterns.


Environment
-----------

 HOME         UDO looks for the file udo.ini in your home directory if
              UDOPATH doesn't exist.

 LANG         Sets  the  language  UDO shall use for error messages if
              neither LC_ALL nor LC_MESSAGES exists.

 LC_ALL       If this is set to `german' UDO prints  German  messages.
              If  this  variable  doesn't  exist LC_MESSAGES it tested
              instead.

 LC_MESSAGES  See LC_ALL. If this variable doesn't exist, too, LANG is
              tested instead.

 UDOPATH      UDO looks  for the file udo.ini in the directory defined
              by  this  variable.  If  UDOPATH doesn't  exist  HOME is
              tested instead.


Exit Status
-----------

 0   Everything was OK.
 >0  An error has appeared.


Author
------

Copyright (c) 1995, 1996, 1997 by
Dirk Hagedorn (Dirk Hagedorn @ MK2, DirkHage@aol.com)


5.2  GEM version
================

The GEM  version  enables  you  to set the files and options by simply
clicking the mouse. Furthermore you can define  programs  for  editing
and viewing files that can be started by the GEM version.

The GEM  version  supports  the VA protocoll, iconification and drag &
drop. It runs with every AES: TOS, MultiTOS, Geneva, MagiC (Mac/PC) or
STonX.

While converting you can see the current status of UDO. Because of the
AES calls the GEM version runs slower than the  TTP  version.  If  you
want to convert large source files I recommend to use the TTP version.

The usage of the GEM version is very easy.


5.2.1  GEM main dialog
----------------------

In the  main dialog you can see several buttons and a menu bar. In the
main dialog you choose the source file, the destination file  and  the
destination  format.  By  pressing  the "Convert" button you start the
conversion.

The items of the menu bar open other dialogs in most cases. If not you
can  guess the sense of them by simply reading the menu item text. Two
menu items have to be described:

 Dest/Start program: You can define a  program  for  each  destination
                     format.  E.g.  you  can  define  a  program  that
                     converts the ST-Guide  source  files  (made  with
                     UDO) into a ST-Guide hypertext, or a program that
                     converts the LaTeX files into a DVI file.

 Dest/ST-Guide:      If you choose this menu item UDO  calls  the  ST-
                     Guide  and  tells  it  to  display  the converted
                     hypertext (source file name, suffix `.hyp)').


5.2.2  GEM dialog `Settings'
----------------------------

After clicking the menu item "Options, Settings" this dialog  appears.
The  sense of each button you can see in this dialog will be described
now.

    Destination file:

        - Adjust: If this button  is  checked  the  GEM  version  will
          adjust  the  file name of the destination file when changing
          the destination format. How it is adjusted  depends  on  the
          status of the following buttons:

             * Completely: UDO adjusts the name completely.

             * Name  and suffix: UDO takes the name of the source file
               and adjusts the suffix according to the current  desti-
               nation  format.  The path of the destination file isn't
               adjusted.

             * Only the suffix: UDO adjusts only  the  suffix  of  the
               destination  file  according to the current destination
               format. The path and the file name aren't adjusted.

        - View: If this button is checked UDO will call  the  destina-
          tion viewer after having converted the source file.

    Ask before:

        - Quitting  UDO: If this button is checked UDO asks you before
          quitting it.

        - Overwriting file:If the destination file already exists  UDO
          will  ask  if it should overwrite the file when starting the
          conversion.

    Options:

        - Save log file: Shall UDO save a log file that  contains  all
          error  messages, warning messages and additional information
          (similar to the command line option --no-logfile)?

        - Save hyphen file: Shall UDO save a hyphen file with syllabi-
          fication patterns (similar to the command line option --no-
          hypfile)?

        - Save tree file: Shall UDO save a tree file where you can see
          the include file structure of your documentation (similar to
          the command line option --treefile)?

        - Verbose  mode:  Shall  UDO  display  the  status  during the
          conversion (similar to the command line option --verbose)?

        - Suppress warnings: Shall UDO suppress  warning  messages  in
          the log file (similar to the command line option --no-
          warnings)?


5.2.3  GEM dialog `Symbols'
---------------------------

The GEM  version  enables  you to set predefined symbols when starting
the conversion. You can insert the text and choose which symbol has to
be used by clicking the buttons on the left side.

If an entry is checked UDO will use the text as a predefined symbol.


5.2.4  GEM dialog `External programs'
-------------------------------------

This dialog  looks  very  complicated  and  I  must say that I have to
change the design next time.

In this dialog you can define the programs you can use for editing and
viewing  the  source files and destination files or for converting the
destination files.

Please select the destination format in the upper half.

In the lower half you can choose the program. If this program isn't  a
GEM  application you should check the button "TOS program". If it is a
GEM  application  and  it  supports  VA_START you  should  check   the
"Supports VA_START" button. These settings are only used if UDO starts
the programs itself. Finally you can edit the parameters UDO shall use
when  calling  the  programs. You can use placeholders for the name of
the current source file and destination file. Click the "Hint"  button
to get more information.


How UDO starts programs

    In first place UDO will look for an AV server. If AVSERVER is set
     inside the environment or Gemini or Thing are running, UDO  tells
     them to start the program.

    If there's no AV server available UDO starts the programs itself.

        - If  the  program  is  an  accessory  the  parameters will be
          transferred via VA_START.

        - If the program is already running and it supports  VA_START,
          UDO will send a VA_START message to this program.

        - In  all  other  cases  UDO  will start GEM applications with
          shel_write() and TOS programs with Pexec().


5.3  Macintosh version
======================

The macintosh version looks more simply  than  the  GEM  version.  All
available options are combined in one dialog.

If you  don't  start  it with passing a UDO source file you can choose
one by clicking the [Choose] or [Auswhlen] button. You  can  set  the
destination  format  by  using  one  of the available formats that are
listed inside the popup. If the destination files shouldn't  be  saved
in  the  source folder you can choose a destination folder by clicking
the second [Choose] or [Auswhlen] button.

Which files UDO will save  you  can  define  by  using  the  group  of
buttons.  I  hope you can guess the function of each button by reading
the labels. The setting of the display popup  ("Ausgabeanzeige")  sets
the  speed  of  UDO. If you set it to "cooperative" ("kooperativ") you
can work with other applications while UDO is  converting  the  source
file.

The conversion  can  be started by clicking the [Output] or [Ausgeben]
button. If your source  file  doesn't  contain  any  error  UDO  quits
without  any  comment.  If  there  were  errors  the Macintosh version
presents an error message with link to the log file.

After having paid the  shareware  fee  you  will  get  a  personalized
keycode  that  you can enter into the dialog. If you enter the keycode
correctly all limitations of the shareware version will be disabled.

The documentation of UDO can be displayed anytime by pressing the help
key  or  clicking  the  help  menu if you have installed the hypertext
viewer Hyperion (written  by  Martin  Osieka)  and  if  the  hypertext
UDO.HYP is installed in the guides folder of Hyperion.


5.4  UDO Shell for Windows
==========================

The UDO shell for Windows ("UDOSH") makes it easier for you to use UDO
with Windows.

The shell can call UDO, editors and viewers and you can simple  choose
which destination format you want to use by clicking the mouse.

The shell is distributed with the complete source code for Borland C++
and is described in a separate documentation.



======================================================================
Chapter 6

The syntax of UDO
======================================================================


6.1  A short example
====================

Before going into details I want to show you how an  UDO  source  file
may  look like. You can use this example to make your own source files
if you want to.

     -----------------------------------------------------------------

     ########################################
     # @(#) An example for UDO
     # @(#) Dirk Hagedorn, 1996/04/16
     ########################################
     
     !stg @subject "Documentation/Utilities"
     
     !title   A short example for
     !program UDO
     !date    (!today)
     !author  Dirk Hagedorn
     
     !use_auto_subtocs    [info,html,stg,tvh,win,aqv]
     !use_auto_subsubtocs [info,html,stg,tvh,win,aqv]
     !no_effects          [asc]
     !use_justified       [asc]
     
     ########################################
     
     !begin_document
     !maketitle
     !tableofcontents
     
     !node Automatic layout
     
     UDO layouts the source file automatically. You don't have
     to take care about spaces between
     two                           words
     because UDO enters line breaks on its own.
     
     
     
     Further more it doesn't make sense but doesn't disturb UDO
     if you enter more than one empty line between to
     paragraphs.
     
     Paragraphs are split by using empty lines or commands.
     
     
     !node A chapter
     This is the text of this chapter.
     
     Due to the switches inside the preamble it follows a
     table-of-contents-like list of all sections of this chapter.
     
     !subnode A section
     This is the text of this section. A ""subsubtoc"" will
     follow due to the switches inside the preamble, too.
     
     !subsubnode A subsection
     This is the text of this subsection.
     
     !end_document

     -----------------------------------------------------------------


Explanations
------------

At the beginning of this example you can see a comment. A comment is a
line that begins with a `#' immediately.

The next  line is a special line. This line contains a special command
for the ST-Guide. If you don't know the ST-Guide just add this line at
the  beginning of your source file so that are all the people are able
to build a hypertext if they want to.

Now the information for the title page  and  the  headlines  are  set.
!title and  !program should  make  sense  if  you  read them one after
another. In this example it would be "An example for UDO". If you look
at  the  line  containing  !date you will see the placeholder (!today)
that is replaced by the current system  date.  You  can  set  !date to
April 16th, 1996 manually, if you want to.

The preamble contains some switches. The first to switches are set for
the output of "sub-tables-of-contents" in  hypertexts.  The  abbrevia-
tions  of  these  hypertexts  you  will  see inside the brackets. In a
"subtoc" all subnodes of a node are printed like a table  of  contents
so  that  readers  of a hypertext are enabled to directly switch to an
interesting subnode.

The switch !no_effects  [asc] suppresses  the  usage  of  Usenet  text
effect commands like stars for bold and slashes for italic text.

The switch  !use_justified  [asc] tells  UDO  to layout the ASCII file
with justified text.

The command !begin_document tells UDO that now the main  part  of  the
document begins. This command has to be part of any source file!

In first  place  we  output  the  title  page  that  is built with the
information set in the  preamble  of  this  example.  You  should  use
!maketitle directly after !begin_document if you use it. It's possible
to use it later but I don't think that it would work without problems.

Then we want that UDO prints a table of contents. There  you  can  see
all  chapters,  sections  and  subsections  of  the  source file. Like
!maketitle you    should    use    !tableofcontents directly     after
!begin_document or !maketitle if you use this command.

Now we  can  enter  the first chapter of our text. Chapters are marked
with !node. Please read the contents of  this  chapter  that  contains
additional information.

The following  lines  demonstrate  how  to  use chapters, sections and
subsections. You should also read the text of these  chapters  to  get
more information.

Finally we  end  our text with the command !end_document. This command
has to be part of every source file and should be the last command  of
a source file!


6.2  Basics
===========


6.2.1  Let's talk about text, Baby!
-----------------------------------

UDO expects a text file that you can edit with every ASCII editor. You
should use only printable characters. That means you shouldn't use any
characters  below  "space"  except ASCII 9 (tab), ASCII 10 (line feed)
and ASCII 13 (carriage return). A line  of  a  source  file  shouldn't
contain more than 512 characters.

UDO layouts  the  destination file itself. That means that it fills in
spaces between words and lines between paragraphs:

 Words are characters that are divided by one or more  blank  or  tab.
     UDO prints words divided by one blank.

 Paragraphs consist  of  words.  Paragraphs are divided by one or more
     empty line(s) or UDO commands.  UDO  divides  paragraphs  by  one
     empty line when printing the destination file.

You can compose the source file using different charsets. UDO supports
the following character sets:

    Atari ST (!code_tos)
    Apple Macintosh (!code_mac)
    HP Roman 8 (!code_hp8)
    IBM PC (!code_dos)
    ISO Latin 1, Windows ANSI (!code_iso)

When UDO starts the conversion it excepts the character  set  that  is
used  on  the  current operating system. If you want to convert source
files that use characters from a different operating system  you  have
to  tell it to UDO by using the upper commands. Additional information
can be found in the chapter "Special characters".


6.2.2  Commands, switches and placeholders
------------------------------------------

 Commands:     An  UDO  command  begins  with  a  single  "!"  at  the
               beginning  of  a  line, it may be indented by spaces or
               tabs. A command tells UDO to  do  something  where  you
               used  it  e.g.  to  output  the  table of contents with
               !tableofcontents.

 Switches:     An UDO switch begins with a single "!" at the beginning
               of  a  line,  it  may  be indented by spaces or tabs. A
               switch tells UDO  how  to  handle  some  commands  e.g.
               !language  english that  switches  the  language of the
               destination file to English  so  that  UDO  will  print
               "Appendix" instead of "Anhang".

 Placeholders: An  UDO  placeholder begins with a "(!" and ends with a
               single ")". A placeholder is replaced by certain  char-
               acters  e.g.  `(!B)'  by  `{\bf' for LaTeX. You can use
               placeholders wherever you want.


6.2.3  Comments
---------------

A source file can contain comments. UDO ignores a line  if  the  first
character  of  a  line is a `#'. This character mustn't be indented by
spaces or tabs!

Inside a verbatim  environment  or  raw  environment  you  cannot  use
comments because UDO prints every line of such an environment.


6.2.4  Preamble and main part
-----------------------------

Each source file has to contain a preamble and a main part.

In the  preamble  you define general information about the source file
like information for the title page or the switches that tell UDO  how
to  convert  the  source  file.  The  preamble  ends  with the command
!begin_document.

The main part contains the text structured into chapters, sections  or
subsections. The main part ends with the command !end_document.


6.2.5  Environments
-------------------

An environment  is a part of a source file that has to be converted in
a special way. Environments will be started with !begin_ and  finished
with  !end_.  The  commands have to be the first words of a line. They
may be indented by spaces or tabs.

UDO offers you a large range of environments that  will  help  you  to
layout your text and to insert special commands:

 appendix environment:    appendix
 center environment:      centred text
 description environment: descriptions
 document environment:    documentation contents
 enumerate environment:   enumerations
 flushleft environment:   left justified text
 flushright environment:  right justified text
 itemize environment:     itemizations
 quote environment:       indented text
 raw environment:         special commands for the destination format
 table environment:       tables
 verbatim environment:    preformatted text
 xlist environment:       lists

How the  text  of  an  environment  is  formatted  you can find in the
according sections.


6.3  Structuring
================

In this chapter you will get to know  what  commands  are  offered  to
structure your documentation.


6.3.1  Title page
-----------------

Using the command !maketitle you can tell UDO to generate a title page
built with information you set in  the  preamble  with  the  following
commands:

 !title:       The  title  of the documentation e.g. "The guide to" or
               "The introduction to".
 !program:     The name of the software or theme you  describe  inside
               the documentation.
 !programimage: The  filename  of  an  image  UDO shall display on the
               title page instead of !program.
 !version:     This is used for version information e.g.  "Release  6"
               or "Version 42".
 !date:        The  date  you  have  written  the documentation or the
               program.
 !author:      The name of the author of the documentation.
 !authorimage: The filename of an image UDO shall display on the title
               page above the name of the author.
 !street:      The  street  where the author lives. Optionally you can
               enter any other text that will be displayed  below  the
               name of the author on the title page.
 !town:        The  town  where  the  author lives. Optionally you can
               enter any other text that will be displayed  below  the
               street on the title page.
 !country:     The  country where the author lives. Optionally you can
               enter any other text that will be displayed  below  the
               town on the title page.
 !email:       The  email  address(es) of the author. You can use this
               command up to five  time  if  you  have  several  email
               addresses.

You don't  have  to use all commands but you should use one command at
least if you are using the command !maketitle.

When used   !maketitle should   only   be    used    directly    after
!begin_document.  To  use  this command at another place of the source
file is allowed but there could be problems.

The title page will be printed on a single  page  when  converting  to
ST-Guide  or  Windows Help. This is a great help for people with small
screens. From the title page you will be able to jump to the table  of
contents.

Converting to  LaTeX  UDO generates a single page using the title page
environment built with the information from the preamble.

If you want to make your own title page you have to use  some  tricks.
You  will  find  an example inside the UDO distribution that shows you
how to make userdefined title pages.


6.3.2  Tables of contents
-------------------------

Using the command !tableofcontents you can  tell  UDO  to  generate  a
table of contents that lists all chapters, sections and subsections of
the source file.

You should   use   !tableofcontents directly    after    !maketitle or
!begin_document to avoid problems.

By using   the   switches   !no_toc_subnodes,  !no_toc_subsubnodes and
!no_toc_subsubsubnodes you can decrease  the  size  of  the  table  of
contents. This is useful when writing large hypertexts.

If you  want  to  list  all  sections of a chapter, all subsections of
section or all paragraphs of a  subsection  you  can  output  this  so
called  "sub-table  of  contents"  with  the  commands called !subtoc,
!subsubtoc and !subsubsubtoc. This is useful for hypertexts where  you
then have the possibility to switch directly to an interesting section
or subsection. UDO enables you  to  automatize  the  output  of  these
"subtoc's"  using the switches !use_auto_subtocs, !use_auto_subsubtocs
and !use_auto_subsubsubtocs.

If you use the upper switches to print subtocs automatically  but  you
don't  want  to  print  them  in  specific chapters you can insert the
commands !ignore_subtoc, !ignore_subsubtoc or !ignore_subsubsubtoc. If
a  chapter  contains  one  of  these commands there will be printed no
table of contents neither automatically nor manually by using  !subtoc
etc.


Summary of all commands and switches
------------------------------------

 !tableofcontents:       Prints  the  table  of contents on a separate
                         page.
 !toc:                   Prints the table of contents inside the text.
 !subtoc:                Prints all sections of a chapter.
 !subsubtoc:             Prints all subsections of a section.
 !subsubsubtoc:          Prints all paragraphs of a subsection.
 !no_toc_subnodes:       Tells UDO that  it  has  to  print  only  the
                         chapter names inside the table of contents.
 !no_toc_subsubnodes:    The table of contents lists only the chapters
                         and sections.
 !no_toc_subsubsubnodes: The  table  of  contents   lists   only   the
                         chapters, sections and subsections.
 !use_auto_subtocs:      Print    all    sections    of    a   chapter
                         automatically.
 !use_auto_subsubtocs:   Print   all   subsections   of   a    section
                         automatically.
 !use_auto_subsubsubtocs: Print   all   paragraphs   of  a  subsection
                         automatically.
 !ignore_subtoc:         Don't  print  the  sections  of  the  current
                         chapter.
 !ignore_subsubtoc:      Don't  print  the  subsections of the current
                         section.
 !ignore_subsubsubtoc:   Don't print the  paragraphs  of  the  current
                         subsection.

Please note:

  1. When  converting to HTML the title page and the table of contents
     will be printed in the file you passed via the command line.

  2. When converting to RTF no table of contents  will  be  generated!
     You  should  make  this with the functions of your text processor
     that is used to import the converted RTF file.


6.3.3  Chapters, sections, subsections and paragraphs
-----------------------------------------------------

UDO offers you four layers for structuring your  documentation.  These
layers are called chapters, sections, subsections and paragraphs.

Using the command !node you tell UDO that a new chapter begins and you
tell it how the chapter is named. The commands  !subnode,  !subsubnode
and   !subsubsubnode do   the  same  for  a  section,  subsection  and
paragraph.

Watch this example (without text) to understand what I want to say:

     !node          A chapter
     !subnode       A section
     !subsubnode    A subsection
     !subsubsubnode A paragraph
     !node          And a different chapter

The table of contents should look like this:

     1  A chapter
        1.1  A section
             1.1.1  A subsection
                    1.1.1.1  A Paragraph
     
     2  And a different chapter

Windows Help and ST-Guide may display text in dialog boxes, too. These
so called popup nodes can be used with the following commands:

    !pnode for popup chapters,
    !psubnode for popup sections,
    !psubsubnode for popup subsections and
    !psubsubsubnode for popup paragraphs

Furthermore you  can create chapters that don't appear in the table of
contents. Use these commands...

    !node* for chapters,
    !subnode* for sections,
    !subsubnode* for subsections,
    !subsubsubnode* for paragraphs
    !pnode* for popup chapters,
    !psubnode* for popup sections,
    !psubsubnode* for popup subsections and
    !psubsubsubnode* for popup paragraphs.

Please note:

  1. Chapters that aren't listed  in  the  table  of  contents  aren't
     numbered, too. UDO will create hypertext links to them as it does
     for all other chapters.

  2. UDO enumerates the chapters automatically. If you want to display
     the  chapter  names  without  numbers  you  can  use  the  switch
     !no_numbers inside the preamble.


6.3.4  Appendix
---------------

UDO can manage one(!) appendix. The contents of the appendix has to be
used inside the appendix environment. This environment is started with
!begin_appendix and finished with !end_appendix.

Chapters that are part of the appendix are  enumerated  using  letters
instead of numbers. A short example:

     !node  A chapter outside the appendix
     !begin_appendix
     !node           A chapter
     !subnode        A section
     !subsubnode     A subsection
     !subsubsubnode  A paragraph
     !end_appendix

The table of contents should look like this:

     5  A chapter outside the appendix
     
     Appendix
     
     A  A chapter
        A.1  A section
             A.1.1  A subsection
                    A.1.1.1  A paragraph

Please note:

  1. You  should  use  the appendix at the end of your source file. In
     other words !end_appendix should be  the  last  but  one  command
     before  !end_document.  You shouldn't use any additional chapters
     behind !end_appendix because UDO  will  get  confused  especially
     while enumerating the chapters.

  2. Because  UDO  uses  letters  for  creating  the  numbers  for the
     chapters of the appendix you shouldn't use more than 26  chapters
     inside the appendix.


6.4  Emphasising text
=====================

In this  section  you  will  get  to  know  how  to layout passages in
different ways. UDO supports centred, left justified, right  justified
and   indented  text,  different  kinds  of  lists,  environments  for
preformatted text and tables. Furthermore you can use  different  text
styles and footnotes.


6.4.1  Itemizations
-------------------

You can  use  the  itemize  environment  for  itemizations where every
single item is marked with a bullet, star, dash or point. The  itemize
environment   is   started   with   !begin_itemize and  finished  with
!end_itemize. Each item has to be marked with the !item command.

You can use the  itemize  environment  inside  other  environments  or
inside another itemize environment.

This short example shows how to write a simple itemize environment:

     !begin_itemize
     !item This is the first item.
     !item This is the second item with a little bit
           more text to demonstrate how UDO formats
           an itemization.
     
           This is the second paragraph of the
           second item of the itemize environment.
     !item This is the last item.
     !end_itemize

... will be printed this way:

    This is the first item.

    This  is  the  second  item with a little bit more text to demon-
     strate how UDO formats an itemization.

     This is the second paragraph of the second item  of  the  itemize
     environment.

    This is the last item.

And this  example, where an itemize environment is used inside another
one ...

     !begin_itemize
     !item This is the first item of the outer
           itemize environment.
     !item This is the second item of the outer
           itemize environment.
           !begin_itemize
           !item This is the 1st item of the inner one.
           !item This is the 2nd item of the inner one.
           !end_itemize
     !item This is the third item of the outer
           itemize environment.
     !end_itemize

... will be printed this way:

    This is the first item of the outer itemize environment.

    This is the second item of the outer itemize environment.

        - This is the 1st item of the inner one.

        - This is the 2nd item of the inner one.

    This is the third item of the outer itemize environment.


UDO separates the text of each item by an empty line.  In  some  cases
it's  not  a  good idea to separate the items e.g. if an item contains
only some text. In this case it would be better to suppress the  empty
lines to get a compressed environment.

For printing  compressed  environment UDO offers you the command named
!short you can add to the !begin_itemize command. If  you  add  !short
UDO  won't separate the items by inserting empty lines. Furthermore in
all environments you use inside  this  itemize  environment  no  empty
lines will be printed.

The following  two  examples  show  how  to use the !short command and
which effects this command has. The first example doesn't, the  second
one uses !short:

Without !short...

     !begin_itemize
     !item Item 1
     !item Item 2
     !item Item 3
     !end_itemize

... will be displayed this way:

    Item 1

    Item 2

    Item 3

With !short...

     !begin_itemize !short
     !item Item 1
     !item Item 2
     !item Item 3
     !end_itemize

... will be displayed this way:

    Item 1
    Item 2
    Item 3

If you  can't  see any difference the destination format doesn't allow
it to suppress the item separation.


Please note:

  1. The items of the first itemize environment will be marked with  a
     bullet   that  is  defined  on  different  positions  inside  the
     character set of each operating system.

  2. If you use the switch  !no_umlaute inside  the  preamble  of  the
     source  file  the  items of the first itemize environment will be
     marked with an `o' instead of a bullet.


6.4.2  Enumerations
-------------------

The enumerate environment is useful for lists where the items have  to
be   enumerated   with   numbers   or  letters.  It  is  started  with
!begin_enumerate and finished with !end_enumerate. Each item has to be
marked with !item.

You can  use  the  itemize  environment  inside  other environments or
inside another itemize environment.

This short example shows how to write a simple itemize environment:

     UDO offers you the following environments:
     !begin_enumerate
     !item itemize environment
     !item enumerate environment (discussed in
           this section)
     !item description environment
     !item xlist environment
     !end_enumerate

... will be displayed this way:

UDO offers you the following environments:

  1. itemize environment

  2. enumerate environment (discussed in this section)

  3. description environment

  4. xlist environment

In the following example the enumerate environment is used  twice  and
it will be compressed because of the usage of !short:

     !begin_enumerate !short
     !item This is the first item of the outer
           enumerate environment.
     !item This is the second item of the outer
           enumerate environment.
           !begin_enumerate
           !item Item 1 of the inner environment.
           !item Item 2 of the inner environment.
           !end_enumerate
     !item This is the third item of the outer
           enumerate environment.
     !end_enumerate

... becomes to:

  1. This is the first item of the outer enumerate environment.
  2. This is the second item of the outer enumerate environment.
      (a) Item 1 of the inner environment.
      (b) Item 2 of the inner environment.
  3. This is the third item of the outer enumerate environment.

Please note:

  1. UDO doesn't enumerate the items for all destination formats. E.g.
     HTML and LaTeX enumerate the items themselves so you have  to  be
     cautious with using text like "see item 1" or "see point b)".

  2. The third layer of enumerate environments will be indented deeper
     than the other layers because Roman numbers  need  a  little  bit
     more space.

  3. Because the second layer is enumerated with letters you shouldn't
     use more than 26 items.

  4. A description of  the  !short command  is  part  of  the  chapter
     "Itemizations".


6.4.3  Descriptions
-------------------

Use the  description  environment for describing some words. Start the
environment    with    !begin_description and    finish    it    using
!end_description.

A word  that  has  to  be described is used with the !item [ ] command
inside brackets and will be displayed with bold text.

The description environment can be used inside other (description) en-
vironments. This example...

     UDO offers you the following environments:
     !begin_description
     !item [the itemize environment]
           for itemized lists,
     !item [the enumerate environment]
           for enumerated lists,
     !item [the description environment]
           for descriptions and
     !item [the xlist environment]
           for lists
     !end_description

... will be display this way:

UDO offers you the following environments:

 the itemize environment for simple lists,

 the enumerate environment for enumerated lists,

 the description environment for descriptions and

 the xlist environment for lists

In this example the description environment is used inside another one
and the !short is used, too:

     !begin_description !short
     !item [Item 1] of the outer description environment
     !item [Item 2] of the outer description environment
           !begin_description
           !item [Item 1] of the inner environment.
           !item [Item 2] of the inner environment.
           !end_description
     !item [Item 3] of the outer description environment
     !end_description

... becomes to:

 Item 1 of the outer description environment
 Item 2 of the outer description environment
      Item 1 of the inner environment.
      Item 2 of the inner environment.
 Item 3 of the outer description environment

Please note:

  1. If the word that shall be displayed in bold text contains  a  "]"
     you have to quote it with an exclamation mark to tell UDO that it
     has to be printed in bold text, too.

  2. The HTML version of your source file will print the  descriptions
     in  bold  text,  too, even if this not typical for HTML. The next
     versions of UDO will offer a command to  disable  the  bold  text
     inside descriptions for HTML.

  3. A  description  of  the  !short command  is  part  of the chapter
     "Itemizations".


6.4.4  Lists
------------

Like the description environment this set of  commands  is  useful  to
describe words. Using this environment the description of each word is
displayed beneath one another.

The xlist environment starts with !begin_xlist [...] and finishes with
!end_xlist. You have to tell UDO in brackets how wide it should indent
the descriptions of each item. Usually you use  the  longest  word  in
brackets.  Each  word  that has to be described has to used inside the
brackets of the !item [ ] command.

You can use the xlist environment inside other  (xlist)  environments,
too.

This short example...

     UDO offers you the following environments:
     !begin_xlist [description environment:]
     !item [itemize environment:]
           for itemizations
     !item [enumerate environment:]
           for enumerations
     !item [description environment:]
           for descriptions
     !item [xlist environment:]
           for lists (discussed in this section)
     !end_xlist

... will be displayed this way:

UDO offers you the following environments:

 itemize environment:     for itemizations

 enumerate environment:   for enumerations

 description environment: for descriptions

 xlist environment:       for lists (discussed in this section)


The command  !short can  also be used for xlist environments. To get a
compressed list just add !short at the end of the line  that  contains
!begin_xlist. Once more a short example:

     !begin_xlist [description:] !short
     !item [itemize:] Itemizations
     !item [enumerate:] Enumerations
     !item [description:] Descriptions
     !item [xlist:] Lists
     !end_xlist

... will be displayed this way:

 itemize:     Itemizations
 enumerate:   Enumerations
 description: Descriptions
 xlist:       Lists


Since Release  6  UDO  offers  three  additional environments that are
familiar with the xlist environment. In contrast to the xlist environ-
ment the items will be displayed in bold, italic or typewritered text.

  1. When  using  the  blist environment (bold list) the items will be
     displayed in bold text. A blist environment will be started  with
     !begin_blist and finished with !end_blist.

  2. When  using the ilist environment (italic list) the items will be
     displayed in italic text. A blist  environment  will  be  started
     with !begin_ilist and finished with !end_ilist.

  3. When  using  the  tlist environment (typewritered list) the items
     will be displayed in typewritered text. A tlist environment  will
     be started with !begin_tlist and finished with !end_tlist.


The following example shall demonstrate the results:

     !begin_xlist [typewritered:]
     !item [normal:] !..
     !end_xlist
     
     !begin_blist [typewritered:]
     !item [bold:] !..
     !end_blist
     
     !begin_ilist [typewritered:]
     !item [italic:] !..
     !end_ilist
     
     !begin_tlist [typewritered:]
     !item [typewritered:] !..
     !end_tlist

... will be displayed this way:

 normal:       ...

 bold:         ...

 italic:       ...

 typewritered: ...


You have to notice some aspects:

  1. If  the text inside the brackets contains a "]" you have to quote
     it with an exclamation mark so that UDO will recognize that  this
     "]" shall be part of the item and shall be displayed on the "left
     side".

  2. HTML, Linuxdoc-SGML and Texinfo don't support an environment like
     UDO's  xlist environment. In these formats the xlist environments
     are displayed like a description environment by default.  But  if
     you  use the switch !use_xlist inside the preamble UDO will print
     xlist environments like in ASCII, but with preformatted text.

  3. UDO doesn't know the character widths when converting the  source
     file to RTF and Windows Help. If the indents are too wide you can
     adjust  the  indent  by  using  the  commands  !rtf_charwidth and
     !win_charwidth.

  4. A  description  of  the  !short command  is  part  of the chapter
     "Itemizations".


6.4.5  Centred text
-------------------

Lines that are part of a center environment will be displayed  centred
if the destination format centred text.

You can  use the center environment inside other environments. You can
also use it inside  another  center  environment,  even  this  may  be
senseless.

If you use other environments inside a center environment they will be
layouted like in all other cases. Only when the center environment  is
the active one text will be printed centred.

If the  following  example  isn't  centred  the  current documentation
format doesn't allow it to use centred text.

     !begin_center
     A centred line.
     
     A centred paragraph
     with two source lines.
     
     The Guide to (!nl)
     UDO
     !end_center

... will be printed in this way:

                           A centred line.

              A centred paragraph with two source lines.

                             The Guide to
                                 UDO

You see that UDO layouts paragraphs of a center environment,  too.  To
insert a manual line break use the (!nl) command.


6.4.6  Right justified text
---------------------------

Lines that  are  part  of  a  flushright environment will be displayed
right justified if the destination  format  supports  right  justified
text.

You can  use the flushright environment inside other environments. You
can also use it inside another flushright environment, even  this  may
be senseless.

If you  use  other  environments  inside a flushright environment they
will be layouted like in all other cases. Only when the flushright en-
vironment is the active one text will be printed right justified.

If the  following  example  isn't  printed right justified the current
documentation format doesn't allow it to use right justified text.

     !begin_flushright
     A right justified line.
     
     A right justified paragraph
     with two source lines.
     
     The Guide to (!nl)
     UDO
     !end_flushright

... will be printed in this way:

                                               A right justified line.

                    A right justified paragraph with two source lines.

                                                          The Guide to
                                                                   UDO

You see that UDO layouts paragraphs of a flushright environment,  too.
To insert a manual line break use the (!nl) command.


6.4.7  Left justified text
--------------------------

Lines that  are part of a flushleft environment will be displayed left
justified without justification.

Er, do you understand that? No? OK, one  more  try.  If  you  use  the
switch  !use_justified UDO  adjusts  the  lines  by  inserting  spaces
between the words so that you have a  proper  right  margin.  But  UDO
won't insert spaces between words of a flushleft environment.

You can  use  the flushleft environment inside other environments. You
can also use it inside another flushleft environment, even this may be
senseless.

If you use other environments inside a flushleft environment they will
be layouted like in all other cases. Only when the flushleft  environ-
ment is the active one text will be printed without justification.

This short example...

     !begin_flushleft
     A left justified line.
     
     A left justified paragraph
     that will be printed
     without justification. This
     senseless sentence is added
     to demonstrate the missing
     justification.
     
     The Guide to (!nl)
     UDO
     !end_flushleft

... will be printed in this way:

A left justified line.

A left justified paragraph that will be printed without justification.
This senseless sentence is added to demonstrate the missing
justification.

The Guide to
UDO

You see  that  UDO layouts paragraphs of a flushleft environment, too.
To insert a manual line break use the (!nl) command.


6.4.8  Indented paragraphs
--------------------------

To display indented paragraphs you can use the quote environment which
is started with !begin_quote and finished with !end_quote. You can use
the quote environment inside another quote environment or inside other
environments.

This environment  is useful to emphasize passages. This effect is used
in the following example:

     !begin_quote
     This paragraph is used inside a
     quote environment and will be
     displayed indented.
     !end_quote

... becomes to:

     This paragraph is used inside a quote environment  and  will
     be displayed indented.

Please note: When  converting  to  HTML  the tag <BLOCKQUOTE> is used.
Netscape and CAB display paragraphs indented but Mosaic displays  them
just with another font.


6.4.9  Preformatted text
------------------------

UDO layouts  the text of the source file on its own. But sometimes you
don't want that because you want to display preformatted  things  like
parts of a source code or something else.

To display preformatted text you can use the verbatim environment that
is started with !begin_verbatim and finished  with  !end_verbatim.  No
UDO commands (except !end_verbatim) or placeholders will be converted.
Text inside this environment will be indented like normal text.

When converting into LaTeX the commands of UDO will be  just  replaced
by   the  LaTeX  commands  \begin{verbatim} and  \end{verbatim}.  When
converting to another format UDO adjusts special  chars  and  displays
the text with a non-proportional font.

If the  lines  of  the verbatim environment contain tabs (ASCII 9) UDO
will replace them by spaces according to the !tabwidth setting.


Because no commands inside a  verbatim  environment  are  noticed  you
cannot use the !include command inside this environment.

To enable  you  to include an external file and display it as it would
be inside a verbatim environment UDO offers you the command !vinclude.
This   command   is   a   mixture   of  !begin_verbatim,  !include and
!end_verbatim.

To write special commands for the destination format  you  cannot  use
this environment. You have to use the raw environment instead.


Please note:

  1. Because  the  text  of  a  verbatim  environment is indented like
     normal text you shouldn't use extra spaces at  the  beginning  of
     each line.

  2. The difference between the raw environment and the verbatim envi-
     ronment is that text of a verbatim environment will be  displayed
     an  you  entered  it, but text of a raw environment will be saved
     into the destination file as you entered it.


6.4.10  Footnotes
-----------------

Text that is used between (!N) and (!n) will be shown  as  a  footnote
when  converting  to  a format that supports footnotes. Otherwise (!N)
will be replaced by ` (', (!n) will be replaced by `)'.

Important hint: Before (!N) you shouldn't use a blank. If  you  do  so
the  footnote  mark  would "fly" without context or before the `(' you
could read two blanks.

This example...

     UDO(!N)Universal Document(!n)

... becomes to:

     UDO (Universal Document)

Footnotes are supported by these formats:

    LaTeX
    Linuxdoc-SGML
    LyX
    Texinfo
    RTF

Please note:

  1. I'm a bit unlucky that UDO just prints brackets if  the  destina-
     tion  format  doesn't support footnotes. It will be better if UDO
     saves the footnote text and prints it at the end of a chapter  or
     page.  Unfortunately this is a very tricky problem that cannot be
     solved in some days.

  2. Don't forget not to use a space or tab before (!N).


6.4.11  Text styles
-------------------

UDO enables you to set text styles right inside the source file.

At the moment UDO supports bold, italic, underlined,  preformatted and
non-proportional text.

If you  want  to display a single word or some words in a certain text
style you have to use them between the according  placeholders.  Look,
how the upper paragraph was made:

At the moment UDO supports
(!B)bold(!b),
(!I)italic(!i),
(!U)underlined(!u),
(!V)preformatted(!v) and
(!T)non-proportional text(!t).

In this  table  you  will  see  in  which way the placeholders will be
replaced:


 +------+-------+----------+-------------+------+---------+--------+
 | UDO  | ASCII | ST-Guide | LaTeX       | RTF  | WinHelp | HTML   |
 +------+-------+----------+-------------+------+---------+--------+
 | (!B) | *     | @{B}     | {\bf        | {\b  | {\b     | <B>    |
 | (!b) | *     | @{b}     | }           | }    | }       | </B>   |
 +------+-------+----------+-------------+------+---------+--------+
 | (!I) | /     | @{I}     | {\it        | {\i  | {\i     | <I>    |
 | (!i) | /     | @{i}     | }           | }    | }       | </I>   |
 +------+-------+----------+-------------+------+---------+--------+
 | (!U) | _     | @{U}     | {\underline | {\ul | {\ul    | <U>    |
 | (!u) | _     | @{u}     | }           | }    | }       | </U>   |
 +------+-------+----------+-------------+------+---------+--------+
 | (!V) |       |          | \verb+      | {\f1 | {\f1    | <PRE>  |
 | (!v) |       |          | +           | }    | }       | </PRE> |
 +------+-------+----------+-------------+------+---------+--------+
 | (!T) |       |          | {\tt        | {\f1 | {\f1    | <TT>   |
 | (!t) |       |          | }           | }    | }       | </TT>  |
 +------+-------+----------+-------------+------+---------+--------+

As you see here for the ASCII format there will be used the text style
commands  as  they  are used in Usenet. If you don't like them you can
use   the   switch   called   !no_effects to   suppress   them.    Use
!no_effects [asc] to  suppress the text style commands when converting
to ASCII.

Please note: Definitions are great for programming  user-defined  text
styles.  It's for sure that you need some knowledge about the destina-
tion forma to do this. The following example show how to  use  ghosted
text which is available for the ST-Guide:

     !ifdest [stg]
         !define G @{G}
         !define g @{g}
     !else
         !define G
         !define g
     !endif
     
     Normal and (!G)ghosted(!g).


6.4.12  Tables
--------------

Since Release  5 you are able to print simple tables with UDO. You can
define the justification of the columns  and  where  UDO  shall  print
vertical and/or horizontal lines.

To print tables with UDO you need the following commands:

  1. !table_caption <text>
  2. !begin_table [...] {!hline}
  3. !end_table
  4. !hline
  5. !!

The command !table_caption defines the title of the next table. It has
to be used before the table environment, not inside this environment!

The command  !begin_table starts  a  table,  !end_table finishes   and
prints  the table. After !begin_table you can define the justification
of the table columns and the usage of vertical lines. Use  `c'  for  a
centred  row,  `l' for a left justified row, `r' for a right justified
row and `|' for vertical lines inside brackets. If you  add  a  !hline
command to this line the table starts with a horizontal line.

After having described the layout of the table with the upper line you
can insert the cells of the table. You have to insert a column in  one
source line and you have to divide the cells by using `!!'.

If you  want  to  insert  a  horizontal  line  you  can use the !hline
command. !hline has to be at the beginning of the line and it  has  to
be the only command of this line.

Here you  will  see a short example that demonstrates the usage of the
upper described commands:

     !table_caption Tables with UDO
     !begin_table [|l|c|r|] !hline
     upper left !! up !! upper right
     lower left cell !! lower cell !! lower right cell
     !hline
     !end_table

This example prints a table with two rows and three columns. The first
column  is left justified, the second columns is centred and the third
columns is printed right justified:


         +-----------------+------------+------------------+
         | upper left      |     up     |      upper right |
         | lower left cell | lower cell | lower right cell |
         +-----------------+------------+------------------+

                       Table 4: Tables with UDO


Because I used a `|' before and after every column they are divided by
vertical  lines.  The  table starts with a horizontal line because the
!hline command was added at the end of !begin_table. Finally the table
ends  with  a horizontal line because the !hline command is used right
before !end_table.


The following example shows the upper table without any lines:


            upper left           up           upper right 
            lower left cell  lower cell  lower right cell 

                       Table 5: Another example



UDO offers you a switch  called  !use_ansi_tables.  If  you  use  this
switch inside the preamble the lines of the table are printed by using
some characters of the IBM PC graphic character set instead  of  +,  -
and  | when  converting  into  an  ASCII like format like ASCII or ST-
Guide. This switch has no effect if you convert to Windows Help,  RTF,
HTML or LaTeX.


Please note:

    Tables are always printed centred.

    HTML  doesn't  allow to define where to use lines. If you use the
     !hline command at the end of !begin_table the  table  is  printed
     via  frame=box. If you don't use !hline it is printed without any
     lines.

    Windows Help doesn't allow it to print centred tables or to print
     lines  where  you  want to. If you use !hline in the !begin_table
     line all cells will be printed with  a  box.  If  you  don't  use
     !hline there will be no line at all in this table.

    Converting  to  ST-Guide  the lines of a table are generated with
     @line. It's not possible to  use  more  than  one  vertical  line
     between columns or more than one horizontal line.

    Inside  the  cells  you  can use all other UDO commands like text
     styles, links or indices.


6.5  Special characters
=======================


6.5.1  Double quotes
--------------------

Double quotes of the source file will be  converted  to  typographical
quotes  if they are supported by the destination format. The following
ASCII simulation demonstrates how it works:

     Double ""quotes""
     
            66       99
     Double    quotes

If you want to  display  two  quotes  you  have  to  use  ("")text("")
instead.

Please note:

  1. The conversion of these double quotes can be suppressed using the
     switch called !no_quotes [ ].

  2. When converting to RTF special RTF commands will be used.


6.5.2  Double apostrophes
-------------------------

Like double quotes UDO can convert double apostrophes into typographi-
cal apostrophes:

     double ''apostrophes''

will become

     double `apostrophes'

If you  want  to  display two apostrophes you have to use ('')text('')
instead.

Please note: The switch !no_quotes [ ] switches off the conversion  of
these double apostrophes, too.


6.5.3  Non breaking spaces
--------------------------

If you  want  to insert non-breaking spaces between two words you have
to use the tilde (~). Non-breaking spaces are also useful to stop  UDO
and the other formats from breaking lines between two words.

Converting to  an  ASCII  format  UDO  replaces this tildes by blanks.
Converting to other formats UDO replaces this tildes by commands  that
have the same effect.

 LaTeX:   ~
 HTML:    &nbsp;
 RTF:     \~
 WinHelp: \~

If you want to display a tilde you have to use !~ instead.

Please note: If  you  use  a  tilde  inside an external link UDO won't
convert it.


6.5.4  Dashs
------------

UDO supports - did you think  anything  else  -  dashs  like  in  this
sentence.

Dashs are  supported  by  LaTeX,  Windows  Help and RTF. Converting to
other formats UDO will replace `---' and `--' by a single `-'.

If you want to display three or two `-' you have to use (---) or (--).


6.5.5  Converting 8 bit chars
-----------------------------

In an UDO source file you can use "higher" characters  without  having
to  know how a character has to look like in a destination format like
LaTeX or Windows Help. So you can enter a German `' without any fear,
UDO  converts  it for you and it knows that this has to be &szlig; for
HTML or {\ss} for LaTeX.

UDO expects files containing chars  of  the  system  charset  of  your
operating system. If you run UDO on a MS-DOS computer UDO expects text
files that are written with the IBM PC character set  by  default.  If
UDO runs on an Atari computer UDO will expect the TOS character set by
default.

But UDO can manage file that are written with another  character  set,
too.  You have simply to tell UDO which character set your source file
uses with the following commands:

 !code_dos: IBM-PC, MS-DOS
 !code_hp8: HP Roman 8
 !code_iso: ISO Latin 1, Windows ANSI
 !code_mac: Apple Macintosh
 !code_tos: Atari ST


There are some things  you  have  to  remember.  Some  character  sets
contain  characters  that  aren't  available  in  another  one. So you
shouldn't use characters from the PC  graphic  character  set  or  the
Hebraic  characters  of  the Atari character set because they can't be
printed in formats like LaTeX, Windows Help, RTF or HTML. In this case
UDO  prints  an error message. You should remove these characters from
your source file and find another solution.

If source files are converted that don't use the character set of  the
operating system UDO is running on the limitations are even higher. In
the first step UDO will convert the characters into ISO  Latin  1.  In
the  second  step UDO will convert the ISO Latin 1 characters into the
character set of the current operating system. In some  cases  there's
is  no possibility to convert the characters without any loss. In such
a case UDO will print an error message.

Please note: If  I've  forgotten  any  character  or  a  character  is
converted in a wrong way please send a bug report!


6.6  Syllabification
====================

UDO supports  a  semi-automatic  syllabification  for ASCII, ST-Guide,
Pure C Help and Manualpage. "Semi-automatic" means that  you  have  to
tell UDO at which position a word can be divided into two pieces.

You have two possibilities to set the syllabification patterns:

  1. Local definition ("!-")
  2. Global definition using the !hyphen command

When converting  to  LaTeX  the  marks  will be replaced by "\-". Then
LaTeX knows that a word can be split at these positions.

When converting to RTF, Windows Help and HTML the marks are deleted.

If you want to display !- you have to use !/-.


6.6.1  Local definition of syllabification patterns
---------------------------------------------------

You can set the syllabification marks in the source file using "!-".  At
these marks UDO is allowed to split up a word. A short example:

     semi-automatic syl!-labi!-fi!-cation

When converting to LaTeX UDO replaces all "!-" by "\-". So it would look
like "syl\-labi\-fi\-cation".

Converting to ASCII, ST-Guide, Pure C Help and Manualpage the word  is
split  up  into different parts if it doesn't have enough place at the
end of a line. So it can  look  like  "syl-  labification",  "syllabi-
fication" or "syllabifi- cation"

When converting to other formats the marks are simply deleted.


6.6.2  Global definition of syllabification patterns
----------------------------------------------------

You can  set  these  marks  at the beginning of a source file with the
!hyphen command for often used words. "Global"  means  that  you  only
have to define the marks once.

If a  word hasn't enough place at the end of a line when converting to
ASCII, ST-Guide, Pure C Help or Manualpage  UDO  looks  for  a  global
definition in its internal list.

In the  following  example  I  expect that the word "documentation" is
used many times in your source file:

     !hyphen docu!-men!-ta!-tion


6.6.3  Short lines
------------------

When converting to ASCII, Pure C Help, ST-Guide or Manualpage UDO  can
generate  a  relative  regular  right margin due to its semi-automatic
syllabification.

The right margin becomes irregular  when  long  words  haven't  enough
place  at  the  end of a line. UDO will print a warning containing the
specific word and you should try to insert some syllabification marks.

Please note:

The command !sloppy switches of these warnings,  !fussy switches  them
back  on.  While developing a documentation you should use !sloppy. At
the end of developing a text you should comment this  switch  and  you
should look after warnings according short lines.


6.7  Images
===========

UDO enables  you  to include images into your destination format if it
supports images like ST-Guide, LaTeX,  HTML  and  Windows  Help.  This
chapter  explains  how  to  include images into a destination file and
what destination commands UDO generates.

To display an image you can use the !image command. You  have  to  add
the name of the image without suffix and an optional image title.

To display  images  right  inside the text you can use the placeholder
(!img ..) when converting into Windows Help or HTML. The other formats
don't  allow  to use images inside the text or it is so difficult that
UDO can't automatize it.

Since Release 6 images will not be centred in all cases. To display  a
centred  image you have to insert the !image command into a center en-
vironment. To display a right justified image you have to  insert  the
!image command  inside  a  flushright  environment. In all other cases
images will be displayed left justified.


6.7.1  *.img & ST-Guide
-----------------------

Example: !image tiger A tiger

UDO opens the file tiger.img and reads  the  size  of  this  image.  A
special  ST-Guide  command  called @limage is generated and the needed
parameters are calculated due to the  information  of  the  GEM  image
header.

If you  want  to display a subtitle add it right after the name of the
image file. This subtitle will look like "(Figure x: A tiger)".


6.7.2  *.img & Lindner-TeX
--------------------------

If you are using Lindner-TeX and you want to include a GEM image  into
your DVI file you have to add !tex_lindner to your preamble.

UDO replaces the tool called IMGTOTEX that is part of Lindner-TeX. UDO
has all functions of this tool built in.

To set the size of an image you have to use the  !tex_dpi command.  An
example:

     !tex_dpi 100
     !image tiger A GEM image

UDO reads  in the header of tiger.img, calculates its size and adjusts
the header to 100 dpi. In the destination file a  TeX  macro  will  be
generated that includes this image and displays it with 100 dpi.


Please note: Using  100  dpi screenshots are displayed in the original
screen size on my HP DeskJet 510.  !tex_dpi can  be  used  before  any
image.  If  you are using an image more than once you shouldn't try to
display it in different resolutions. Use a copy of your image  instead
and  display  the  original  one  with the first and the copy with the
second resolution.


6.7.3  *.img & CS-TeX/MultiTeX
------------------------------

If you are using CS-TeX or MultiTeX and you  want  to  include  a  GEM
image into your DVI file you have to add !tex_strunk to your preamble.

Because the  drivers  of  CS-TeX support the macros of Lindner-TeX the
same is done here as in the upper section.


6.7.4  *.msp & emTeX
--------------------

If you are using emTeX and you want to include an MSP  image  to  your
DVI  file you have to add !tex_emtex to your preamble. Furthermore you
have to set the resolution of an image via !tex_dpi.

The macros for emTeX are generated according  to  the  information  of
dvidrv.doc of emTeX.

In first  place  UDO  tries  to  read  in the header of tiger.msp when
reading the  command  !image  tiger  A  tiger.  If  UDO  doesn't  find
tiger.msp it will try to find tiger.pcx.

An example  shows  what kind of macro UDO generates for emTeX. `w' and
`h' represent the width and height of the image:

     \begin{figure}[htb]
     \begin{...}
     \begin{picture}(<w>,<h>)
         \put(0,<h>){\special{em:graph tiger.msp}}
     \end{picture}
     \end{...}
     \caption{A tiger}
     \end{figure}

Please note: I use !tex_dpi  300 on  my  HP  DeskJet  510  to  display
screenshots.


6.7.5  *.pcx & emTeX
--------------------

If you  are  using  emTeX  and you want to include a Paintbrush PCX to
your DVI file you have to add !tex_emtex to your preamble. Furthermore
you have to set the resolution of an image via !tex_dpi.

The macros  for  emTeX  are  generated according to the information of
dvidrv.doc of emTeX.

In first place UDO tries to  read  in  the  header  of  tiger.msp when
reading  the  command  !image  tiger  A  tiger.  If  UDO  doesn't find
tiger.msp it will try to find tiger.pcx.

An example shows what kind of macro UDO generates for emTeX.  `w'  and
`h' represent the width and height of the image:

     \begin{figure}[htb]
     \begin{...}
     \begin{picture}(<w>,<h>)
         \put(0,<h>){\special{em:graph tiger.pcx}}
     \end{picture}
     \end{...}
     \caption{A tiger}
     \end{figure}


Note: In  first place UDO tries to find an MSP image. If you are using
images from Paintbrush PCX you can ignore the warning printed by UDO.


6.7.6  *.gif & HTML
-------------------

UDO can generate HTML commands to include a GIF. UDO doesn't check  if
the GIF is existing!

For HTML  the  second  parameter of the !image command will be used as
the alternative  text.  The  command  !image  tiger  A  tiger will  be
converted into the following HTML commands:

     <p align=...>
     <img src="tiger.gif" alt="(Figure 1: A tiger)">
     </p><br>

If you  don't  set  the  title  of  this  image  UDO doesn't output an
alternative text. The command  !image  tiger will  be  converted  into
this:

     <p align=...>
     <img src="../gif/tiger.gif" alt="">
     </p><br>


6.7.7  *.jpg & HTML
-------------------

By default UDO expects that you want to display GIF's (see above). But
it's possible to display any other kind of image format, too.

To tell UDO which suffix you want to use the next  time  you  use  the
!image command you can use the command !html_img_suffix.

If the  upper tiger isn't inside a GIF but inside a JPEG image you can
insert the following command right before the !image command:

     !html_img_suffix jpg

If the file is named tiger.jpeg instead of tiger.jpg use the following
line:

     !html_img_suffix jpeg

The setting is used for all following images. If you want to display a
GIF next time you have to  use  !html_img_suffix gif before  the  next
!image command is used.


6.7.8  *.bmp & WinHelp
----------------------

UDO can  generate commands for Windows Help to display Windows bitmaps
(BMP). UDO doesn't check if a BMP is existing!

An image can be displayed with or without  a  subtitle.  Windows  Help
centers the image in the help file.

  1. without subtitle: !image tiger

  2. with subtitle: !image tiger A tiger

UDO will then generate these commands:

     {\qc \{bmc tiger.bmp\}}\par\pard
     \par
     {\qc (Figure 1: A tiger)}\par\pard

Please note:

  1. UDO  won't  check  if  the  image file is existing. If it doesn't
     exists or the filename is wrong the Microsoft  Helpcompiler  will
     print an error message.

  2. With  the  switch  !win_inline_bitmaps you  can  tell  UDO to use
     special Windows Help commands to use "hard-coded" images.


6.8  Hypertext commands
=======================


6.8.1  Labels
-------------

Using the command !label you can set labels inside the source file. An
example:

     !label example

When converting  to the hypertext formats Windows Help, HTML, ST-Guide
and Pure C Help UDO inserts references inside the text to  this  label
automatically.  You  can  search  for  these  labels inside the search
dialog of Windows Help.

When you set the upper label you can jump from  every  position  where
the word "example" is used to the position where you used the label.

Here a list how UDO converts a label for the hypertext formats:

 HTML:          <a name="example"</a>
 LaTeX:         \label{example}
 Linuxdoc-SGML: <label id="example">
 Pure-C-Help:   sensitive("example") inside the header
 ST-Guide:      @symbol ar example
 Turbo-Vision:  .topic example inside the header
 WinHelp:       #{\footnote # example}


Please note: You  shouldn't use special chars like commas, semicolons,
quotes or apostrophes inside the label text because some formats  have
problems  with  these special characters. Please try to avoid them. In
most cases you can avoid them if you really want.


6.8.2  Links
------------

Sometimes you maybe want to set a link to other parts of  the  current
document  or to other documents. To make it possible for you to insert
links UDO offers you the placeholders called  (!link...),  (!xlink...)
and (!plink...).

Please note: If  you want to use a "(" or a "]" inside a link you have
to quote it with an exclamation mark:

     Wrong: (!link [Brackets])] [Link])
     Right: (!link [Brackets!]!)] [Link])
                            ----


6.8.2.1  Internal links

Using the (!link...) command you can insert  links  to  parts  of  the
current  document.  You  can  link to chapters, sections, subsections,
labels and aliases. The following list shows you how to use  the  link
command and how UDO converts it:

     UDO:       (!link [a word] [the link])
     HTML:      <a href="file.htm#the link">a word</a>
     LaTeX:     a word (see \ref{the link})
     ST-Guide:  @{"a word" link "the link"}
     WinHelp:   {\uldb a word}{\v the_link}
     Turbo:     {a word:the_link}
     else:      a word (see "the link")

The following  example  shows  how  to  insert  a  link  to my contact
addresses:

     If you want to register UDO,
     please send (!link [me] [Contact addresses])
     an email.

... will be displayed this way:

If you want to register UDO, please send me (see "Contact  addresses")
an email.

Please note:

  1. You may use up to (!MAXLINKS) inside a paragraph. If you will use
     more links UDO will print an error message.

  2. When converting to hypertext formats UDO checks if the link  des-
     tination exists. If it doesn't exits UDO prints an error message.
     When converting to the other formats UDO  doesn't  check  if  the
     link destination exists!

  3. LaTeX only allows it to link to aliases and labels.


6.8.2.2  Internal links with images

Especially for  Windows Help and HTML there's existing the (!ilink...)
("image  link")  commands.  It  is  a  mixture  of  the  (!img...) and
(!link...) command  that allows to display "hyperimages". If you click
an image you will jump to another part of the current document.

     UDO:      (!ilink [img] [text] [link])
     WinHelp:  {\uldb \{bmc img.bmp\}}{\v link}
     HTML:     <a href="link"><img src="img.gif" alt="text"></a>
     else:     like (!link [text] [link])

Please note:

  1. UDO won't check if the images exist.

  2. By default  UDO  uses  `.gif'  as  the  suffix  for  images  when
     converting  to  HTML. You can use the command !html_img_suffix to
     change the suffix.

  3. You may use up to (!MAXLINKS) inside a paragraph. If you will use
     more links UDO will print an error message.


6.8.2.3  Internal links to pages

Especially for  LaTeX  there's  existing the (!plink...) ("page link")
command:

     UDO:    (!plink [link commands] [Links])
     LaTeX:  link commands (see page \pageref{Links})
     else:   link commands

The following example shows how to insert a page like to the page that
contains my contact addresses:

     If you want to register UDO,
     please send (!plink [me] [Contact addresses])
     an email.

... will be displayed this way:

If you want to register UDO, please send me an email.

Please note:

  1. You  can  only  insert  page  links to labels and aliases, not to
     chapters when converting to LaTeX.

  2. You may use up to (!MAXLINKS) inside a paragraph. If you will use
     more links UDO will print an error message.


6.8.2.4  External links

With the (!xlink...) ("external link") command you can insert links to
(parts of) other documents, net sites or hypertexts. The difference to
the upper command: UDO doesn't adjust special chars of the link desti-
nation. The tilde isn't a non-breaking space in the link  destination,
too.

     UDO:       (!xlink [UDO] [*:\udo.hyp])
     ST-Guide:  @{"UDO" link "*:\udo.hyp"}
     
     UDO:       (!xlink [Atari] [http://www.atari.com])
     HTML:      <A HREF="http://www.atari.com">Atari</A>
     
     UDO:       (!xlink [UDO] [Titel@d:/winhelp/udo.hlp])
     WinHelp:   {\uldb UDO}{\v Titel@d:/winhelp/udo.hlp}
     
     else:     UDO (or Atari)

Please note:

  1. You  have  to  use existing topic names for Windows Help. A topic
     name must contain only numbers and characters form the  alphabet.
     All other characters will be converted by UDO.

  2. You should use `*:\' at the beginning of an external link for the
     ST-Guide to tell it to look for the hypertext in all  directories
     you defined with PATHS in your ST-GUIDE.INF.

  3. Using  the  switch  called  !no_xlinks [...] you can suppress the
     conversion of external links. This  is  useful  if  you  wrote  a
     source  file  especially  for HTML and you want to make a version
     for Windows Help or ST-Guide, where the  external  file  wouldn't
     make no sense.


6.9  Miscellaneous
==================


6.9.1  Macros
-------------

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:

  1. When  naming  the  macros  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)).

  2. 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.


6.9.2  Definitions
------------------

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:

  1. Characters of text of the !define command won't be converted.

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

  3. UDO  supports  the !heading command for displaying headlines. The
     upper HTML example is only used for demonstration.

  4. 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)).

  5. 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.


6.9.3  Indices
--------------

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:

  1. The conversion of these index commands can be suppressed with the
     switch !no_index inside the preamble.

  2. Chapter names, labels and aliases aren't added to the index in no
     destination  format.  But  you  can  automatize  this  with   the
     following            switches:           !use_nodes_inside_index,
     !use_label_inside_index and !use_alias_inside_index.

  3. If a chapter contains the command !ignore_index the chapter  name
     won't  be  added  to  the  index  even  if  you  use  the  switch
     !use_nodes_inside_index inside the preamble of your source file.

  4. If you convert to LaTeX and you use !index commands  inside  your
     source  file  UDO  will  add  the commands that are necessary for
     "Makeindex" automatically. Special characters of an  index  entry
     are converted especially for "Makeindex".

  5. 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:

          wrong:  (!idx [Copyright (c) 1995] )
          right:  (!idx [Copyright (c!) 1995] )


6.9.4  Special commands
-----------------------

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
 pdf   PDF
 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


The raw environment
-------------------

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!


6.9.5  Split documents
----------------------

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:

  1. When writing large source files you can edit a separate file  for
     each chapter that are included by a main file with !include. Thus
     you can restructure your text by simply moving one  line  of  the
     main file.

  2. 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.

  3. 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.

  4. 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.

  5. With  !vinclude and  !tabwidth you  can  add  source code to your
     documentation. This is great for a documentation of a source code
     or a library.



======================================================================
Chapter 7

Tips & tricks
======================================================================

In this  chapter I will tell you some tips for your writing UDO source
files. Furthermore I will show you some tricks. Maybe these tricks can
help you solving some of your problems.

I'm going to add additional tips in the near future. Watch out for new
versions of this documentation or for new UDO Releases.


7.1  Seven rules for writing UDO source files
=============================================

Before starting to write UDO source files you should take  a  look  at
these rules and learn them by heart:

  1. Arrange your documentation clearly!

  2. Speak directly to the reader.

     Use "You can..." instead of "It's possible to...".

  3. Use text styles sparingly and homogeneously.

     Don't use  italic, bold and underlined text too often. But if you
     use different text styles use them homogeneously. This documenta-
     tions  prints  all  UDO  command  in  italics,  all filenames are
     printed with a mono-spaced font.

  4. Make it brief as possible.

     Don't write novels, come straight to the point. If you don't  the
     reader may get bored while reading your manual.

     I have to admit that I'm not able to do this in some cases. ;-)

  5. Use short chapter names.

     If you  use  short chapter names the reader will find the chapter
     more quickly after having read the table of contents. Furthermore
     you can help UDO to insert hypertext links more quickly.

  6. Avoid to use the same chapter name more than once.

     If you  use  the  same  chapter  name  more than once UDO and the
     hypertext compilers  get  confused.  And  you  will  confuse  the
     reader, too.

  7. Use macros and definitions sparingly.

     UDO has to look for macros and definitions twice in every line of
     your source file. Any additional macro or definitions slows  down
     the conversion.


7.2  General tips & tricks
==========================


7.2.1  Split large documentations
---------------------------------

If you  write a documentation that is 30 KB or larger you should split
up it into different parts that you can merge with !include.

By splitting up the documentation you are e.g. enabled to  restructure
it  by  simply moving one line of your main source file. If your docu-
mentation is part of one file you have  to  move  blocks  of  text  to
restructure it.

Another advantage  is that you can find specific chapters more quickly
if you write them to files that you name like this chapter.

Furthermore you can test or convert only some parts of the  documenta-
tion.  My  be  you  have  a  documentation with five chapters. Write a
preamble file, a main file and five files that contain the chapters:

     [main.u]
     !include header.ui
     !begin_document
     !maketitle
     !tableofcontents
     !include chapter1.ui
     !include chapter2.ui
     !include chapter3.ui
     !include chapter4.ui
     !include chapter5.ui
     !end_document
     
     [header.ui]
     !title ...
     !program ...
     !author ...
     
     [chapter1.ui]
     !node Chapter 1
     ...
     
     [chapter2.ui]
     !node Chapter 2
     ...
     
     [etc]

If you now want to convert a single chapter you  simply  edit  another
main file:

     [ch5test.u]
     !include header.ui
     !begin_document
     !maketitle
     !tableofcontents
     !include chapter5.ui
     !end_document

If you  use  this  method  you  will be able to find errors in a large
documentation more quickly.

Just take a look at the source files of the UDO documentation  if  you
want to know how to split up a large documentation. You can believe me
that it would be hard work if all the text would be part of  a  single
text file.


7.2.2  Use standardized source files
------------------------------------

There are  some  authors that write every few weeks a new program or a
new hypertext. And in every documentation you can read a disclaimer or
a  copyright  chapter.  Wouldn't it be easier to use the same text all
the time?

No problem, just use macros. The following example shows how to use  a
standardized  copyright text. May be you have a written a program that
contains this copyright note:

     ""Hello, World!"" Version 8.15 (!nl)
     Copyright (!copyright) 1996 by C. Rookie

Your next program contains a  similar  text,  only  the  name  of  the
program  and the version number differ. Wouldn't it be better to use a
standardized text any time  you  write  the  documentation  of  a  new
software?

     ""(!PrgName)"" Version (!PrgVersion) (!nl)
     Copyright (!copyright) (!PrgYear) by C. Rookie

Here the  name,  the  version number and the years will be replaced by
the contents of macros "PrgName", "PrgVersion" and "PrgYear".  If  you
write the upper text to a sinlge file you can use it for many documen-
tations where only the macros have to be defined.

     !macro PrgName    Hello, World!
     !macro PrgVersion 8.15
     !macro PrgYear    1996
     ...
     !begin_document
     ...
     !include copyleft.ui

It's true that this is only a small example. But  you  can  make  more
complex files if you want to.


7.2.3  Write your own commands
------------------------------

UDO doesn't  support  every command of the destination formats. If you
need a special command you  can  add  it  by  using  definitions  with
parameters. You only need some knowledge about the destination format.

The following  example  shows  how  to write commands for changing the
font size for LaTeX, HTML, Windows Help and RTF:

     !code_iso
     !program Changing the font size
     !author Dirk Hagedorn
     !date August 19th 1996
     
     !ifdest [tex]
     !define tiny  {\tiny{(!1)}}
     !define large {\large{(!1)}}
     !define Large {\Large{(!1)}}
     !define LARGE {\LARGE{(!1)}}
     !define huge  {\huge{(!1)}}
     !define Huge  {\Huge{(!1)}}
     !endif
     
     !ifdest [win,rtf]
     !define tiny  {\fs14 (!1)}
     !define large {\fs28 (!1)}
     !define Large {\fs36 (!1)}
     !define LARGE {\fs44 (!1)}
     !define huge  {\fs50 (!1)}
     !define Huge  {\fs60 (!1)}
     !endif
     
     !ifndest [tex,win,rtf]
     !macro  tiny  (!2)
     !macro  large (!2)
     !macro  Large (!2)
     !macro  LARGE (!2)
     !macro  huge  (!2)
     !macro  Huge  (!2)
     !endif
     
     !begin_document
     !maketitle
     !tableofcontents
     
     !node Test
     
     (!tiny [tiny]),
     normal,
     (!large [large]),
     (!Large [Large]),
     (!LARGE [LARGE]),
     (!huge [huge]) und
     (!Huge [Huge]).
     
     !end_document


7.3  Tips & tricks according to LaTeX
=====================================


7.3.1  A user-defined LaTeX preamble
------------------------------------

In contrast to the previous UDO version UDO  Release  6  will  save  a
LaTeX preamble automatically for LaTeX 2.09 or LaTeX2e.

If you  don't  like the automatically generated preambles you tell UDO
not to save them by using  the  switch  !no_preamble [tex] inside  the
preamble of your UDO source file.

In this case you can enter the special LaTeX commands at the beginning
of the UDO source file with !tex or a raw environment.

The following example shows how you can do this:

     !code_iso
     !no_preamble [tex]
     
     # Uncomment the following line for LaTeX 2.09
     # !tex \documentstyle[12pt]{article}
     
     # Uncomment the following lines for LaTeX2e
     !tex_2e
     !tex \documentclass[12pt,a4paper]
     !tex \usepackage{a4}
     
     !begin_document
     !node Example
     This example uses a userdefined (!LaTeX) preamble.
     !end_document


7.4  Tips & tricks according to ST-Guide
========================================


7.4.1  A user-defined title page for ST-Guide
---------------------------------------------

If you don't like the layout of the title  page  UDO  will  make  with
!maketitle you can make your own title page with some commands:

The following  example  shows how to make your own title page but only
for the ST-Guide. It's used a "hidden" node  that  contains  the  word
"Contents" at the end. The ST-Guide will insert a link to the table of
contents due to this word.

     !program Title pages with UDO
     
     !begin_document
     
     !ifndest [stg]
     
     !maketitle
     
     !else
     
     !node* Title
     
     !begin_center
     The hypertext to ""Hello, World!"" (!nl)
     Version 8.4
     
     written by
     
     Ford Prefect
     !end_center
     
     !smallskip
     
     !begin_center
     Contents
     !end_center
     
     !endif
     
     !tableofcontents
     
     !node The first chapter
     This is the first chapter
     
     !node Bye bye
     Stop it, now!
     
     !end_document


7.4.2  Don't use justified text
-------------------------------

"Why that?" you might ask. Well, Martin Osieka has written  a  program
called  Hyperion  for  the  Apple  Macintosh that can display ST-Guide
hypertexts.

In contrast  to  ST-Guide  Hyperion  can   display   hypertexts   with
proportional fonts but only if you don't use justified text.

Thus you should don't use the justification if you want that Macintosh
users shall also read your hypertext without any problems.

If you  have  written  a  system  specific  hypertext  that  is   only
interesting  for  Atari  users  you  can use justification without any
doubts.


7.5  Tips & tricks concerning Windows Help
==========================================


7.5.1  Write the source files with a Windows editor
---------------------------------------------------

You can speed up the conversion if you write the source files  with  a
Windows  editor.  In this case UDO doesn't have to convert the charac-
ters from the IBM PC character set into  the  Windows  ANSI  character
set.

If you  write source file with a Windows Editor you have to insert the
switch !code_iso inside the preamble  of  your  source  file.  If  you
forget to do this UDO will think that the source file was written with
the IBM PC character set.

Tip: I recommend to use the "Programmer's File Editor"  (PFE)  written
by  Alan  Phillips,  a  really great freeware editor that is available
both for Windows 3.11 and Windows95/NT.


7.5.2  Compress the Windows Help files
--------------------------------------

Using the switch !win_medium_compression or  !win_high_compression you
can tell the Microsoft Helpcompiler to compress the final Windows Help
file up to 50%. The Microsoft Helpcompiler will need a little bit more
time to convert the RTF source file if you use the upper switches.




======================================================================
Appendix A

Frequently asked questions
======================================================================

This chapter  shall  help you to solve smaller problems. You will find
some answers to internal questions about  UDO,  too.  In  first  place
general  questions  are  answered, in second place the format specific
questions will be answered.


A.1  General questions
======================

 Why is UDO names `UDO'?

     When I began programming UDO I had no better idea than naming  it
     "UDO", the abbreviation for "Universal DOcument".

     By the way: The author's prename isn't Udo, he's called Dirk!

 How to I pronounce `UDO'?

     `UDO' is pronounced like the prename Udo: `Ooh-do'. Pronounce the
     `U' like the  `u'  in  `butcher',  the  `do'  like  the  `do'  in
     `document'. Please don't pronounce it like `You do'.

 How can I get the current versions?

     You can  download  the  current version from a BBS and via FTP or
     from the World Wide Web.

     The current versions are always available in the BBS called "Maus
     MK2     Iserlohn-Kalthof"    (+49    2371    944925)    in    the
     "Gruppenprogrammteil UDO.Pub". After  the  login  press  `P'  for
     `Programmteil',  press  `G'  for  `Gruppenprogrammteil' and enter
     `UDO.Pub'.  You  can  list   all   archives   by   pressing   `A'
     (`Ausfhrliche Liste') and `L' (output list). Remember the number
     of the archive  and  start  the  download  by  pressing  `D'  and
     entering the number of the archives.

     To download  the current version from the World Wide Web open the
     URL http://members.aol.com/UDODH/index.htm. Here  you  will  find
     links to the UDO archives.

     To download    them    via    FTP    open    a    connection   to
     members.aol.com/UDODH/ (not                ftp.members.aol.com!),
     members.aol.com/UDOENG/ or members.aol.com/UDOADD/.

     If you  don't  own  a  modem  and  you  don't  have access to the
     Internet you can get the current version by simply sending  me  a
     formatted floppy disk besides a readdressed envelope and 2 DM for
     stamps. Please tell me which operating system you use.

     The names of the archives are constructed in the following way:

          udorlyyy.sss
             ||| ||  |
             ||| |+--+--- .zip: ZIP archive
             ||| |        .tgz: tar gzip archive
             ||| |
             ||+-+------- beo:  version for BeOS
             ||           hp4:  version for HP-UX, 300/400
             ||           hp8:  version for HP-UX, 700/800
             ||           lin:  version for Linux
             ||           mac:  version for MacOS
             ||           nex:  version for NeXTStep
             ||           sin:  version for SINIX
             ||           sun:  version for SunOS
             ||           tos:  version for Atari ST and clones
             ||           dos:  version for DOS, OS/2 and Windows
             ||           man:  source files of this manual
             ||
             |+---------- g:    version with German manual
             |            e:    version with English manual
             |
             +----------- Release number: 6 for UDO Rel. 6

     The archive containing the English version for MS-DOS  is  called
     udo6edos.zip,  the archive containing the English source files of
     this manual is called udo6eman.zip.

     The Unix version may have longer names like udo6_ger_linux.tar.gz
     or udo6_eng_hp-ux-34.tar.Z.

 Will there be versions for other operating systems?

     At the  moment  UDO  is  available  for  the  following operating
     systems:

         Atari TOS
         BeOS
         DOS, OS/2, Windows
         HP-UX 9.x for 300/400 and 700/800 models
         Linux i86
         MacOS
         NeXTStep
         SINIX

     UDO was completely written in highly portable C. The source  code
     doesn't  call any system specific functions. Due to this fact UDO
     could be ported to any operating system a C compiler is  existing
     for.

 Can UDO generate formats from other systems?

     Sure. E.g. you can run UDO on a Windows PC and save Linuxdoc-SGML
     files. You can run UDO on a Linux PC and save Windows Help files.
     No  problem.  UDO has the same functions on any operating systems
     it's available for.

     Maybe you have only to convert the file with GNU-Recode later  if
     the charsets are not the same.

 Can I write my source files "here" and translate them "there"?

     Yes, you  can  e.g.  write  your source files on a Windows PC and
     convert them on  a  BeBox  or  Apple  Macintosh.  UDO  knows  the
     charsets  of  all  operating  system it's available for. You have
     only to say UDO which charset was used  for  writing  the  source
     files by using the commands like !code_iso or !code_mac.

 Do you want to support other destination formats in the future?

     Yes, I  want  to  support the following formats if I will get any
     information about them  and  if  I'm  allowed  to  generate  them
     without paying any licences to anybody:

         Apple Guide
         HP HelpTag SGML
         OS/2-Help
         Portable Document Format `PDF', Adobe Acrobat Reader
         Postscript

 May the UDO syntax change in the future?

     UDO is  that  kind  of  software that is improved day by day. New
     commands will appear in the future, that's for sure.

     In some cases it will be necessary to change the syntax  of  some
     commands.  But  I  will tell you about these changes. Just take a
     look at the "History" to get to know about  the  changes  in  the
     past.

 How does UDO work?

     UDO reads the source file(s) in two passes.

     In the  first pass UDO reads in the switches, macros, definitions
     and the chapter titles that are needed for referencing.

     In the second pass UDO will convert and layout the text. UDO will
     save all lines in an internal buffer until it reads an empty line
     or an UDO command. A command or an empty line tells UDO to layout
     the last paragraph and to go on reading the source file.

 How does UDO reference other parts of the document?

     UDO inserts  links in hypertext formats (except for the ST-Guide)
     automatically to other parts of the documentation. UDO references
     chapter titles, labels and aliases.

     Using the  switch  !autoref [off] you  can tell UDO not to insert
     any references until you use the switch !autoref [on].

 How can I link to parts of the current page?

     Because UDO doesn't insert links to labels of the same  page  you
     have  to  insert  a  explicit  link  to  this  label by using the
     (!link [ ] placeholder. An example:

     !node  Test
     !label Test top
     [...]
     (!link [Back to top of page] [Test top])

 How can I display images in the table of contents?

     You have to make your own table of contents, that means you  have
     to leave the !tableofcontents command. An example:

          !begin_document
          !maketitle
          !node Contents
          !image foo
          !toc [all]
          
          !node First chapter


A.2  Questions concerning ASCII
===============================

 Do you plan to split up ASCII manuals into separate files?

     Only one  (unregistered)  user  has  wished  yet  that UDO should
     output chapters etc. to separate  files  as  it  does  for  HTML.
     Because  no one else has asked me to do this yet I haven't imple-
     mented this feature.

     But if there's a need for this feature I will implement  it.  The
     functions still exist and have only to be adapted for ASCII.

 Some lines are larger than 70 characters, why?

     These are  the  lines  that  contain  bold,  italic or underlined
     words. These text styles are generated with the characters  *,  /
     and _ like in Usenet.

     Because of  the  existence of some print tools (e.g. IdeaList for
     Atari ST) and newsreaders know  these  text  styles  UDO  doesn't
     count these special characters.

     If you  want  to  suppress the output of these characters you can
     use the switch !no_effects [asc] inside the preamble.

 8bit characters are wrong when viewing an ASCII file with Windows!?

     UDO saves ASCII  files  that  use  the  system  charset  of  your
     operating  system. UDO is a DOS software, not a Windows software.
     So it will use the  IBM-PC  charset  and  not  the  Windows  ANSI
     charset.

     Just view  the  ASCII files with the System font or Terminal font
     and you will believe me that the 8bit characters aren't wrong.

 How can I change the paragraph width?

     The paragraph width can be changed with the !parwidth command.


A.3  Questions concerning HTML
==============================

 How can I tell UDO not make files for each chapter?

     In contrast to the other formats UDO saves a separate  HTML  file
     for  each  chapter by default. UDO names these files by using the
     chapter numbers. The title page and the table of contents will be
     saved in the file you passed in the command line.

     Using the   switches   !html_merge_nodes,   !html_merge_subnodes,
     !html_merge_subsubnodes or   !html_merge_subsubsubnodes you   can
     tell UDO not to save a file for each chapter.

     If you  use  !html_merge_nodes inside  the preamble UDO will save
     only one HTML file that contains the whole text. You  should  use
     this option only for small source files.

     If you use !html_merge_subnodes UDO will save separate files only
     for chapters. All  sections,  subsections  and  paragraphs  of  a
     chapter will be saved inside this file, too.

     If you  use  !html_merge_subsubnodes UDO will save separate files
     for chapters and sections. The subsections and  paragraphs  of  a
     section  will  be saved in the file that contains the text of the
     upper section.

     Finally if you use !html_merge_subsubsubnodes the paragraphs of a
     subsection  will  be  saved in the file that contains the text of
     the subsection.  UDO  will  save  separate  files  for  chapters,
     sections and subsections.

 I don't like the names of the HTML files!

     Using the   command   !html_name inside   a   chapter,   section,
     subsection or paragraph you can tell UDO which filename it  shall
     use instead of using a filename like "01020304.html".

 How can I suppress these ugly headlines?

     UDO will  print  on  every HTML page a headline that contains the
     title of the documentation and hypertext links to  the  previous,
     next  and  upper  page.  UDO  uses GIF's for these links that are
     saved by UDO automatically. The  filenames  of  these  GIF's  are
     udo_lf.gif, udo_rg.gif and udo_up.gif.

     Using the switch !no_headlines [html] inside the preamble you can
     tell UDO not to generate these headlines.

 How can I easily make my own headlines or bottomlines?

     If you want to make your own headlines or bottomlines you can use
     macros  at  the  beginning of each chapter. The following example
     shows how I added  bottomlines  to  my  WWW  pages.  These  pages
     contain  links  to  the chapters that contain my address, the de-
     scriptions of my software and links to other web sites.

      Main file:

          !ifdest [html]
          !define HR <hr>
          !macro  HEAD [ Software | Contact addresses | Links ] (!HR)
          !macro  FOOT (!I)Dirk Hagedorn - last updated on (!short_today)(!i)
          !else
          !define HR
          !macro  HEAD
          !macro  FOOT

      software.ui:

          !node Software
          !html_name software
          (!HEAD)
          [...]
          (!FOOT)

     If you convert the source file to HTML  UDO  expands  the  macros
     that  contain  the text of the headlines and bottomlines. Because
     UDO insert links automatically you can jump to the other pages by
     clicking the entries of the bottomline.

     If you  don't  convert  to  HTML  empty  macros  are used so that
     nothing will appear when using (!HEAD) or (!FOOT).

 Sometimes a table has a frame, sometimes it hasn't!?

     Unfortunately HTML only allows to  use  tables  with  or  without
     frames. You cannot use table lines where you want to.

     To print  a table with a frame you have to add !hline to the line
     that contains !begin_table. If you don't want a frame  don't  use
     !hline. That's all.

 Which suffixes does UDO use for HTML files?

     By default  UDO  uses the suffix of the --outfile you used in the
     command line:

      -o index.htm  .htm
      -o index.html .html
      -o INDEX.HTML .HTML

     If you use the option -o ! UDO uses `.htm' on  operating  systems
     with  8+3-filenames  and  `.html'  on operating systems with long
     filenames.

 The filenames of the URL's are wrong!?

     If you use UDO on an operating system that doesn't  support  long
     filenames  but  you have used `--outfile index.html' and you copy
     the saved `.htm' files to a web server, remember this:

       1. UDO will try to save `index.html' but TOS and DOS will  name
          it `index.htm'.

       2. UDO  will  use  for  all  hypertext links the suffix `.html'
          because of the suffix of the `outfile'. If you  use  a  HTML
          browser  for  TOS or DOS this browser will open `index.html'
          without any problems even  if  there's  only  a  file  named
          `index.htm'.

       3. When  copying  the  files to a web server you have to change
          the suffixes from `.htm' to `.html'. If you will forget this
          all links will be wrong.


A.4  Questions concerning manpages
==================================

The Manualpage  is  an  ASCII  format  where  text  styles are made by
inserting backspace sequences. It's used for short  software  descrip-
tions for Unix systems. For longer descriptions you should use the GNU
Texinfo format.

 How can I set the page length for manpages?

     You can set the lines each page of a manpage should have with the
     command !man_lpp ("lpp" means "lines per page").

 How can I set the program type for manpages?

     Use the switch !man_type X where "X" is displayed inside brackets
     in the headlines of the manpage.

 Why doesn't UDO print a table of contents?

     It's very unusual to use a table of contents in  a  manpage.  For
     short  program  description  - you only should use manpages for -
     tables of contents don't make sense, too.


A.5  Questions concerning LaTeX
===============================

 How does UDO create the LaTeX preamble?

     UDO knows which  language  and  which  document  style  you  use.
     Furthermore  UDO  knows  if  you are using indices or not. So UDO
     knows enough to create the LaTeX preamble on its own.

 How can I make files for LaTeX2e?

     By default UDO saves files for LaTeX 2.09. If you use the  switch
     !tex_2e inside  the  preamble  UDO will save a preamble and other
     special commands for LaTeX2e.

 I want to use a userdefined preamble!?

     Use the switch !no_preamble [tex] inside the preamble of your UDO
     source  file and insert the userdefined LaTeX preamble into a raw
     environment at the beginning of your UDO source file.

 How can I use LaTeX formulas inside the text?

     Use a raw environment for complete paragraphs or definitions  for
     floating text. An example:

     !ifdest [tex]
     !define ab2 $(a+b)^2 = a^2 + 2ab + b^2$
     !else
     !macro  ab2 (a + b)^2 = a^2 + 2ab + b^2
     !endif
     ...
     The first binomial theorem: (!ab2)

 How does UDO translate special chars in indices?

     Special characters are translated especially for makeindex.

 When I use brackets inside indices a LaTeX error appears!?

     You have  to use a `}' for any `}' inside an index entry and vice
     versa. Otherwise LaTeX will print an error message.


A.6  Questions concerning Linuxdoc-SGML
=======================================

In March 1996 I found an article in  the  German  Unix  magazine  "iX"
about  Linuxdoc-SGML.  It took two hours to download the Linuxdoc-SGML
archive and to implement this format into UDO. Unfortunately I  didn't
own a Linux computer and so I wasn't able to test UDO's output.

Linuxdoc-SGML is  a multiformat converter like UDO. With Linuxdoc-SGML
you can  convert  SGML  files  into  LaTeX,  RTF,  HTML,  Texinfo  and
manpages.  But  it's not a lie if I say that UDO is more powerful than
Linuxdoc-SGML 1.5.

 The xlist environment is handled like a description environment!?

     Linuxdoc-SGML doesn't offer an environment like UDO's xlist envi-
     ronment.  So  UDO is forced to handle it like a description envi-
     ronment.

 Linuxdoc-SGML doesn't know &Aring;, why?

     Add the following line to /usr/lib/linuxdoc-sgml/rep/html/
     general:

          <!entity Aring sdata "&Aring;" >


A.7  Questions concerning Pure C Help
=====================================

The Pure C Help format is only useful for the Pure C compiler on Atari
ST  for  displaying online library descriptions. The format isn't used
for any other purposes neither on this nor on other computers.

 How does UDO print the title page and the table of contents?

     UDO prints a single page that contains both the  title  page  and
     the  table  of  contents. Because this page can get very long you
     should use the switch !use_short_toc [pch].

 How can I suppress the headlines?

     UDO prints a  headline  on  each  page  automatically.  Headlines
     contain  the  name  of  the  current chapter and the title of the
     source file. By clicking the title you can jump to the title page
     or the table of contents.

     Using the  switch !no_headlines [pch] you can suppress the output
     of these headlines.

 How can I suppress the bottomlines?

     UDO prints a bottomline on each page automatically  that  contain
     links  to  the  previous page, next page and upper page. Thus the
     reader of the online manual is enabled to jump directly to  other
     pages without returning to the table of contents.

     Using the   switch  !no_bottomlines [pch] you  can  suppress  the
     output of these bottomlines.

 What can I do with the file with the suffix .cmd?

     UDO saves a command file for the Pure C Help compiler HC.TTP. You
     have  to  call the HC by passing the name of this command file to
     get a compiled help file.

     UDO always overwrites this file. You  have  to  switch  in  write
     protection if you want to protect your own changes to this file.

 How do I build a help file for Pure C?

     UDO saves  two file when converting the source fie foo.u: foo.scr
     and foo.cmd.

     To get a Pure C Help file you have to call HC.TTP by passing  the
     command file foo.cmd:

          $ e:\purec\hc.ttp foo.cmd

     Using GEM just drag foo.cmd onto HC.TTP to start the conversion.

 How can I install this help file?

     Pure C can display on user defined help file. This file has to be
     named  USR.HLP and  it  has  to  be  placed  inside  the  Pure  C
     directory.

     To install  your  help  file  backup the original USR.HLP, rename
     your help file to USR.HLP and copy it to the Pure C directory.


A.8  Questions concerning the Rich Text Format
==============================================

The Rich Text Format (RTF) is used for the  system  wide  exchange  of
text  files.  This format has a strict definition. New commands can be
added every time. If a RTF software reads in an unknown command it has
to ignore it.

Unfortunately not   all  the  existing  software  ignore  unknown  RTF
commands, some are interpreting some senseless stuff.  Microsoft  Word
doesn't  interpret  the  RTF correctly in all cases, even if Microsoft
has developed the Rich Text Format.

It's not wrong if I say that RTF is  the  most  misinterpreted  format
ever known.

 Why doesn't UDO print a table of contents?

     I think  you  are the reader of your documentation wants to print
     it out with a text processor. And it's for sure that you want the
     correct page numbers inside the table of contents.

     But UDO cannot know on which page a chapter will be printed. Thus
     it doesn't print a table of contents when converting to RTF.

     OK, it wouldn't be a problem to print it but I  think  you  don't
     want a table of contents without page numbers.

 Why doesn't UDO include the image data into the RTF file?

     Because I don't know until today how image data is converted into
     RTF data. If you can tell me how this is done, please tell it  to
     me.

 The output of my text processor is horrible, why?

     Bad luck.  You  own  a  text  processor  that  cannot  import RTF
     correctly. UDO strictly pays attention to the RTF definition.  If
     it's  possible  for  you  to  contact  the  authors  of your text
     processor send them your RTF file.

     By the way: I also tried  to  get  contact  to  authors  of  text
     processors   but   only  one  author  (Christian  Nieber,  R.O.M.
     logicware, Papyrus) answered my emails. Can you imagine that?

 8-bit characters aren't imported correctly!?

     UDO saves RTF files that use  the  Windows  ANSI  character  set.
     Every  text processor should be able to import RTF files that use
     the IBM-PC character set, the Macintosh  character  set  and  the
     Windows   ANSI  character  set.  If  some  8-bit  characters  are
     displayed incorrectly it's a problem of your text  processor  and
     not a bug of UDO.

 Quotes aren't imported correctly, why?

     UDO uses   the  RTF  commands  \lquote,  \rquote,  \rdblquote and
     \ldblquote for displaying the typographical quotes  and  apostro-
     phes. Your text processor has to know these common RTF commands.

     If it doesn't want to import these RTF commands or the quotes and
     apostrophes are displayed incorrectly you can tell UDO not to use
     these  RTF  commands  by  inserting  the  switch !no_quotes [rtf]
     inside the preamble of the UDO source file.

 My text processor cannot import tables. What can I do?

     Use the switch !rtf_ascii_tables inside the preamble of your  UDO
     source  file  to  tell UDO that it shall print tables without RTF
     commands like in the ASCII format.

 StarWriter 3.0 prints an RTF error!?

     It seems to be that StarWriter 3.0 doesn't know all RTF  commands
     and  furthermore  it  faults correct RTF commands. Please contact
     Star Division.

 Indices aren't imported into StarWriter!?

     StarWriter 3.0 ignores the RTF command `\xe' which  is  used  for
     indices.

 Lotus WordPro places chapter numbers outside the text frame!?

     I'm sorry  but  I  have  no  idea  why  it  does this. Other text
     processors display the chapter numbers correctly.

 Lotus WordPro doesn't display tables correctly!?

     I don't know why Lotus WordPro doesn't recognize the ending of  a
     table.  The  table  itself  will  be  displayed incorrectly, too.
     Please use the switch !rtf_ascii_tables inside  the  preamble  of
     your UDO source file.

 WordPad doesn't display tables, why?

     Because WordPad   cannot   display   tables.   Use   the   switch
     !rtf_ascii_tables inside the preamble of your UDO source file.


A.9  Questions concerning ST-Guide
==================================

 Images aren't displayed centred?

     Get the current ST-Guide version. Since Release 15  the  ST-Guide
     can center images itself.

 How does UDO create the title page and the table of contents?

     The title  page  and the table of contents are displayed inside a
     special node. The title page node is named "Title". The node that
     contains the table of contents is named "Main".

     To let the ST-Guide display the first page of the hypertext (this
     will be the title page in most cases) just pass the name  of  the
     hypertext. To let the ST-Guide display the table of contents pass
     the node name "Main". How you can call the ST-Guide from programs
     you can read in the HCP hypertext.

 How can I suppress the headlines?

     UDO prints  a  headline  in  every  page by default. The headline
     contains the current node name and the title  of  the  hypertext.
     The headline will be displayed underlined.

     Using the switch !no_headlines [stg] inside the preamble you tell
     UDO not to create these headlines.

 How does UDO insert hypertext links?

     UDO just insert hypertext  links  when  you  use  (!link ...) and
     (!xlink ...).  All  the other hypertext links will be inserted by
     the HCP.

 How does UDO convert labels?

     The UDO command  !label will  be  replaced  by  the  HCP  command
     "@symbol  ari". You have to check yourself if there's a node or a
     label existing with the same name.

 How can I make popup nodes?

     Using the !pnode and the familiar commands you can tell  the  ST-
     Guide  to  display  the  contents of the node inside a dialog box
     instead of a window.

     But you have to remember that text inside a popup node  may  have
     up  to  12  lines  of  text  with  60  characters  per line only.
     Furthermore no images and links are allowed inside a popup node.

     UDO breaks line after 60 characters but it doesn't print an error
     message  if  you use more than 12 lines, images or links inside a
     popup node.

 There's always an empty line at the end of a popup node, why?

     UDO reads in the source file line  by  line.  If  an  empty  line
     appears  UDO  will print the last paragraph and an empty line for
     separation.

     UDO does the same when printing the text of  a  popup  node.  The
     problem cannot be solved, I'm sorry.

 Some cells of my table are too wide, why?

     The ST-Guide  has a built-in italic correction which is active in
     tables, too. Unfortunately the ST-Guide  adds  a  blank  when  it
     reads  an  italic-off command. This problem can only be solved by
     Holger Weets, the author of ST-Guide.

     Thus you shouldn't use italic text inside tables when  converting
     to  ST-Guide  until  Holger doesn't offer a command for disabling
     the italic correction.

 The HCP prints the error message "please add...", why?

     If the HCP prints the  error  message  "please  add  a  @subject-
     command  to  this text" at the end of converting the STG file you
     have forgotten to insert a line like the  following  one  at  the
     beginning of your UDO source file:

          !stg @subject "Documentation/Utilities"


A.10  Questions concerning Texinfo
==================================

GNU Texinfo  is  used on many Unix systems to offer the user an online
hypertext manual and a printed documentation that  can  be  made  with
`Makeinfo' or plain TeX. Online manuals can be displayed with `Info'.

On systems with 8+3-filenames UDO saves files with the suffix .tex. If
the operating systems supports long  filenames  UDO  uses  the  suffix
.texi instead.

 Why does UDO change the chapter names?

     Makeinfo and/or  Info  get  problems  if a chapter names contains
     brackets, commas or colons. UDO is forced to delete these charac-
     ters so that you will be able to convert the output with Makeinfo
     without any problems. If a chapter name contains  only  forbidden
     characters UDO encodes them.

     You will  only  see  the  changed  chapter  names inside the Info
     headlines and Info menus. If you convert the  Texinfo  file  with
     TeX you will get your original chapter names.

 Why doesn't Texinfo display the environments in "compressed" form?

     Using Texinfo  it's  impossible  to smaller the paragraph separa-
     tion. Thus the parameter !short is  useless  when  converting  to
     Texinfo.


A.11  Questions concerning Turbo Vision Help
============================================

This format  is  used to make online manuals for DOS programs that are
compiled with Borland's Turbo Vision library. UDO's output has  to  be
converted  with TVHC.EXE. The source code of TVHC.EXE is available and
you have to change some parts because it contains some bugs.

If you aren't an author that programs software  that  uses  the  Turbo
Vision library you shouldn't use this format.

 TVHC prints the error message "Unterminated topic reference"!?

     My TVHC  version  1.0  contains  an ugly bug. Due to this bug you
     cannot quote brackets by using them twice. If  your  TVHC  prints
     the  upper error message look for the function scanForCrossRefs()
     in tvhc.cpp and patch it like this:

     Original version:

          if (line[i+1] == begXRef)
          {
              strdel(line, i, 1);
                  ++i;
          }

     Patched version:

          if (line[i] == begXRef)    // [i] instead of [i+1]
          {
              strdel(line, i, 1);
                  ++i;
          }

     After having changed the source code you should recompile TVHC to
     enable the changes.

 TVHC prints the error message "Text too long"!?

     The file  tvhc.h contains a constant number named bufferSize that
     defines the maximum size of the text buffer. This text buffer  is
     a  little  bit small. You should increase the buffer size e.g. to
     32 KB to suppress the upper error message:

          const bufferSize = 32768;

     After having changed the buffer size you should recompile TVHC to
     enable the changes.

 TVHC prints the error message "TOPIC expected"!?

     This error  message is printed if a line starts with a point. The
     point is a special character in Turbo Vision Help if  it  is  the
     first character of a line. My TVHC stops if it reads such a line.

     But there's  no  need to stop the conversion. Thus I have patched
     my TVHC. I have replaced this line

          error("TOPIC expected");

     with

          warning("TOPIC expected");

     If you recompile the TVHC it will print a warning and it will  go
     on  converting  the  source  file  instead  of  printing an error
     message.


A.12  Questions concerning Windows Help
=======================================

 WinHelp says that the RTF-File isn't a Windows Help file. Why?

     The RTF file UDO saves isn't a Windows Help file. It's  just  the
     source  code  of  a  Windows  Help file! You have to convert this
     source code with the Microsoft Helpcompiler to get a Windows Help
     file.

 Where can I get the Microsoft Helpcompiler?

     You can   download   the   Microsoft  Helpcompiler  HC31.EXE from
     Microsoft's FTP server (ftp.microsoft.com) free  of  charge.  You
     shall find the HC where UDO is available, too.

 Why doesn't want the HC to compile UDO's output?

     This can have two reasons:

       1. The  UDO  source file contains errors. Please take a look at
          UDO's log file (suffix `.ulw') and correct  the  errors  you
          will  find  there. If the log file doesn't contain any error
          messages your source file  may  contain  errors  UDO  hasn't
          detected.

       2. The HC is working incorrectly. Take a look at the HC's error
          file (suffix `.err'). Unfortunately I  can't  tell  you  the
          sense of the errors printed in the error file in most cases.

 What is the file `.hpj' good for?

     When converting  to  Windows Help UDO will save an RTF file and a
     project file for the Microsoft  Helpcompiler  named  `.hpj'.  You
     have  to start the HC by passing the name of this project file to
     get a Windows Help file.

     This project file contains several information e.g. the title  of
     the  help  file,  code for adding additional buttons, the size of
     the main window when opening the help file.

     UDO will overwrite this project file  without  previously  asking
     you  if you want it. So, if you have changed the project file and
     you want to protect your changes you have to  write  protect  the
     project file.

 How does UDO generate headlines?

     UDO prints on every page (without the title page and the table of
     contents) a headline.  In  this  headline  the  chapter  name  is
     printed  inside  a  non-scrolling region. Thus you can see always
     the chapter name even if you scroll the text.

     If you use the switch !no_headlines [win] inside the preamble  no
     headlines will be printed.

     If you  use the command !ignore_headline inside a chapter in this
     chapter no headline will be printed.

 How does UDO create the context strings?

     If you want to create a link from another help file or a  program
     to  a  help  file that was made with UDO you have to know how UDO
     creates the context strings.

     Windows Help doesn't  allow  to  use  special  characters  inside
     context strings. UDO creates the context strings in the following
     way:

       1. Special characters are printed in RTF form.

       2. Blanks will be replaced by underscores.

       3. All other characters except  numbers  and  letters  will  be
          replaced   by   their   hexadecimal  value  with  a  leading
          underscore.

     An example with German words:

          UDO:     !node LaTeX-Einfhrung Teil 1
          WinHelp: #{footnote # LaTeX_2DEinf_5C_27FChrung_Teil_1}

     Description:

       1. The hexadecimal ASCII code of the dash is `0x2D'.  The  dash
          will be replaced by `_2D'.

       2. The  `'  inside  `Einfhrung'  is printed in RTF files like
          `\'FC'. The ASCII code of the backslash (`\') is `0x5C',  so
          the  backslash  will be replaced by `_5C'. The ASCII code of
          `'' is `0x27', so the apostrophe will be replaced by `_27'.

       3. The blanks will be replaced by `_'

     Thus the single letter "" will be replaced by  the  really  long
     string  `_5C_27FC' wird. Maybe you want to say that this is quite
     awkward but if UDO would simply replace the "" by "FC"  problems
     would  appear  very soon. Using the upper way the chance that UDO
     creates a context string that is already used is very small.

 Why doesn't UDO center tables?

     It's impossible to center table in Windows Help.

 Why are there no lines inside tables?

     Windows Help doesn't allow it to layout complex  tables  like  in
     RTF.  It's  impossible  to tell Windows Help where to draw lines.
     It's only possible to tell Windows Help to print table cells with
     or without frames.

 Indents in lists and cells in tables are too width, why?

     UDO doesn't know the width of the characters you use inside lists
     and tables. Thus UDO is forced to calculate with values  so  that
     even  bold and italic capital letters will fit the cells. I think
     that it's better to have cells with a width  that  is  too  large
     than too small.

 How can I print graphic characters from the IBM-PC character set?

     Sorry, there's no way to print them.

     I don't  know  the  reason  but  Windows Help won't use the fonts
     "Terminal" or "MS LineDraw". Windows Help will always use another
     font  if you want to use the upper fonts that contain the graphic
     characters.

     Thus UDO will  replace  the  graphic  characters  of  the  IBM-PC
     character set by "+", "-" or "|".



======================================================================
Appendix B

Bugs
======================================================================

The following known bugs will be fixed as fast as possible:

 Text styles inside indices: Inside indices you cannot use text styles
     at the moment. You can avoid this problem of  you  use  the  text
     style commands outside the (!idx ...) placeholder.

 Images & emTeX: The  output  of LaTeX commands for displaying MSP and
     PCX images with emTeX wasn't tested enough. If you have  problems
     printing  the  images  use the switch !no_images [tex] inside the
     preamble and write your own commands inside a raw environment.

 Small mistakes when layouting WinHelp: If you use many  chapters  and
     the  chapter numbers become "too wide" there may be wrong indents
     in the tables of contents. You can avoid this by using the switch
     !no_numbers [win] in the preamble.

 Tables of contents: In  the  tables  of  contents long chapter titles
     aren't sized to the current document width  yet.  Chapter  titles
     may also appear in different columns ("1.9"-"1.10" problem).

If you  detect  another  bug  please  let me (see "Contact addresses")
know. Please add the following details to your bug report:

    Which UDO version do you use?

    On which operating system do you use UDO?

    Does the bug appear every time or only sometimes?

    Do you have an idea why UDO is working incorrectly?

    Can you give me a short example where I can reproduce the bug?

    If the error is format specific what  do  you  think  UDO  should
     output?



======================================================================
Appendix C

Error messages
======================================================================

UDO prints  all  error  messages,  warnings and hints that appear when
converting the source file to files with the suffix .ul?. Each message
is constructed the following way:

       Error: <file> <line number>: <text>
     Warning: <file> <line number>: <text>
        Hint: <file> <line number>: <text>

If you want to avoid these errors, warnings and hints open the printed
file, go to the printed line and try to find the error. Start with the
first  printed error and convert your source file once again. A lot of
messages will disappear because they depend on earlier errors.

 `...' called twice

     The printed command was used twice or more inside the source file
     even if it's only to use it once.

 `...' expected

     UDO has  expected  the printed command. Please check if all envi-
     ronments were finished with the correct command or if a  !begin_*
     is missing.

 `...' followed by `...'

     You have finished an environment with an incorrect command or you
     have forgotten to finish it. Another possibility is that you have
     misplaced the !end_* command.

 `...' ignored inside preamble

     It's only allowed to use the printed command inside the main part
     of the source file.  That  means  you  have  to  place  it  after
     !begin_document.

 `...' ignored outside preamble

     It's only  allowed to use the printed command inside the preamble
     of the source file. That  means  you  have  to  place  it  before
     !begin_document.

 `...' maybe not available in LaTeX

     The printed character cannot be used for LaTeX. Please try to use
     another character.

 `...' not active

     A text style or a footnote shall be finished  even  if  it  isn't
     active.  Please  note  that  the  placeholders  contain a capital
     letter for activating a text style. The placeholders that  finish
     a text style contain a small letter.

 `...' not available in ISO Latin 1

     ISO Latin1  doesn't  contain  the  printed  character.  Thus, UDO
     cannot convert the printed character.

 `...' not available in this charset

     The printed character isn't available  in  the  system  character
     set. Thus, UDO cannot convert it. Please try to avoid the printed
     character.

 `...' still active

     A text style or a footnote shall be started even  if  it's  still
     active.  Please  note  that  the  placeholders  contain a capital
     letter for activating a text style. The placeholders that  finish
     a text style contain a small letter.

 `...' without `...'

     You wanted  to  finish  an  environment even if it wasn't startet
     before.

 !else without !if

     You have used the !else command but you haven't startet  a  query
     with !if, !ifdest etc.

 !endif without !if

     Your source  file  contains  an  !endif command  but  you haven't
     startet a query with !if, !ifdest etc.

 `!item' outside environment

     You have  used  the   !item command   outside   an   itemization,
     enumeration, description or list.

 check this paragraph

     UDO prints  a  filename  and a line number where you can find the
     reason for the upper printed error message.

 couldn't open <file> (pass1)

     UDO couldn't open the printed file in the first of two passes.

 couldn't open <file> (pass2)

     UDO couldn't open the printed file in  the  second  pass.  Please
     check the filename you have used for !include.

 couldn't open destination file

     UDO couldn't open the destination file. Please check the filename
     or remove file protection of the existing file.

 couldn't open hypfile

     UDO couldn't open the hyphenation file. Please check the filename
     or remove file protection of the existing file.

 couldn't open logfile

     UDO couldn't  open  the  log  file.  Please check the filename or
     remove file protection of the existing file.

 couldn't open source file

     UDO couldn't open the source file. Please check the filename.

 couldn't open treefile

     UDO couldn't open the tree file. Please  check  the  filename  or
     remove file protection of the existing file.

 couldn't read BMP header

     The printed  file  isn't  a  Windows  Bitmap  or the file doesn't
     exist.

 couldn't read IMG header

     The printed file isn't a GEM image or the file doesn't exist.

 couldn't read MSP header

     The printed file isn't a MSP image or the file doesn't exist.

 couldn't read PCX header

     The printed file isn't a PCX image or the file doesn't exist.

 couldn't replace (!ilink ...)

     A manual image link couldn't be replaced. You are allowed to  use
     up  to 200 internal and external links and internal images inside
     each paragraph. Split up the paragraph in two or  more  parts  or
     delete some links.

 couldn't replace (!img ...)

     An internal image couldn't be replaced. You are allowed to use up
     to 200 internal and external links  and  internal  images  inside
     each  paragraph.  Split  up the paragraph in two or more parts or
     delete some links.

 couldn't replace (!link ...)

     A manual link couldn't be replaced. You are allowed to use up  to
     200  internal  and external links and internal images inside each
     paragraph. Split up the paragraph in two or more parts or  delete
     some links.

 couldn't replace (!xlink ...)

     An external  link couldn't be replaced. You are allowed to use up
     to 200 internal and external links  and  internal  images  inside
     each  paragraph.  Split  up the paragraph in two or more parts or
     delete some links.

 couldn't write IMG header

     UDO couldn't  open  the  printed  file  for  changing  the  image
     information.   Maybe   the  file  doesn't  exist  or  it's  write
     protected.

 definition contents longer than ... characters

     The contents of a definition exceeds the maximum number of  char-
     acters. Please shorten your definition contents.

 definition name longer than ... characters

     The name  of  a  definition exceeds the maximum number of charac-
     ters. Please shorten your definition name.

 language ... not supported

     The printed language isn't supported  by  UDO  yet  or  you  have
     written the language in a wrong way.

 link destination undefined

     The destination  of  a  manual  link  isn't  defined.  That means
     there's no chapter or label exisiting with the given name.

 macro contents longer than ... characters

     The contents of a macro exceeds the maximum number of characters.
     Please shorten your macro contents.

 macro name longer than ... characters

     The contents of a macro exceeds the maximum number of characters.
     Please shorten your macro name.

 memory allocation failed

     UDO couldn't  allocate  the  needed  memory.  It   doesn't   stop
     converting the source file but you should take a look at the des-
     tination file if it's OK.

 missing parameter(s)

     A command needs a specific numer of parameters and you have  used
     not  enough  parameters.  Check  the  command  and add the needed
     parameters.

 odd number of ''

     The source file contains an odd number of double apostrophes. UDO
     will find this error at the end of a chapter so check the chapter
     above the printed line number.

 odd number off ""

     The source file contains an odd number of double quotes. UDO will
     find  this  error  at  the  end of a chapter so check the chapter
     above the printed line number.

 overfull line

     A line of a verbatim environment is  longer  than  the  value  of
     !parwidth. Try to cut the line or increase the paragraph width.

 source and destination file are equal

     You have  tried  to  read  and  write  the  same file. Check your
     command line options.

 string buffer overflow

     Please contact the author.

 too many aliases used

     Your source file contains too many !alias commands. Please delete
     some  unimportant  aliases or contact the author to get a special
     version of UDO.

 too many columns used

     Your source file contains a table with too many columns.

 too many defines used

     Your source file contains more than 128 definitions.

 too many environments used

     You have used too many environments  into  one  another.  Try  to
     layout your source file less complex.

 too many files opened

     During the  conversion  too  many  files  were opened. Check your
     source file if you constructed a recursive include.

 too many hyphens used

     Your source file  contains  too  many  syllabification  patterns.
     Delete some of them and use local syllabification marks.

 too many items inside enumeration

     You have  used  too  many  items  inside an enumerate environment
     where items are marked with letters. Reduce the ammount of  items
     to 26 or use an itemize environment instead.

 too many labels used

     Your source  file  contains too many !label commands. Because UDO
     handles chapters and aliases like labels, too, this error message
     can  appear  when  using  only  some  labels.  Please delete some
     unimportant labels or aliases or contact  the  author  to  get  a
     special version of UDO.

 too many macros used

     Your source file uses more than 128 macros.

 too many nodes used

     Your source file uses too many chapters. If possible try to merge
     some chapters or contact the author to get a special  version  of
     UDO.

 too many parameters used

     A command  or  placeholder  was  called with too many parameters.
     Check the command and look for additional information inside  the
     command index.

 too many rows used

     Your source file uses a table with too many rows.

 too many words used inside paragraph

     A paragraph of your source file uses too many words. Try to split
     up the paragraph into two or more parts.

 underfull line

     The printed line is too short and you  will  see  an  ugly  right
     margin.  If  you  use  justification this error message says that
     there were inserted too many blanks.  Try  to  insert  syllabifi-
     cation  marks or use the !sloppy command to suppress this type of
     error message.

 unexpected end of line in command

     Your source file contains  a  placeholder  that  wasn't  finished
     correctly.

 unknown command

     UDO doesn't know the printed command. If you want to use a word a
     the beginning of a line that begins with an exclamation mark  you
     have to mark it with a slash (`/').

 use (!V) and (!v) in one line

     Something's still missing here...

 use (!xlink [text] [topic@foo.hlp])

     The construction   of  an  external  link  for  Windows  Help  is
     incorrect.

 wrong number of parameters

     You called a command or placeholder  with  the  wrong  number  of
     parameters. Check the command index for additional information.

 xlink needs WinHelp destination topic

     The construction   of  an  external  link  for  Windows  Help  is
     incorrect. Here the name of the page is missing.

 xlinks needs WinHelp destination file

     The construction  of  an  external  link  for  Windows  Help   is
     incorrect. Here, the name of the Windows Help file is missing.



======================================================================
Appendix D

This & that
======================================================================


D.1  Facts, facts, facts
========================

You can use source files that don't exceed these maximum values:

 Macros:                              128
 Defines:                             128
 Hyphenation patterns:                4096
 Sum of chapters, labels and aliases: 6144
 Characters per line:                 512
 Characters per word:                 128
 Syllables per word:                  32
 Words per paragraph:                 800
 Links per paragraph:                 200
 Rows per table:                      256
 Columns per table:                   32
 Depth of environments:               6


Do you know how much work it has been to program UDO and to write this
documentation? Here's the answer:

 Source code:           820 KB
 German Documentation:  470 KB
 English Documentation: 420 KB


D.2  Programming environment
============================

UDO has been developed using the following software:

 Atari:     Pure C 1.1, Pure Profiler 1.0,  MiNT-Libs  PL  46,  SysGem
            2.03beta,  Interface  2.3,  Programming Tools by Julian F.
            Reschke, MagiC-PC 1.01

 DOS:       EMX-GCC 2.6.3 emxfix06, GDB 4.13, PFE

 HP-UX:     GCC 2.7.2

 Linux:     GCC 2.7.2, S.u.S.E. Linux 4.3 Kernel 2.0.18, Joe

 Macintosh: CodeWarrior 9 (68K/PPC), ResEdit 2.1

Currently I develop UDO on a Pentium 133 running Windows 95  with  the
EMX-GCC and on my Compaq Contura 486-DX50 notebook running Linux.



This documentation has been written with the following software:

    Joe Allan's Own Editor `Joe' for MS-DOS and Linux
    Allan  Phillips' Programmer's File Editor `PFE' 0.06.01 (the best
     editor for Windows 3.1 and Windows 95 I know)
    Phoenix for Windows 3.11 by Application Systems Heidelberg  (also
     available as Fuji Base 1.0)


D.3  Generated files
====================

A short description of the files, UDO saves next to its log files:

 .1:       Nroff
 .c:       C source code
 .cmd:     command file for the Pure C help compiler
 .txt:     ASCII
 .hpj:     project file for the Microsoft Help Compiler HC.EXE
 .htm(l):  HTML
 .lyx:     LyX
 .man:     Manualpage
 .pas:     Pascal source code
 .rtf:     RTF or WinHelp source code or QuickView source code
 .scr:     Pure C Help source code
 .sgm(l):  Linuxdoc-SGML
 .stg:     ST-Guide source code
 .txt:     Turbo-Vision-Help source code
 .tex:     LaTeX
 .texinfo: Texinfo

Files with the suffix .ul? contain the error messages and warnings UDO
prints while converting the source file.

Files with the suffix .uh? contain the  syllabification  patterns  UDO
prints for ASCII, ST-Guide and Pure C Help.

Files with the suffix .ut? contain the "include tree".

The following  suffixes  appear  if  UDO  saves  a file that has to be
converted with another software to get the final result:

 .err: log file of the Microsoft Help Compiler (HC.EXE)

 .h:   C header file for Turbo Vision (TVHC.EXE)

 .hlp: Windows Help file (HC.EXE), Turbo Vision Help file  (TVHC.EXE),
       Pure C Help file (HC.PRG)

 .hyp: ST-Guide hypertext (HCP.TTP)

 .ref: ST-Guide reference file (HCP.TTP)



======================================================================
Appendix E

History
======================================================================

In this  chapter  you  will find a short summary of all the changes in
the past.


E.1  Last minute changes
========================

In this section you will find all the changes that aren't discussed in
the other parts of this documentation yet.

  1. Destination format "NROFF"

     I don't know if UDO really saves NROFF or if it's TROFF or GROFF.
     But you can already use it  to  make  simple  manpages  for  Unix
     systems.

  2. Destination formats "C source code" and "Pascal source code"

     Using these  formats  it's  possible to edit a C or Pascal source
     code and its documentation in one file.

     UDO will print "normal" text using the comment characters of C or
     Pascal. The source code will be printed without conversion.

  3. The sourcecode environment

     Lines that  are  part of a sourcecode environment will be printed
     for C and Pascal  without  any  conversion.  If  you  convert  to
     "normal"  formats,  UDO  prints  the lines as they were part of a
     verbatim environment that is used inside a quote environment.

A small example of a C source code written with UDO:

     !program Hello, world!
     !author Dirk Hagedorn
     
     !begin_document
     
     !node Hello, World
     This program is just for demonstrating
     the sourcecode environment.
     
     !begin_sourcecode
     #include <stdio.h>
     
     int main ( void )
     {
             printf("Hello, world!\n");
     
             return 0;
     }
     !end_sourcecode
     
     !end_document


E.2  Release 6
==============

UDO6 was released on January 3rd, 1997.

You will find here a very compressed list of the major changes of  the
last  eight  months.  UDO  supports  now  more destination formats, it
supports new features and there were fixed a  lot  of  bugs.  In  some
cases it was impossible not to change the syntax of some commands.

 New destination formats:

         Apple QuickView
         HP-HelpTag-SGML (rudimentr)
         LyX
         C and Pascal source code (see "Last minute changes")
         NROFF (see "Last minute changes")

 New commands:

         !autoref_items [off|on]:  Shall UDO insert links in items of
          descriptions and lists?
         !code_mac, !code_hp8,  !code_iso,  !code_dos and  !code_tos:
          UDO  understands  now  the character sets of other operating
          systems.
         !country: Additional title page information.
         !html_backpage: For a back-link on the HTML title page.
         !html_keywords: For HTML meta information.
         !html_img_suffix: To enable you to use JPEG images etc.
         !html_nodesize:  For  changing  the  font   size   of   HTML
          headlines.
         !ifos und !ifnos: For checking the operatin system.
         !ignore_headline,  !ignore_bottomline:  For  suppressing the
          headline or the bottomline of a specific node.
         !ignore_subtoc und Verwandte: For suppressing the  sub-table
          of contents inside a specific node.
         !ignore_links: For suppressing links to a specific node.
         !image*: For printing image captions without "Figure #:".
         !image_counter: For changing the image counter.
         !no_index: For suppressing index command conversion.
         !no_toc_subnodes,                       !no_toc_subsubnodes,
          !no_toc_subsubsubnodes: For making  the  table  of  contents
          smaller.
         !no_preamble: Useful if you want to write your own preamble.
         !parwidth:  For changing the paragraph width of the destina-
          tion file.
         !rtf_charwidth:  For  changing  the  value  UDO   uses   for
          calulating indents and cell widths.
         !set,  !unset,  !ifset,  !ifnset:  For  setting and checking
          symbols.
         !sort_hyphen_file: Shall UDO sort the hyphen file and delete
          duplicates?
         !subsubsubnode und Verwandte: A fourth layer.
         !table_counter: For changing the table counter.
         !table_caption*:  For printing table captions without "Table
          #:".
         !tabwidth: For setting the tabulator width for verbatim  en-
          vironments.
         !use_justification: Shall UDO generate justification?
         !use_nodes_inside_index,            !use_alias_inside_index,
          !use_label_inside_index: For appending  nodes,  aliases  and
          labels to the index.
         !use_output_buffer:  Shall  UDO  use  a  buffer  to make the
          referencation more perfectly for HTML and Windows Help?
         !use_short_envs: For  printing  always  compressed  environ-
          ments.
         !verbatimsize:  For changing the font size of verbatim envi-
          ronments.
         !win_background: For  changing  the  background  colour  for
          Windows Help.
         !win_high_compression,  !win_medium_compression: For setting
          the compression rate for Windows Help.
         !win_inline_bitmaps: Shall UDO use special RTF commands  for
          using inline bitmaps?
         !win_charwidth:   For   changing  the  value  UDO  uses  for
          calulating indents and cell widths.

 News:

         You can use four layers now for structuring your text.
         Justification
         Macros and definitions can contain parameters. Thus, you can
          write your own commands in most cases.
         blist environment, ilist environment and tlist environment
         right justified text (flushright environment)
         left  justfied  text (flushleft environment) for suppressing
          the justification
         You can use up to four E-Mail addresses on  the  title  page
          now.
         UDO   supports   Italian   (!language   italian),   Spanisch
          (!language spanish) and Swedish (!language swedish) now.
         UDO can sort the hyphen file and delete duplicates.
         !no_umlaute converts now all international  characters,  not
          only the German umlauts.
         The source code was optimized. Although UDO supports lots of
          new commands this version of UDO runs faster  than  the  old
          one.

 Changes:

         The RTF output was programmed completely new. You can import
          UDO's RTF files without problems in WinWord.
         UDO saves a preamble for LaTeX 2.09 and LaTeX2e on  its  own
          (you can switch it off, if you want).
         UDO  allows  you to use many more nodes, table rows, hyphens
          etc.
         UDO checks the source files more pedantically.
         Images are positioned like the  outer  text.  To  center  an
          image you have to use the !image command inside a center en-
          vironment. Thus, you can  print  left  and  right  justified
          images, too.
         The suffix for ASCII files is now .txt.
         UDO  doesn't  break  line  between  \verb when converting to
          LaTeX.
         Graphic characters of the  IBM  PC  character  set  will  be
          replaced by `+', `-' and `|' for Windows Help.

 Syntax changes:

         !no_verbatim_umlaute replaces           the           switch
          !verbatim_no_umlaute
         The switch !list_parsep doesn't exist anymore. You can print
          "compressed" environment easier with !short now.
         The  language of the destination file has to be set with the
          !language command   now.   !language english replaces    the
          command !endlish.
         You  can  pass  three  index entries with one !index command
          now.
         !win_html_look doesn't exist anymore.
         Shdowed, hollow, outlined and framed  text  isn't  supported
          anymore.   But   you  can  define  your  own  commands  with
          definitions if you need these text styles.


E.3  Release 5
==============

A very short description of the major changes I added to this  release
for the last five months is listed here. It wasn't possible to prevent
a change of the syntax of some commands.

 New destination formats:
         Linuxdoc-SGML
         Turbo Vision Help
         Texinfo
 New commands:
         !alias
         !begin_raw, !end_raw
          inside the raw environment you can  enter  special  commands
          for a destination format
         !begin_table, !end_table
          setting tables like in LaTeX!
         !chapterimage
          an image can be used for the title of a chapter
         !define
         !french
          for French expressions
         !heading, !subheading, !subsubheading
          for displaying headlines
         !hline
          for displaying horizontal lines
         !htmlname
          to set the filename of a chapter
         !html_merge_nodes,                     !html_merge_subnodes,
          !html_merge_subsubnodes
          for merging chapters when converting to HTML
         (!ilink ...)
          for displaying images with links inside  the  text,  Windows
          Help and HTML only
         (!img ...)
          for displaying images inside the text, Windows Help and HTML
          only
         !index
          for setting an index entry
         !list_parsep
          for switching the use of empty lines between items of an en-
          vironment
         !ifdest, !else, !endif
          for special passages
         !iflang, !else, !endif
          for special passages with different languages
         !node*,   !subnode*,   !subsubnode*,   !pnode*,  !psubnode*,
          !psubsubnode*
          for chapters that don't appear inside a table of contents
         !rinclude
          for including special commands
         !use_about_udo
         !use_chapter_images
          for displaying images instead of chapter titles
         !use_style_book
         !win_html_look
          for using grey inside a Windows Help file
 Changes:
         You can display tables very easily. You can  define  how  to
          justify  columns  and  where to draw horizontal and vertical
          lines.
         The layout of the  environments  was  programmed  completely
          new.  Now you can use up to six environments inside another,
          the xlist environment, too! UDO generates a  correct  output
          for Windows Help and RTF.
         The  semiautomatic syllabification was programmed completely
          new.
         UDO now references only complete words.
         You can use 1024 chapters and 1024 labels now.
         You can use up to 200 links inside a paragraph. Due to a bug
          you  could  only  use 16 links inside a complete document in
          release 4.
         Manualpages are layouted completely new.
         Paintbrush PCX images are supported for emTeX.
         The output of Windows Help was updated in many cases!
         The Atari versions were compiled with MiNT libs PL46.
 Syntactical changes:
         The special environments  that  were  built  with  !begin_*,
          !else_* and  !end_* have  to  made  with  the  more flexible
          commands !ifdest, !else and !endif.
          Instead of...
               !begin_asc
               [...]
               !else_asc
               [...]
               !end_asc
          ... you now have to use this construction:
               !ifdest [asc]
               [...]
               !else
               [...]
               !endif
 Bug fixes:
     Innumerous. ;-)


E.4  Release 4
==============

This was the first English version with an English documentation!


E.5  Release 3
==============

I think that nobody is interested in those things that changed a  year
ago.



======================================================================
Appendix F

Command index
======================================================================

In this chapter you will find a short description of every UDO command
in alphabetical order. The command description shows you  the  meaning
of the descriptions.


Command description
===================

 Type & position:
     The  type  of  the command and the position where it's allowed to
     use it.

     A command tells UDO do something especially, a switch  sets  some
     internal  information  for  UDO  and a placeholder will be simply
     replaced by a different text fragment.

     "Preamble" means that you are only allowed to use this command in
     the  preamble of your source file (before !begin_document). "Main
     part"  means  that  you  are  only  allowed  to  use  it   behind
     !begin_document.  "Preamble  &  main part" means that you can use
     this command wherever you want.

 Syntax:
     Here you can see how to use the command.

      <text>         replaces text

      <file>         replaces a file name

      <value>        replaces a number

      <char>         replaces a single character

      <abbreviations> replaces the  abbreviation  of  the  destination
                     formats (aqv = Apple QuickView, asc = ASCII, 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 = WinHelp)

      <language>     replaces  the  abbreviation  of  the  destination
                     language (english  =  English,  french  = French,
                     german = German, italian  =  Italian,  spanish  =
                     Spanish, swedish = Swedish)

      <systems>      replaces  one  or  more operating systems (beos =
                     BeOS, dos = DOS, hpux =  HP-UX,  linux  =  Linux,
                     macos  =  MacOS,  nextstep  =  NeXTStep,  sinix =
                     SINIX, sunos = SunOS, tos = TOS)

 Example:
     Here you can see a small example.

 See also:
     Related commands and topic are listed here.


F.1  A...
=========


F.1.1  !=aqv
------------

 Type & position: command, preamble & main part

 Syntax:          !=aqv <text>

 Description:     "<text>" will only be printed if  you  don't convert
                  into   Apple   QuickView.   "<text>"   will  be  not
                  converted!

 See:             !aqv, !ifdest, raw environment


F.1.2  !=asc
------------

 Type & position: command, preamble & main part

 Syntax:          !=asc <text>

 Description:     "<text>" will only be printed if  you  don't convert
                  into ASCII. "<text>" will be not converted!

 See:             !asc, !ifdest, raw environment


F.1.3  !alias
-------------

 Type & position: command, main part

 Syntax:          !alias <text>

 Description:     "<text>"  is  used as a secondary name of a chapter.
                  UDO references an alias like a label or  node  name.
                  You  can use !alias inside a chapter more than once.
                  But you should use <text> only once.

 See:             !node,   !subnode,   !subsubnode,    !subsubsubnode,
                  !label, Links, Labels


F.1.4  !aqv
-----------

 Type & position: command, preamble & main part

 Syntax:          !aqv <text>

 Description:     "<text>"  will  only  be printed if you convert into
                  Apple QuickView. "<text>" will be not converted!

 See:             !=aqv, !ifdest, raw environment


F.1.5  !asc
-----------

 Type & position: command, preamble & main part

 Syntax:          !asc <text>

 Description:     "<text>" will only be printed if  you  convert  into
                  ASCII. "<text>" will be not converted!

 See:             !=asc, !ifdest, raw environment


F.1.6  !author
--------------

 Type & position: command, preamble

 Syntax:          !author <text>

 Description:     "<text>"  will  be used as the name of the author on
                  the title page and for different other purposes.

 Example:         !author Dirk Hagedorn

 See:             !maketitle, !authorimage, Title page


F.1.7  !authorimage
-------------------

 Type & position: command, preamble

 Syntax:          !authorimage <file>

 Description:     <file> will be  displayed  above  the  name  of  the
                  author  on  the title page if the destination format
                  supports images.

 Example:         !authorimage dh

 See:             !maketitle, !author, Title page, Images


F.1.8  !autoref
---------------

 Type & position: switch, main part

 Syntax:          !autoref [ on | off ]

 Description:     Switches on or off automatic  references.  When  UDO
                  starts  it  will  insert references automatically by
                  default. For the ST-Guide UDO  prints  @autorefon or
                  @autorefoff.

 Example:         !autoref [off]

 See:             Links


F.1.9  !autoref_items
---------------------

 Type & position: switch, main part

 Syntax:          !autoref_items [ on | off ]

 Description:     With  this  command  you can switch on or off if UDO
                  shall insert links in items of a  description  envi-
                  ronment  or  xlist  environment.  When UDO starts it
                  inserts links by default.

 Example:         !autoref_items [off]

 See:             Descriptions, Lists, !item [ ]


F.1.10  (!alpha)
----------------

 Type & position: placeholder, preamble & main part

 Syntax:          (!alpha)

 Description:     This placeholder will be replaced by an alpha.

 Example:         (!alpha) becomes alpha

 See:             (!beta), Special characters


F.2  B...
=========


F.2.1  !begin_appendix
----------------------

 Type & position: command, main part

 Syntax:          !begin_appendix

 Description:     Starts the appendix. Chapters  are  enumerated  with
                  letters.  UDO  supports only one appendix per source
                  file!

 See:             !end_appendix, Appendix


F.2.2  !begin_blist
-------------------

 Type & position: command, main part

 Syntax:          !begin_blist [<text>]

 Description:     Starts a new list. The length  of  "<text>"  defines
                  the  indent  of  the  list. This environment must be
                  finished with !end_blist. You can use this  environ-
                  ment  inside  other  environments.  The text you set
                  with !item [ ] will be displayed with a bold font.

 See:             !end_blist, !item [ ],  !begin_ilist,  !begin_tlist,
                  !begin_xlist, Lists


F.2.3  !begin_center
--------------------

 Type & position: command, main part

 Syntax:          !begin_center

 Description:     This  command opens a (new) center environment. Text
                  that is part of a center environment will be printed
                  centred  until  the !end_center command appears. UDO
                  layouts the text of a center environment so you will
                  may  be  be  forced to insert manual linebreaks with
                  (!nl).

 See:             !end_center, (!nl)


F.2.4  !begin_description
-------------------------

 Type & position: command, main part

 Syntax:          !begin_description

 Description:     Starts a new description environment that has to  be
                  finished  with  !end_description.  You  can  use the
                  description environment inside  other  (description)
                  environments.  Text that stands between the brackets
                  of !item [ ] will be printed with bold text.

 See:             !end_description, !item [ ], Descriptions, !short


F.2.5  !begin_document
----------------------

 Type & position: command, main part

 Syntax:          !begin_document

 Description:     This command must be part of every source  file.  It
                  divides the preamble from the main part.

 See:             !end_document


F.2.6  !begin_enumerate
-----------------------

 Type & position: command, main part

 Syntax:          !begin_enumerate

 Description:     Starts  a  new  enumerate environment that has to be
                  finished  with  !end_enumerate.  You  can  use   the
                  enumerate environment inside other (enumerate) envi-
                  ronments. The items of an enumerate environment will
                  be marked with alphanumerical characters.

 See:             !end_enumerate, !item, Enumerations, !short


F.2.7  !begin_flushleft
-----------------------

 Type & position: command, main part

 Syntax:          !begin_flushleft

 Description:     Lines  that  are  part  of flushleft environment are
                  printed left justified without justification.

 See:             !end_flushleft


F.2.8  !begin_flushright
------------------------

 Type & position: command, main part

 Syntax:          !begin_flushright

 Description:     Lines that are part of  flushright  environment  are
                  printed right justified without justification.

 See:             !end_flushright


F.2.9  !begin_ilist
-------------------

 Type & position: command, main part

 Syntax:          !begin_ilist [<text>]

 Description:     Starts  a  new  list. The length of "<text>" defines
                  the indent of the list.  This  environment  must  be
                  finished  with !end_ilist. You can use this environ-
                  ment inside other (iltalic list)  environments.  The
                  text  you  set with !item [ ] will be displayed with
                  an italic font.

 See:             !end_ilist, !item [ ],  !begin_blist,  !begin_xlist,
                  !begin_tlist, Lists


F.2.10  !begin_itemize
----------------------

 Type & position: command, main part

 Syntax:          !begin_itemize

 Description:     Starts  a  new  itemize  environment  that has to be
                  finished with !end_itemize. You can use the  itemize
                  environment  inside  other  (itemize)  environments.
                  Items of the itemize environment will be marked with
                  bullets, dashes or stars.

 See:             !end_itemize, !item, Itemizations, !short


F.2.11  !begin_quote
--------------------

 Type & position: command, main part

 Syntax:          !begin_quote

 Description:     This command starts a new quote environment. Text is
                  printend indented until  UDO  reads  the  !end_quote
                  command.

 See:             !end_quote, Indented paragraphs


F.2.12  !begin_raw
------------------

 Type & position: command, preamble & main part

 Syntax:          !begin_raw

 Description:     Starts  a  raw  environment  that has to be finished
                  with !end_raw. Each  line  inside  this  environment
                  will be output directly without any conversion. Thus
                  this environment can  be  used  to  insert  specific
                  commands for the destionation format.

 See:             !end_raw, raw environment, !rinclude, !ifdest


F.2.13  !begin_sourcecode
-------------------------

 Type & position: command, main part

 Syntax:          !begin_sourcecode

 Description:     With  this  command you can start a sourcecode envi-
                  ronment.  It   has   to   be   finished   with   the
                  !end_sourcecode command.  Lines  that  are part of a
                  sourcecode  environment  will  be  printed   without
                  conversion  for  the  sourcecode  formats.  For  the
                  "normal" formats the text of the sourcecode environ-
                  ment  will  be printed like text of a verbatim envi-
                  ronment that is used inside a quote environment.

 See:             !end_sourcecode


F.2.14  !begin_table
--------------------

 Type & position: command, main part

 Syntax:          !begin_table [<format>] {!hline}

 Description:     With this command a table is started.  For  <format>
                  you  enter  the justification of the columns of this
                  table and the position of vertical  lines.  If  this
                  command  is  followed  by  `!hline' the table starts
                  with a horizontal line. The  example  shows  how  to
                  make  a  table  with  three  columns  where the left
                  column is left justified, the second is centered and
                  the  last  columns  is  right  justified.  The table
                  begins with a horizontal line an it has one vertical
                  line on the left

 Example:         !begin_table [|lcr|] !hline

 See:             !hline, !end_table, Tables


F.2.15  !begin_tlist
--------------------

 Type & position: command, main part

 Syntax:          !begin_tlist [<text>]

 Description:     Starts  a  new  list. The length of "<text>" defines
                  the indent of the list.  This  environment  must  be
                  finished  with !end_tlist. You can use this environ-
                  ment inside other environments.  The  text  you  set
                  with  !item [ ] will  be displayed with a monospaced
                  font.

 See:             !end_tlist, !item [ ],  !begin_blist,  !begin_ilist,
                  !begin_xlist, Lists


F.2.16  !begin_verbatim
-----------------------

 Type & position: command, main part

 Syntax:          !begin_verbatim

 Description:     Starts   a  verbatim  environment  that  has  to  be
                  finished with !end_verbatim. Text that is part of  a
                  verbatim environment is printed out as given using a
                  monospaced font.

 See:             !end_verbatim, Preformatted text, !vinclude


F.2.17  !begin_xlist
--------------------

 Type & position: command, main part

 Syntax:          !begin_xlist [<text>]

 Description:     Starts a new list. The length  of  "<text>"  defines
                  the  indent  of  the  list. This environment must be
                  finished with !end_xlist. You can use this  environ-
                  ment  inside  other  environments.  The text you set
                  with !item [ ] will be  displayed  with  the  normal
                  font.

 See:             !end_xlist,  !item [ ],  !begin_blist, !begin_ilist,
                  !begin_tlist, Lists


F.2.18  !bigskip
----------------

 Type & position: command, main part

 Syntax:          !bigskip

 Description:     This command will be simplay replaced by  "\bigskip"
                  when  converted to LaTeX. Otherwise three additional
                  empty lines will be generated.

 See:             !smallskip, !medskip


F.2.19  !break
--------------

 Type & position: command, main part

 Syntax:          !break

 Description:     You can use this command inside the source  file  to
                  stop  the conversion right at the line where you use
                  this   command.    UDO    calls    !end_appendix and
                  !end_document itself if necessary.


F.2.20  (!B)...(!b)
-------------------

 Type & position: placeholder, preamble & main part

 Syntax:          (!B)<text>(!b)

 Description:     "<text>" will be displayed in bold text if possible.

 Example:         (!B)bold(!b)

 See:             Emphasizing text


F.2.21  (!beta)
---------------

 Type & position: placeholder, preamble & main part

 Syntax:          (!beta)

 Description:     This placeholder will be replaced by beta.

 Example:         (!beta) becomes beta

 See:             (!alpha), Special characters


F.3  C...
=========


F.3.1  !chapterimage
--------------------

 Type & position: command, main part

 Syntax:          !chapterimage <file>

 Description:     Converting  to  Windows  Help,  HTML or ST-Guide the
                  image called `<file>' is displayed  instead  of  the
                  chapter  title if !use_chapter_images is used inside
                  the preamble.

 Example:         !chapterimage udo

 See:             Images, !use_chapter_images


F.3.2  !code_dos
----------------

 Type & position: switch, preamble & main part

 Syntax:          !code_dos

 Description:     UDO expects files written in  the  IBM-PC  character
                  set  after this command. You can switch back to your
                  system charset with some other commands (see below).

 See:             !code_iso, !code_mac, !code_hp8, !code_tos,  Special
                  characters


F.3.3  !code_hp8
----------------

 Type & position: switch, preamble & main part

 Syntax:          !code_hp8

 Description:     UDO  expects files written in the HP Roman 8 charac-
                  terset after this command. You can  switch  back  to
                  your  system  charset  with some other commands (see
                  below).

 See:             !code_dos, !code_iso, !code_mac, !code_tos,  Special
                  characters


F.3.4  !code_iso
----------------

 Type & position: switch, preamble & main part

 Syntax:          !code_iso

 Description:     UDO expects files written in the ISO characterset or
                  Windows ANSI characterset after  this  command.  You
                  can  switch  back  to  your system charset with some
                  other commands (see below).

 See:             !code_dos, !code_mac, !code_hp8, !code_tos,  Special
                  characters


F.3.5  !code_mac
----------------

 Type & position: switch, preamble & main part

 Syntax:          !code_mac

 Description:     UDO expects files written in the Macintosh character
                  set behind this command. You can switch back to your
                  system charset with some other commands (see below).

 See:             !code_dos,  !code_iso, !code_hp8, !code_tos, Special
                  characters


F.3.6  !code_tos
----------------

 Type & position: switch, preamble & main part

 Syntax:          !code_tos

 Description:     UDO expects files written in the  Atari  ST  charac-
                  terset  behind  this command. You can switch back to
                  your system charset with some  other  commands  (see
                  below).

 See:             !code_dos,  !code_iso, !code_mac, !code_hp8, Special
                  characters


F.3.7  !country
---------------

 Type & position: command, preamble

 Syntax:          !country <text>

 Description:     "<text>" will be displayed below  the  town  of  the
                  author on the title page to show in which country he
                  lives.

 Example:         !country Germany

 See:             !maketitle, Title page


F.3.8  (!copyright)
-------------------

 Type & position: special character(s), preamble & main part

 Syntax:          (!copyright)

 Description:     This placeholder  will  be  replaced  by  a  special
                  copyright  symbol if the destination format supports
                  them.  If  it  doesn't   UDO   will   replace   this
                  placeholder by "(c)".

 Example:         (!copyright) is converted to (c)


F.4  D...
=========


F.4.1  !date
------------

 Type & position: command, preamble

 Syntax:          !date <text>

 Description:     "<text>"  will  be displayed on the title page below
                  the contents of !version. The example shows  how  to
                  use the current system time for the title page.

 Example:         !date (!today)

 See:             !maketitle, (!today), (!short_today), Title page


F.4.2  !define
--------------

 Type & position: command, preamble

 Syntax:          !define <word> <text>

 Description:     Sets  a  (new)  definition. When converting UDO will
                  replace  every  "(!<word>)"  by   "<text>"   without
                  converting  special  chars.  When  using  the  lower
                  exmaple every "(!H1)" will be replaced  by  "</H1>".
                  The  difference  to  a  macro:  no  umlauts or other
                  special chars will  be  converted.  Definitions  can
                  contain  parameters.  Read the chapter "Definitions"
                  to  get  to  know  how  to  use   definitions   with
                  parameters.

 Example:         !define H1 </H1>

 See:             Definitions


F.5  E...
=========


F.5.1  !else
------------

 Type & position: command, preamble & main part

 Syntax:          !else

 Description:     The   following   lines   are  converted  until  the
                  appearance of !endif, if  the  abbreviation  of  the
                  current  destination  format  wasn't  used  with the
                  previous !ifdest or !iflang command.

 See:             !ifdest, !iflang, !endif, Query commands


F.5.2  !email
-------------

 Type & position: command, preamble

 Syntax:          !email <text>

 Description:     "<text>" will be dsiplayed on  the  titlepage  below
                  the  name  and  address of the author. !email can be
                  used up to four times to enable you  to  print  more
                  than one email address on the title page.

 Example:         !email Internet: dh@mk2.maus.sauerland.de

 See:             !maketitle, Title page


F.5.3  !end_appendix
--------------------

 Type & position: command, main part

 Syntax:          !end_appendix

 Description:     This  command  finishes  the  appendix. UDO supports
                  only one appendix, so this  command  should  be  the
                  precessor of !begin_document.

 See:             !begin_appendix, Appendix


F.5.4  !end_blist
-----------------

 Type & position: command, main part

 Syntax:          !end_blist

 Description:     Finsihes the latest blist ("bold list") environment.

 See:             !begin_blist, !item [ ], Lists


F.5.5  !end_center
------------------

 Type & position: command, main part

 Syntax:          !end_center

 Description:     This command finishes the latest center environment.

 See:             !begin_center, center environment


F.5.6  !end_description
-----------------------

 Type & position: command, main part

 Syntax:          !end_description

 Description:     This command finishes the latest descripion environ-
                  ment.

 See:             !begin_description, !item [ ], description  environ-
                  ment


F.5.7  !end_document
--------------------

 Type & position: command, main part

 Syntax:          !end_document

 Description:     This  command  must be  part of a source file and it
                  should be the last command. If  you  forget  to  use
                  this command UDO will print an error message.

 See:             !begin_document


F.5.8  !end_enumerate
---------------------

 Type & position: command, main part

 Syntax:          !end_enumerate

 Description:     Finishes the latest enumerate environment.

 See:             !begin_enumerate, !item, enumerate environment


F.5.9  !end_flushleft
---------------------

 Type & position: command, main part

 Syntax:          !end_flushleft

 Description:     This  command finishes the latest flushleft environ-
                  ment.

 See:             !begin_flushleft, flushleft environment


F.5.10  !end_flushright
-----------------------

 Type & position: command, main part

 Syntax:          !end_flushright

 Description:     This command finishes the latest flushright environ-
                  ment.

 See:             !begin_flushright, flushright environment


F.5.11  !end_ilist
------------------

 Type & position: command, main part

 Syntax:          !end_ilist

 Description:     Finishes  the  latest ilist ("italic list") environ-
                  ment.

 See:             !begin_ilist, !item [ ], Lists


F.5.12  !end_itemize
--------------------

 Type & position: command, main part

 Syntax:          !end_itemize

 Description:     Finishes the latest itemize environment.

 See:             !begin_itemize, !item, itemize environment


F.5.13  !end_quote
------------------

 Type & position: command, main part

 Syntax:          !end_quote

 Description:     This command finishes the  last  quote  environment.
                  Text,  that's  part  of  a quote environment will be
                  displayed indented.

 See:             !begin_quote, quote environment


F.5.14  !end_raw
----------------

 Type & position: command, preamble & main part

 Syntax:          !end_raw

 Description:     Finishes the raw environment.

 See:             !begin_raw, raw environment


F.5.15  !end_sourcecode
-----------------------

 Type & position: command, main part

 Syntax:          !end_sourcecode

 Description:     This command finishes the sourcecode environment.

 See:             !begin_sourcecode


F.5.16  !end_table
------------------

 Type & position: command, main part

 Syntax:          !end_table

 Description:     Finishes the table environment and prints the table.

 See:             Tables, !begin_table


F.5.17  !end_tlist
------------------

 Type & position: command, main part

 Syntax:          !end_tlist

 Description:     Finsihes the latest tlist environment.

 See:             !begin_tlist, !item [ ], Lists


F.5.18  !end_verbatim
---------------------

 Type & position: command, main part

 Syntax:          !end_verbatim

 Description:     Finishes the verbatim environment.

 See:             !begin_verbatim, Preformatted text


F.5.19  !end_xlist
------------------

 Type & position: command, main part

 Syntax:          !end_xlist

 Description:     Finsihes the latest xlist environment.

 See:             !begin_xlist, !item [ ], Lists


F.5.20  !endif
--------------

 Type & position: command, preamble & main part

 Syntax:          !endif

 Description:     Finishes a  query  command  that  was  started  with
                  !ifdest, !iflang, !ifset, !ifos or !if.

 See:             !ifdest,  !iflang,  !ifset, !ifos, !if, !else, Query
                  commands


F.6  F...
=========


F.6.1  !fussy
-------------

 Type & position: switch, main part

 Syntax:          !fussy

 Description:     Switches on  warning  messages  according  to  short
                  lines.  You  can use this command wherever you want.
                  The warnings can  be  disabled  with  !sloppy.  When
                  converting  to LaTeX UDO doesn't convert !fussy into
                  `\fussy'!

 See:             !sloppy, Error messages, Syllabification


F.7  G...
=========


F.7.1  (!grin)
--------------

 Type & position: placeholder, preamble & main part

 Syntax:          (!grin)

 Description:     (!grin) will be  replaced  by  a  grinning  emoticon
                  displayed in typewriter.

 Example:         (!grin) becomes ;-)

 See:             (!laugh)


F.8  H...
=========


F.8.1  !=htag
-------------

 Type & position: command, preamble & main part

 Syntax:          !=htag<text>

 Description:     "<text>"  will  only be printed if you don't convert
                  into Helptag. "<text>" will be not converted!

 See:             !htag, !ifdest, raw environment


F.8.2  !=html
-------------

 Type & position: command, preamble & main part

 Syntax:          !=html <text>

 Description:     "<text>" will only be printed if  you  don't convert
                  into HTML. "<text>" will be not converted!

 See:             !html, !ifdest, raw environment


F.8.3  !heading
---------------

 Type & position: command, main part

 Syntax:          !heading <text>

 Description:     This  command  prints  out  "<text>" like a headline
                  using the chapter font and fontsize.

 Example:         !heading A headline

 See:             !subheading, !subsubheading, !subsubsubheading


F.8.4  !hline
-------------

 Type & position: command, main part

 Syntax:          !hline

 Description:     This  command  displays  a  horizontal  line  inside
                  normal  text  or inside a table. Not all destination
                  formats support horizontal lines.

 See:             Tables


F.8.5  !htag
------------

 Type & position: command, preamble & main part

 Syntax:          !htag <text>

 Description:     "<text>" will only be printed if  you  convert  into
                  Helptag. "<text>" will be not converted!

 See:             !=htag, !ifdest, raw environment


F.8.6  !htag_img_suffix
-----------------------

 Type & position: switch, preamble & main part

 Syntax:          !htag_img_suffix <suffix>

 Description:     UDO uses the suffix "tiff" when converting the image
                  commands for HP HelpTag SGML by default. If you want
                  to  use  different  image types you can redefine the
                  image suffix with this command.  The  lower  example
                  shows  how  to change the image suffix to "xwd". You
                  can use !htag_img_suffix as often as you want so you
                  can  redefine  the  image  suffix right before every
                  image.

 Example:         !htag_img_suffix xwd

 See:             !image, (!img [ ]), Images


F.8.7  !html
------------

 Type & position: command, preamble & main part

 Syntax:          !html <text>

 Description:     "<text>" will only be printed if  you  convert  into
                  HTML. "<text>" will be not converted!

 Example:         !html <hr>

 See:             !=html, !ifdest, raw environment


F.8.8  !html_backpage
---------------------

 Type & position: command, preamble

 Syntax:          !html_backpage <URL>

 Description:     Using this command you can tell UDO where to jump to
                  when the reader clicks on the "Go Up" button on  the
                  title page.

 Example:         !html_backpage ../index.html

 See:             !no_headlines, !no_bottomlines


F.8.9  !html_img_suffix
-----------------------

 Type & position: switch, preamble & main part

 Syntax:          !html_img_suffix <suffix>

 Description:     UDO  uses the suffix "gif" when converting the image
                  commands for HTML by default. If  you  want  to  use
                  different  image  types  you  can redefine the image
                  suffix with this command. The  lower  example  shows
                  how  to  change  the image suffix to "jpeg". You can
                  use !html_img_suffix as often as you want so you can
                  redefine the image suffix right before every image.

 Example:         !html_img_suffix jpeg

 See:             !image, (!img [ ]), Images


F.8.10  !html_keywords
----------------------

 Type & position: command, main part

 Syntax:          !html_keywords <text>

 Description:     <text should  be a comma separated list of keywords.
                  This list will be printed by UDO inside  the  header
                  of the HTML file that contains the chapter where you
                  used this comand. Some Internat machines are  taking
                  these information for referencing the HTML pages.

 Example:         !html_keywords   Dirk   Hagedorn,   UDO6,  Software,
                  Converter


F.8.11  !html_merge_nodes
-------------------------

 Type & position: switch, preamble

 Syntax:          !html_merge_nodes

 Description:     If you use this switch inside the preamble  of  your
                  UDO  source  file  UDO  will save only one HTML file
                  that will contain the whole text.

 See:             !html_merge_subnodes,       !html_merge_subsubnodes,
                  !html_merge_subsubsubnodes


F.8.12  !html_merge_subnodes
----------------------------

 Type & position: switch, preamble

 Syntax:          !html_merge_subnodes

 Description:     If  you  use this switch inside the preamble of your
                  source file UDO will save  an  HTML  file  for  each
                  chapter.  These  files  will  contain  the sections,
                  subsections and paragraphs, too.

 See:             !html_merge_nodes,          !html_merge_subsubnodes,
                  !html_merge_subsubsubnodes


F.8.13  !html_merge_subsubnodes
-------------------------------

 Type & position: switch, preamble

 Syntax:          !html_merge_subsubnodes

 Description:     If  you  use this switch inside the preamble of your
                  source file UDO will save  an  HTML  file  for  each
                  section.  These  files  will contain the subsections
                  and paragraphs, too.

 See:             !html_merge_nodes,             !html_merge_subnodes,
                  !html_merge_subsubsubnodes


F.8.14  !html_merge_subsubsubnodes
----------------------------------

 Type & position: switch, preamble

 Syntax:          !html_merge_subsubsubnodes

 Description:     If  you  use this switch inside the preamble of your
                  source file UDO will save  an  HTML  file  for  each
                  subsection. These files will contain the paragraphs,
                  too.

 See:             !html_merge_nodes,             !html_merge_subnodes,
                  !html_merge_subsubnodes


F.8.15  !html_name
------------------

 Type & position: command, main part

 Syntax:          !html_name <file>

 Description:     If  you  use this command inside a chapter, section,
                  subsection or paragraph, "<file>"  is  used  as  the
                  name  of  the  HTML  file  instead  of  CCSSUUPP (CC
                  chapter, SS section, UU subsection, PP paragraph).

 Example:         !html_name software


F.8.16  !html_nodesize
----------------------

 Type & position: switch, preamble

 Syntax:          !html_nodesize <value>

 Description:     You can set the font size of the HTML headlines with
                  this  switch.  By  default  UDO will use value of 1.
                  That means, that  UDO  will  print  <H1>...</H1> for
                  chapters, <H2>...</H2> for sections etc. The example
                  shows  how  to  tell  UDO  that  it   should   print
                  <H2>...</H2> for chapters etc.

 Example:         !html_nodesize 2

 See:             !node, !subnode, !subsubnode, !subsubsubnode


F.8.17  !html_use_xlist
-----------------------

 Type & position: switch, preamble

 Syntax:          !html_use_xlist

 Description:     Because  the  output of an xlist environment is very
                  complicated  these  environments  are  handled  like
                  description environments by default. Use this switch
                  inside the preamble to  display  xlist  environments
                  like  in  ASCII and with the use of the preformatted
                  tag.

 See:             Lists, Descriptions


F.8.18  !hyphen
---------------

 Type & position: command, preamble

 Syntax:          !hyphen <word>

 Description:     You can  set  syllabification  marks  (!-)  with  this
                  command  for  a word for the whole text. The example
                  shows how to tell UDO where it's allowed to split up
                  the word "syllabification".

 Example:         !hyphen syl!-labi!-fi!-ca!-tion

 See:             Syllabification, !sloppy, !fussy, !-


F.9  I...
=========


F.9.1  !=info
-------------

 Type & position: command, preamble & main part

 Syntax:          !=info <text>

 Description:     "<text>"  will  only be printed if you don't convert
                  into Texinfo "<text>" will be not converted!

 See:             !info, !ifdest, raw environment


F.9.2  !if
----------

 Type & position: command, preamble & main part

 Syntax:          !if [<text>]

 Description:     This command combines the commands !ifdest, !iflang,
                  !ifset and  !ifos.  The example shows how to test if
                  the source file is converted into  an  English  HTML
                  file.

 Example:         !if [english,html]

 See:             !iflang, !ifdest, !ifset, !ifos, Query commands


F.9.3  !ifdest
--------------

 Type & position: command, preamble & main part

 Syntax:          !ifdest [<abbreviations>]

 Description:     This  command  tests the current destination format.
                  If  one  of  the   "<abbreviations>"   matches   the
                  abbreviation  of  the  destination  format  UDO will
                  convert  all  lines  between  !ifdest and   !else or
                  !endif.  If  not  UDO  will  only  convert the lines
                  between  !else and  !endif if  !else is  used.   The
                  example  shows  how  to  test if UDO converts to ST-
                  Guide or Windows Help.

 Example:         !ifdest [stg,win]

 See:             !else, !endif, !ifndest, !if, Query commands


F.9.4  !iflang
--------------

 Type & position: command, preamble & main part

 Syntax:          !iflang [<languages>]

 Description:     This command test the language UDO uses for the des-
                  tination  file.  If  "<language>" matches one of the
                  abbreviations for the destination languages UDO will
                  convert   all  lines  between  !iflang and  !else or
                  !endif. If not  UDO  will  only  convert  the  lines
                  between   !else and  !endif if  !else is  used.  The
                  example  shows  how  to  test  if  UDO  converts  to
                  English.

 Example:         !iflang [english]

 See:             !ifnlang, !ifdest, !language, Query commands


F.9.5  !ifndest
---------------

 Type & position: command, preamble & main part

 Syntax:          !ifndest [<abbreviation>]

 Description:     This  command  tests the current destination format.
                  If   none of   the   "<abbreviations>"   match   the
                  abbreviation  of  the  destination  format  UDO will
                  convert  all  lines  between  !ifdest and   !else or
                  !endif.  If  one  matches them UDO will only convert
                  the lines between !else and !endif if !else is used.
                  The example shows how to test if UDO doesn't convert
                  to HTML.

 Example:         !ifndest [html]

 See:             !else, !endif, !ifdest, Query commands


F.9.6  !ifnlang
---------------

 Type & position: command, preamble & main part

 Syntax:          !ifnlang [<languages>]

 Description:     This command tests the current destination language.
                  If  none of the "<languages>" match the abbreviation
                  of the destination language  UDO  will  convert  all
                  lines  between  !ifdest and  !else or !endif. If one
                  matches them UDO will only convert the lines between
                  !else and !endif if !else is used. The example shows
                  how to test if UDO doesn't convert to French.

 Example:         !ifnlang [french]

 See:             !ifnlang, !ifdest, !language, Query commands


F.9.7  !ifnos
-------------

 Type & position: command, preamble & main part

 Syntax:          !ifnos [<systems>]

 Description:     This command tests the current operating system  UDO
                  is  running  on. If "<systems>" doesn't match any of
                  the abbreviations of the operating systems UDO  will
                  convert  all  lines that follow !else if it is used.
                  If !else isn't used UDO will ignore all lines  until
                  an !endif. The example shows how you can test if UDO
                  !doesn't run on an Apple Macintosh.

 Example:         !ifnos [macos]

 See:             !ifos


F.9.8  !ifnset
--------------

 Type & position: command, preamble & main part

 Syntax:          !ifnset [<text>]

 Description:     With this command you can test if a  symbol  !wasn't
                  set with the command line option -D or with !set. If
                  <text> wasn't set UDO will convert all lines bewteen
                  !ifnset and  !else or  !endif. If <text> was set UDO
                  will convert all lines between  !else and  !endif if
                  !else was used. The example shows how to test if the
                  symbol "british" isn't set.

 Example:         !ifnset [british]

 See:             !ifset


F.9.9  !ifos
------------

 Type & position: command, preamble & main part

 Syntax:          !ifos [<text>]

 Description:     This command tests the current operating system  UDO
                  is  running  on. If "<systems>" match one of the ab-
                  breviations  of  the  operating  systems  UDO   will
                  convert  all  lines  that are used between !ifos and
                  !endif or !else. If "<systems>" doesn't match any of
                  the  abbreviations of the operating systems UDO will
                  ignore all lines before !endif or !else. The example
                  shows how you can test if UDO runs with Linux.

 Example:         !ifos [linux]

 See:             !ifnos


F.9.10  !ifset
--------------

 Type & position: command, preamble & main part

 Syntax:          !ifset [<text>]

 Description:     With  this  command you can test if a symbol was set
                  with the command line option  -D or  with  !set.  If
                  <text> was  set  UDO  will convert all lines bewteen
                  !ifset and !else or !endif. If <text> wasn't set UDO
                  will  convert  all lines between !else and !endif if
                  !else was used. The example shows how to test if the
                  symbol "british" was set.

 Example:         !ifset [british]

 See:             !ifnset


F.9.11  !ignore_bottomline
--------------------------

 Type & position: switch, preamble

 Syntax:          !ignore_bottomline

 Description:     If  this  switch  is used inside a chapter UDO won't
                  print a headline.  In  contrast  to  !no_bottomlines
                  this  switch  will only suppress the headline inside
                  the chapter where !ignore_bottomline is used.

 See:             !no_bottomlines


F.9.12  !ignore_headline
------------------------

 Type & position: switch, preamble

 Syntax:          !ignore_headline

 Description:     If this switch is used inside a  chapter  UDO  won't
                  print  a headline. In contrast to !no_headlines this
                  switch will only suppress the  headline  inside  the
                  chapter where !ignore_headline is used.

 See:             !no_headlines


F.9.13  !ignore_index
---------------------

 Type & position: switch, main part

 Syntax:          !ignore_index

 Description:     If  this  switch  is used inside a chapter UDO won't
                  add its title  to  the  index  even  if  the  switch
                  !use_nodes_inside_index is  used inside the preamble
                  of the source file.

 See:             !use_nodes_inside_index, !no_index, Indices


F.9.14  !ignore_links
---------------------

 Type & position: switch, main part

 Syntax:          !ignore_links

 Description:     If this switch is part of a chapter UDO won't insert
                  links  to  this chapter automatically. You are still
                  able to insert links with !link ...) on your own.

 See:             Links, (!link ...)


F.9.15  !ignore_subsubsubtoc
----------------------------

 Type & position: switch, main part

 Syntax:          !ignore_subsubsubtoc

 Description:     If this switch is used inside a subsection UDO won't
                  print a "subsubsubtoc" which contains all paragraphs
                  of  this  subsection   even   if   you   have   used
                  !use_auto_subsubsubtocs inside the preamble.

 See:             !use_auto_subsubsubtocs, !subsubsubtoc


F.9.16  !ignore_subsubtoc
-------------------------

 Type & position: switch, main part

 Syntax:          !ignore_subsubtoc

 Description:     If  this  switch  is used inside a section UDO won't
                  print a "subsubtoc" which contains  all  subsections
                  and paragraphs of this section even if you have used
                  !use_auto_subsubtocs inside the preamble.

 See:             !use_auto_subsubtocs, !subsubtoc


F.9.17  !ignore_subtoc
----------------------

 Type & position: switch, main part

 Syntax:          !ignore_subtoc

 Description:     If this switch is used inside a  chapter  UDO  won't
                  print   a  "subtoc"  which  contains  all  sections,
                  subsections and paragraphs of this chapter  even  if
                  you have used !use_auto_subtocs inside the preamble.

 See:             !use_auto_subtocs, !subtoc


F.9.18  !image
--------------

 Type & position: command, main part

 Syntax:          !image <file> <caption>

 Description:     A  command  to  include an image is generated in the
                  destination  file,  if  it  supports   images.   You
                  shouldn't  pass  the  suffix  of  the  wanted  image
                  because UDO itself adds the right one.  It  will  be
                  .img for  the  ST-Guide, CSTeX and Lindner-TeX, .gif
                  for  HTML,  .msp or  .pcx for  emTeX  and   .bmp for
                  Windows  Help.  If  `<caption>'  is  used it will be
                  printed as the title of this

 Example:         !image tiger

 See:             !no_images, (!image ...), Images, !html_img_suffix


F.9.19  !image*
---------------

 Type & position: command, main part

 Syntax:          !image* <file> <caption>

 Description:     There's one difference between  !image* and  !image.
                  If  you  use  this  command there will be printed no
                  table number.

 Example:         !image* tiger This is a tiger

 See:             !image


F.9.20  !image_counter
----------------------

 Type & position: switch, preamble

 Syntax:          !image_counter [<value>]

 Description:     With this switch you can set the image  counter.  If
                  you  use  the lower example the caption of the first
                  image will look like this: "Figure 5: ...".

 Example:         !image_counter 5

 See:             Images


F.9.21  !include
----------------

 Type & position: command, preamble & main part

 Syntax:          !include <file>

 Description:     Opens  the  file  named  "file"  and  converts   its
                  contents.

 Example:         !include macros.ui

 See:             !vinclude, !rinclude, Split documents


F.9.22  !index
--------------

 Type & position: command, main part

 Syntax:          !index <text>

 Description:     <text> will  pe  printed  as \index {...} for LaTeX,
                  K{\footnote K ...} for WinHelp, {\xe\v ...} for  RTF
                  and  @index  ... for ST-Guide. So, <text> appears in
                  the index of LaTeX and ST-Guide. WinHelp  allows  to
                  search  this  word. You can use this command as many
                  times as you like.

 Example:         !index entry !! index

 See:             Indices, !no_index


F.9.23  !info
-------------

 Type & position: command, preamble & main part

 Syntax:          !info <text>

 Description:     "<text>" is only  given  out  if  you  convert  into
                  Texinfo. "<text>" will be not converted!

 See:             !=info, !ifdest, raw environment


F.9.24  !item
-------------

 Type & position: command, main part

 Syntax:          !item <text>

 Description:     Starts  a  new item of an itemize or enumerate envi-
                  ronment.

 Example:         !item This is the next item

 See:             !item [ ], Itemizations, Enumerations


F.9.25  !item [ ]
-----------------

 Type & position: command, main part

 Syntax:          !item [<text>]

 Description:     Starts a new item of a description or an xlist envi-
                  ronment.  "<text>"  will  be  displayed in bold text
                  inside a description environment.

 Example:         !item [Title:] Description

 See:             !item, Descriptions, Lists


F.9.26  (!I)...(!i)
-------------------

 Type & position: placeholder, preamble & main part

 Syntax:          (!I)<text>(!i)

 Description:     "<text>" will be displayed in italics if possible.

 Example:         (!I)italic(!i)

 See:             Emphasizing text


F.9.27  (!idx ...)
------------------

 Type & position: placeholder, main part

 Syntax:          (!idx     [<text>]     {[<index1>]}     {[<index2>]}
                  {[<index3>]} )

 Description:     Useful  for  adding  indices right inside the source
                  file.

 Example:         (!idx [word] [index entry])

 See:             Indices, !no_index, !index


F.9.28  (!ilink ...)
--------------------

 Type & position: placeholder, main part

 Syntax:          (!ilink [<file>] [<text>] [<link>])

 Description:     This placeholder is a combination of (!img ...)  and
                  (!link ...)  and is useful to display an image right
                  inside the text. If you click this  image  you  will
                  jump  to  another  part of the document. The example
                  shows how to display an image called disk.[bmp,gif],
                  the   link   destination   is  "Download".  In  HTML
                  "download UDO" will be used as the alternative text.
                  In  all  other  formats  only "download" UDO will be
                  dislayed.

 Example:         (!ilink [disk] [download UDO] [Download]

 See:             (!img~..), (!link ...), Links, Images


F.9.29  (!img ...)
------------------

 Type & position: placeholder, main part

 Syntax:          (!img [<file>] [<text>])

 Description:     Use this placeholder to use an  image  right  inside
                  the  text of HTML or WinHelp. If another destination
                  format will be used only "<text>" will be displayed.
                  When  converting to HTML file.gif will be used, when
                  converting to WinHelp file.bmp  will  be  used.  UDO
                  doesn't check if this file exists.

 Example:         (!img [dh] [my logotype])

 See:             Images, !image


F.10  L...
==========


F.10.1  !=ldoc
--------------

 Type & position: command, preamble & main part

 Syntax:          !=ldoc <text>

 Description:     "<text>"  will  only be printed if you don't convert
                  into Linuxdoc-SGML. "<text>" will be not converted!

 See:             !ldoc, !ifdest, raw environment


F.10.2  !label
--------------

 Type & position: command, main part

 Syntax:          !label <text>

 Description:     Defines  a  label  that  will   be   referenced   in
                  hypertexts or can be accessed by a link command

 Example:         !label Label

 See:             Labels, (!link ...), (!plink ...)


F.10.3  !language
-----------------

 Type & position: command, preamble

 Syntax:          !language [<languages>]

 Description:     With this command you can tell UDO which language it
                  should  use  for  the  date  and  expressions   like
                  "Table",  "Contents"  or  "Appendix".  UDO  will use
                  German expressions by default. The example shows how
                  to change the language to English.

 Example:         !language english

 See:             !iflang, !ifnlang, (!today)


F.10.4  !ldoc
-------------

 Type & position: command, preamble & main part

 Syntax:          !ldoc <text>

 Description:     "<text>"  is  only  given  out  if  you convert into
                  Linuxdoc-SGML. "<text>" will be not converted!

 See:             !=ldoc, !ifdest, raw environment


F.10.5  !listoffigures
----------------------

 Type & position: command, main part

 Syntax:          !listoffigures

 Description:     This command prints a list of  figures.  You  should
                  use  it  directly after !tableofcontents if you want
                  to use it. At the moment this command will  only  be
                  converted for LaTeX.

 See:             !image, !tableofcontents, !listoftables


F.10.6  !listoftables
---------------------

 Type & position: command, main part

 Syntax:          !listoftables

 Description:     This command prints a list of tables. You should use
                  it directly after !tableofcontents or !listoffigures
                  if  you  want  to use it. At the moment this command
                  will only be converted for LaTeX.

 See:             Tabellen, !tableofcontents, !listoffigures


F.10.7  (!LaTeX)
----------------

 Type & position: placeholder, preamble & main part

 Syntax:          (!LaTeX)

 Description:     This placeholder will be replaced  by  \LaTeX{} when
                  converting to LaTeX. Otherwise it will be replace by
                  "LaTeX".

 See:             (!TeX), (!LaTeXe)


F.10.8  (!LaTeXe)
-----------------

 Type & position: placeholder, preamble & main part

 Syntax:          (!LaTeXe)

 Description:     This placeholder will be replaced by  \LaTeXe{} when
                  converting to LaTeX. Otherwise it will be replace by
                  "LaTeX2e".

 See:             (!TeX), (!LaTeX)


F.10.9  (!laugh)
----------------

 Type & position: placeholder, preamble & main part

 Syntax:          (!laugh)

 Description:     (!laugh) will be replaced  by  a  laughing  emoticon
                  displayed in typewriter.

 Example:         (!laugh) becomes :-)

 See:             (!grin)


F.10.10  (!link~..)
-------------------

 Type & position: placeholder, main part

 Syntax:          (!link [<text>] [<link>])

 Description:     With  this placeholder you can define links to other
                  parts of  the  document.  See  section  "Links"  for
                  further information.

 Example:         (!link [me] [Contact addresses])

 See:             (!xlink ...), (!plink ...), Links


F.11  M...
==========


F.11.1  !=man
-------------

 Type & position: command, preamble

 Syntax:          !=man <text>

 Description:     "<text>"  will  only be printed if you don't convert
                  into a manualpage. "<text>" will be not converted!

 See:             !man, !ifdest, raw environment


F.11.2  !macro
--------------

 Type & position: command, preamble

 Syntax:          !macro <word> <text>

 Description:     Defines a macro. Later on every "(!<word>)" will  be
                  replaced  by  "<text>". When using the lower exmaple
                  every "(!DH)" will be replaced by "Dirk Hagedorn".

 Example:         !macro DH Dirk Hagedorn

 See:             Macros


F.11.3  !maketitle
------------------

 Type & position: command, main part

 Syntax:          !maketitle

 Description:     Outputs a titlepage build with the  information  set
                  by  the  lower  commands.  !maketitle should be used
                  directly    after     !begin_document and     before
                  !tableofcontents.

 See:             Title page


F.11.4  !man
------------

 Type & position: command, preamble & main part

 Syntax:          !man <text>

 Description:     "<text>"   is   printed   if   you  convert  into  a
                  manualpage. "<text>" will be not converted!

 See:             !=man, raw environment


F.11.5  !man_lpp
----------------

 Type & position: command, preamble

 Syntax:          !man_lpp <value>

 Description:     Sets the  "lines  per  page"  of  a  manualpage.  If
                  <value>  is  bigger  than  0 UDO generates footlines
                  with  pagenumbers.  When  UDO  starts  !man_lpp   is
                  undefined and UDO won't generate these footlines.

 Example:         !man_lpp 60

 See:             !use_formfeed


F.11.6  !man_type
-----------------

 Type & position: command, preamble

 Syntax:          !man_type <text>

 Description:     When  converting into a manualpage UDO uses "<text>"
                  inside the headline with brackets. The  exmaple  and
                  "!program udo" would look like "udo(1)". UDO doesn't
                  use "<text>" as a file suffix.

 Example:         !man_type 1


F.11.7  !medskip
----------------

 Type & position: command, main part

 Syntax:          !medskip

 Description:     This command will be simplay replaced by  `\medskip'
                  when  converted  to  LaTeX. Otherwise two additional
                  empty lines will be generated.

 See:             !smallskip, !bigskip


F.12  N...
==========


F.12.1  !newpage
----------------

 Type & position: command, main part

 Syntax:          !newpage

 Description:     Generates a page break  if  the  destination  format
                  supports it.

 See:             !use_formfeed


F.12.2  !no_bottomlines
-----------------------

 Type & position: switch, preamble

 Syntax:          !no_bottomlines [<abbreviations>]

 Description:     Tells  UDO  not  to  generate  bottomlines.  In  the
                  example this is done for the Pure C Help format.

 Example:         !no_bottomlines [pch]

 See:             !no_headlines, !ignore_bottomline


F.12.3  !no_effects
-------------------

 Type & position: switch, preamble

 Syntax:          !no_effects [<abbreviations>]

 Description:     Switches off  the  usage  of  text  emphasises.  The
                  exmaple shows how to switch it of when converting to
                  ASCII.

 Example:         !no_effects [asc]


F.12.4  !no_headlines
---------------------

 Type & position: switch, preamble

 Syntax:          !no_headlines [<abbreviations>]

 Description:     Switches off the usage  of  headlines.  The  example
                  show  how  to  switch  it  off  when  converting  to
                  WinHelp.

 Example:         !no_headlines [win]

 See:             !no_bottomlines, !ignore_headline


F.12.5  !no_images
------------------

 Type & position: switch, preamble

 Syntax:          !no_images [<abbreviations>]

 Description:     Switches off  the  output  of  commands  to  display
                  images.  The  example show how to switch it off when
                  converting to HTML.

 Example:         !no_images [html]

 See:             !image, Images


F.12.6  !no_index
-----------------

 Type & position: switch, preamble

 Syntax:          !no_index [<abbreviations>]

 Description:     If this switch  is  used  inside  the  preamble  UDO
                  suppresses  index commands for the given destination
                  formats. Furthermore neither UDO nor the destination
                  format will print an index. The example shows how to
                  suppress index commands for RTF.

 Example:         !no_index [rtf]

 See:             !index, (!idx ...)


F.12.7  !no_numbers
-------------------

 Type & position: switch, preamble

 Syntax:          !no_numbers [<abbreviations>]

 Description:     This command  switches  off  the  usage  of  chapter
                  numbers.  In  tables  of  contens  only  the chapter
                  titles will be displayed. The example shows  how  to
                  suppress them in Windows Help and HTML.

 Example:         !no_numbers [win,html]

 See:             !tableofcontents, !toc, !subtoc, !subsubtoc


F.12.8  !no_preamble
--------------------

 Type & position: switch, preamble

 Syntax:          !no_preamble [<abbreviations>]

 Description:     If  this  switch  is used inside the preamble of the
                  source file UDO won't print a specific preamble  for
                  the  destination  format.  The  example shows how to
                  suppress the preamble for LaTeX. You shall have some
                  knowledge  about  the destination format if you want
                  to write your own preamble.

 Example:         !no_preamble [tex]


F.12.9  !no_quotes
------------------

 Type & position: switch, preamble

 Syntax:          !no_quotes [<abbreviations>]

 Description:     Says UDO not to replace  double  quotes  and  double
                  apostrophes by real quotes and apostrophes.

 Example:         !no_quotes [asc,man]

 See:             Double quotes, Double apostrophes


F.12.10  !no_toc_subnodes
-------------------------

 Type & position: switch, preamble

 Syntax:          !no_toc_subnodes

 Description:     If  you use this switch inside the preamble UDO will
                  print only the chapter titles inside  the  table  of
                  contents.    !no_toc_subnodes is    the    same   as
                  !use_short_toc.

 Example:         !no_toc_subnodes [win]

 See:             !tableofcontents


F.12.11  !no_toc_subsubnodes
----------------------------

 Type & position: switch, preamble

 Syntax:          !no_toc_subsubnodes

 Description:     If you use this switch inside the preamble UDO  will
                  print  only  the  chapter  titles and section titles
                  inside the table of contents.

 Example:         !no_toc_subsubnodes [win,stg,html]

 See:             !tableofcontents


F.12.12  !no_toc_subsubsubnodes
-------------------------------

 Type & position: switch, preamble

 Syntax:          !no_toc_subsubsubnodes

 Description:     If you use this switch inside the preamble UDO  will
                  print  only  the  chapter titles, section titles and
                  subsection titles inside the table of contents.

 Example:         !no_toc_subsubsubnodes [win,stg,html]

 See:             !tableofcontents


F.12.13  !no_umlaute
--------------------

 Type & position: switch, preamble

 Syntax:          !no_umlaute [<abbreviations>]

 Description:     Switches  off  the  usage  of  German  umlauts.  The
                  example show how to switch it off when converting to
                  a manualpage. Umlauts are than replaced by  ae,  oe,
                  ue, ss, Ae, Oe and Ue.

 Example:         !no_umlaute [man]

 See:             Special characters


F.12.14  !no_verbatim_umlaute
-----------------------------

 Type & position: switch, preamble

 Syntax:          !no_verbatim_umlaute [<abbreviations>]

 Description:     Switches  off  the  usage of German umlauts inside a
                  verbatim environment. The example show how to switch
                  it  off  when  converting to LaTeX. Umlauts are than
                  replaced by ae, oe, ue, ss, Ae, Oe and Ue.

 Example:         !no_verbatim_umlaute [tex]

 See:             !begin_verbatim, !end_verbatim, Preformatted text


F.12.15  !no_xlinks
-------------------

 Type & position: switch, preamble

 Syntax:          !no_xlinks [<abbreviations>]

 Description:     This command switches  off  the  usage  of  external
                  links.  This  is  useful  if  you used external HTML
                  links in a source file that you want to  convert  to
                  another  format  that  supports  external links. The
                  example shows how to suppress the usage of  external
                  links when converting to ST-Guide.

 Example:         !no_xlink [stg]

 See:             (!xlink ...)


F.12.16  !node
--------------

 Type & position: command, main part

 Syntax:          !node <text>

 Description:     Starts a new chapter named "<text>".

 Example:         !node Command reference

 See:             !pnode,   !subnode,   !subsubnode,   !subsubsubnode,
                  Structuring


F.12.17  !node*
---------------

 Type & position: command, main part

 Syntax:          !node* <text>

 Description:     This command  does  the  same  as  !node,  but  here
                  "<text>" will not appear in a table of contents.

 Example:         !node* Chapter title

 See:             !node, !pnode*, Structuring


F.12.18  !nop
-------------

 Type & position: command, preamble & main part

 Syntax:          !nop

 Description:     This  command  ("no  operation") does nothing and is
                  used for debugging purposes.


F.12.19  (!N)...(!n)
--------------------

 Type & position: placeholder, preamble & main part

 Syntax:          (!N)<text>(!n)

 Description:     "<text>" will be  displayed  as  a  footnote  or  in
                  brakes.  Right before (!N) shouldn't be a space, tab
                  or linefeed!

 Example:         the text(!N)the footnote(!n)

 See:             Footnotes


F.12.20  (!nl)
--------------

 Type & position: placeholder, main part

 Syntax:          (!nl)

 Description:     With (!nl) you can force a line break. You  must add
                  a space before (!nl) if you use it!

 Example:         breaking (!nl) lines


F.13  O...
==========


F.14  P...
==========


F.14.1  !=pch
-------------

 Type & position: command, preamble & main part

 Syntax:          !=pch <text>

 Description:     "<text>"  will  only be printed if you don't convert
                  into Pure C Help. "<text>" will be not converted!

 See:             !pch, !ifdest, raw environment


F.14.2  !parwidth
-----------------

 Type & position: switch, preamble

 Syntax:          !parwidth <value>

 Description:     With this switch you can tell  UDO  which  width  it
                  should  use  for  the lines it saves. UDO uses 70 by
                  default. You  can  change  this  value  by  using  a
                  <value> between  20  and  200.  When  converting  to
                  Windows Help, Apple QuickView or HTML you can use  a
                  value  that's greater than 200 if you use the switch
                  !use_output_buffer.

 Example:         !parwidth 98

 See:             !use_output_buffer


F.14.3  !pch
------------

 Type & position: command, preamble & main part

 Syntax:          !pch <text>

 Description:     "<text>" is only given out if you convert into  Pure
                  C Help. "<text>" will be not converted!

 See:             !=pch, raw environment


F.14.4  !pnode
--------------

 Type & position: command, main part

 Syntax:          !pnode <text>

 Description:     The same as !node but the contents will be displayed
                  as a popup inside ST-Guide and WinHelp.

 Example:         !popup Popup title

 See:             !psubnode, !psubsubnode, !psubsubsubnode


F.14.5  !pnode*
---------------

 Type & position: command, main part

 Syntax:          !pnode* <text>

 Description:     This command does  the  same  as  !pnode,  but  here
                  "<text>" will not appear in a table of contents.

 Example:         !pnode Popup title

 See:             !pnode, !node*, Structuring


F.14.6  !program
----------------

 Type & position: command, preamble

 Syntax:          !program <text>

 Description:     "<text>"  will  be  displayed on the titlepage below
                  the title.

 Example:         !program UDO

 See:             !maketitle, !programimage, Title page


F.14.7  !programimage
---------------------

 Type & position: command, preamble

 Syntax:          !programimage <file>

 Description:     "<file>" will be displayed instead of  the  name  of
                  the  program  on  the  titlepage  if the destination
                  format supports images.

 Example:         !programimage udo

 See:             !maketitle, !program, Title page


F.14.8  !psubnode
-----------------

 Type & position: command, main part

 Syntax:          !psubnode <text>

 Description:     The  same  as  !subnode but  the  contents  will  be
                  displayed as a popup inside ST-Guide and WinHelp.

 Example:         !psubnode A popup section

 See:             !pnode, !psubsubnode, !psubsubsubnode


F.14.9  !psubnode*
------------------

 Type & position: command, main part

 Syntax:          !psubnode* <text>

 Description:     This  command  does  the same as !psubnode, but here
                  "<text>" will not appear in a table of contents.

 Example:         !psubnode* A hidden popup section

 See:             !psubnode, !subnode*, Structuring


F.14.10  !psubsubnode
---------------------

 Type & position: command, main part

 Syntax:          !psubsubnode <text>

 Description:     The same as !subsubnode but  the  contents  will  be
                  displayed as a popup inside ST-Guide and WinHelp.

 Example:         !psubsubnode A popup subsection

 See:             !pnode, !psubnode, !psubsubsubnode


F.14.11  !psubsubnode*
----------------------

 Type & position: command, main part

 Syntax:          !psubsubnode* <text>

 Description:     This command does the same as !psubsubnode, but here
                  "<text>" will not appear in a table of contents.

 Example:         !psubsubnode* A hidden popup subsection

 See:             !psubsubnode, !subsubnode*, Structuring


F.14.12  !psubsubsubnode
------------------------

 Type & position: command, main part

 Syntax:          !psubsubsubnode <text>

 Description:     The same as !subsubsubnode but the contents will  be
                  displayed as a popup inside ST-Guide and WinHelp.

 Example:         !psubsubsubnode A popup paragraph

 See:             !pnode, !psubnode, !psubsubnode


F.14.13  !psubsubsubnode*
-------------------------

 Type & position: command, main part

 Syntax:          !psubsubsubnode* <text>

 Description:     This  command  does the same as !psubsubsubnode, but
                  here "<text>"  will  not  appear  in  the  table  of
                  contents.

 Example:         !psubsubsubnode* A hidden popup paragraph

 See:             !pnode, !psubnode, !psubsubnode, !psubsubsubnode


F.14.14  (!plink~..)
--------------------

 Type & position: placeholder, main part

 Syntax:          (!plink [<text>] [<link>])

 Description:     Only  useful  when  converted  to  LaTeX  where it's
                  converted into a page reference.

 Example:         (!plink [word] [label])

 See:             (!link ...), (!xlink ...), Links


F.15  R...
==========


F.15.1  !=rtf
-------------

 Type & position: command, preamble & main part

 Syntax:          !=rtf <text>

 Description:     "<text>" will only be printed if  you  don't convert
                  into RTF. "<text>" will be not converted!

 See:             !rtf, !ifdest, raw environment


F.15.2  !rinclude
-----------------

 Type & position: command, main part

 Syntax:          !rinclude <file>

 Description:     "<file>"  will  be included and output unforformated
                  inside a raw environment. Useful  for  large  tables
                  for LaTeX or HTML.

 Example:         !rinclude table.tex

 See:             !include,  !vinclude,  Split documents, raw environ-
                  ment


F.15.3  !rtf
------------

 Type & position: command, preamble & main part

 Syntax:          !rtf <text>

 Description:     "<text>" is only given out if you convert into  RTF.
                  "<text>" will be not converted!

 See:             !=rtf, raw environment


F.15.4  !rtf_charwidth
----------------------

 Type & position: switch, preamble & main part

 Syntax:          !rtf_charwidth <value>

 Description:     UDO  uses a constant value for calulating the indent
                  of lists and the widths of table cells.  This  value
                  works   even   fine  with  bold  monospaced  capital
                  letters, but if you use normal text the  indents  or
                  table  cells  my  be  too width. You can adjust this
                  value by  using  !rtf_charwidth.  UDO  uses  150  by
                  default.

 Example:         !rtf_charwidth 100

 See:             Tables, Lists


F.15.5  !rtf_monofont
---------------------

 Type & position: command, preamble

 Syntax:          !rtf_monofont <fontname>

 Description:     With  this command you can set the font that will be
                  used to display preformated  text.  The  default  is
                  "Monospace 821".

 Example:         !rtf_monofont Courier New

 See:             !rtf_propfont


F.15.6  !rtf_no_tables
----------------------

 Type & position: switch, preamble

 Syntax:          !rtf_no_tables

 Description:     If  you  use  this  command  inside the preamble UDO
                  prints tables without using special RTF commands. It
                  will  print  the  table ASCII like with a monospaced
                  font.

 See:             Tables


F.15.7  !rtf_propfont
---------------------

 Type & position: command, preamble

 Syntax:          !rtf_propfont <fontname>

 Description:     With this command you can set the font that will  be
                  used  to  display  text and headings. The default is
                  "Dutch 801 Roman".

 Example:         !rtf_propfont Times New Roman

 See:             !rtf_monofont


F.16  S...
==========


F.16.1  !=stg
-------------

 Type & position: command, preamble & main part

 Syntax:          !=stg <text>

 Description:     "<text>" will only be printed if  you  don't convert
                  into ST-Guide. "<text>" will be not converted!

 See:             !stg, !ifdest, raw environment


F.16.2  !set
------------

 Type & position: command, preamble & main part

 Syntax:          !set <text>

 Description:     With  this  command  you can set symbols inside your
                  source file that you can check with !ifset and  !if.
                  Symbols  may  alos be set by the command line option
                  -D. With the !unset command you can delete  symbols.
                  You can use !set wherever you want.

 Example:         !set UseColourGraphics

 See:             !unset, !ifset, !ifnset


F.16.3  !short
--------------

 Type & position: switch, main part

 Syntax:          !short

 Description:     If  you  use  this switch together with environments
                  this specific environment will  be  printed  without
                  additional  vertical space. The example shows how to
                  print a "compressed" itemize environment.

 Example:         !begin_itemize !short

 See:             !begin_itemize,                    !begin_enumerate,
                  !begin_description, !use_short_envs


F.16.4  !sloppy
---------------

 Type & position: switch, main part

 Syntax:          !sloppy

 Description:     Switches off warning messages according short lines.
                  You can use this  command  wherever  you  want.  The
                  warnings can be enabled with !fussy. When converting
                  to LaTeX UDO doesn't convert !sloppy into \sloppy!

 See:             !fussy


F.16.5  !smallskip
------------------

 Type & position: command, main part

 Syntax:          !smallskip

 Description:     This   command   will   be   simplay   replaced   by
                  "\smallskip"  when converted to LaTeX. Otherwise one
                  additional empty line will be generated.

 See:             !medskip, !bigskip


F.16.6  !sort_hyphen_file
-------------------------

 Type & position: switch, preamble

 Syntax:          !sort_hyphen_file [<abbreviations>]

 Description:     If this switch is used inside the preamble UDO  will
                  read  the  hyphenation file, delete entries that are
                  used more than once and will save a  sorted  version
                  of  this  hyphenation file. The example shows how to
                  do this for ASCII and ST-Guide.

 Example:         !sort_hyphen_file [asc,stg]

 See:             !hyphen


F.16.7  !stg
------------

 Type & position: command, preamble & main part

 Syntax:          !stg <text>

 Description:     "<text>" is only given out if you convert  into  ST-
                  Guide. "<text>" will be not converted!

 Example:         !stg @subject "Documentation\Utilities

 See:             !=stg, raw environment


F.16.8  !stg_no_database
------------------------

 Type & position: switch, preamble

 Syntax:          !stg_no_database

 Description:     Switches  off  the  output of the ST-Guide @database
                  line.


F.16.9  !street
---------------

 Type & position: command, preamble

 Syntax:          !street <text>

 Description:     "<text>" will be displayed below  the  name  of  the
                  author to show in which street you live.

 Example:         !street Asmecke 1

 See:             !maketitle, Title page


F.16.10  !subheading
--------------------

 Type & position: command, main part

 Syntax:          !subheading <text>

 Description:     This command prints out "<text>" as a headline using
                  the section font and fontsize.

 See:             !heading, !subsubheading


F.16.11  !subnode
-----------------

 Type & position: command, main part

 Syntax:          !subnode <text>

 Description:     Starts a new section named "<text>".

 Example:         !subnode Section title

 See:             !node, !subsubnode, !subsubsubnode, Structuring


F.16.12  !subnode*
------------------

 Type & position: command, main part

 Syntax:          !subnode* <text>

 Description:     This command does the same  as  !subnode,  but  here
                  "<text>" will not appear in a table of contents.

 Example:         !subnode* Section title

 See:             !subnode, !psubnode*, Structuring


F.16.13  !subsubheading
-----------------------

 Type & position: command, main part

 Syntax:          !subsubheading <text>

 Description:     This command prints out "<text>" as a headline using
                  the subsubnode font and fontsize.

 See:             !heading, !subheading


F.16.14  !subsubnode
--------------------

 Type & position: command, main part

 Syntax:          !subsubnode <text>

 Description:     Starts a new subsection named "<text>".

 Example:         !subsubnode Subsection title

 See:             !node, !subnode, Structuring


F.16.15  !subsubnode*
---------------------

 Type & position: command, main part

 Syntax:          !subsubnode* <text>

 Description:     This command does the same as !subsubnode, but  here
                  "<text>" will not appear in a table of contents.

 Example:         !subsubnode* Subsection title

 See:             !subsubnode, !psubsubnode*, Structuring


F.16.16  !subsubsubheading
--------------------------

 Type & position: command, main part

 Syntax:          !subsubsubheading <text>

 Description:     This command prints out "<text>" as a headline using
                  the subsubsubnode font and fontsize.

 See:             !heading, !subheading, !subsubheading


F.16.17  !subsubsubnode
-----------------------

 Type & position: command, main part

 Syntax:          !subsubsubnode <text>

 Description:     Starts a new paragraph  named  "<text>".  Paragraphs
                  are  numbered  with #.#.#.# and are displayed inside
                  the table of contents

 Example:         !subsubsubnode Paragraph title

 See:             !psubsubsubnode, !subnode, !subsubnode, Structuring


F.16.18  !subsubsubnode*
------------------------

 Type & position: command, main part

 Syntax:          !subsubsubnode* <text>

 Description:     This command does the same  as  !subsubsubnode,  but
                  here  "<text>"  will  not  appear  in  the  table of
                  contents.

 Example:         !subsubsubnode* Paragraph title

 See:             !psubsubsubnode, !subnode, !subsubnode, Structuring


F.16.19  !subsubtoc
-------------------

 Type & position: command, main part

 Syntax:          !subsubtoc

 Description:     Lists all subsections of a  section  to  enable  the
                  reader of a hypertext to switch to the subsections.

 Example:         !subsubtoc [html,pch,stg,win]

 See:             !tableofcontents,           !toc,           !subtoc,
                  !use_auto_subsubtocs, Tables of contents


F.16.20  !subtoc
----------------

 Type & position: command, main part

 Syntax:          !subtoc

 Description:     Lists all sections of a chapter to enable the reader
                  of a hypertext to siwtch to the sections.

 Example:         !subtoc [html,pch,stg,win]

 See:             !tableofcontents,          !toc,         !subsubtoc,
                  !use_auto_subtocs, Tables of contents


F.16.21  (!short_today)
-----------------------

 Type & position: placeholder, preamble & main part

 Syntax:          (!short_today)

 Description:     This placeholder will be replaced by the short  form
                  of the current date.

 Example:         (!short_today) becomes 1997/01/12

 See:             (!today), !language


F.17  T...
==========


F.17.1  !=tex
-------------

 Type & position: command, preamble & main part

 Syntax:          !=tex <text>

 Description:     "<text>"  will  only be printed if you don't convert
                  into LaTeX. "<text>" will be not converted!

 See:             !tex, !ifdest, raw environment


F.17.2  !table_caption
----------------------

 Type & position: command, main part

 Syntax:          !table_caption <text>

 Description:     Use this command to set the title of the next table.
                  You have to use this command outside the table envi-
                  ronment. For the first table of your source file UDO
                  will  print  "Table 1: A table" if you use the lower
                  example.

 Example:         !table_caption A table

 See:             Tables, !table_caption*


F.17.3  !table_caption*
-----------------------

 Type & position: command, main part

 Syntax:          !table_caption* <text>

 Description:     The difference between this and  the  !table_caption
                  command is that UDO won't print "Table <no>:" before
                  the table caption.

 Example:         !table_caption* A table

 See:             Tables, !table_caption


F.17.4  !table_counter
----------------------

 Type & position: switch, preamble

 Syntax:          !table_counter [<value>]

 Description:     With this switch you can set the table  counter.  If
                  you  use  the lower example the caption of the first
                  table will look like this: "Table 5: ...".

 Example:         !table_counter 5

 See:             Tables


F.17.5  !tableofcontents
------------------------

 Type & position: command, main part

 Syntax:          !tableofcontents

 Description:     Generates a full table  of  contents  with  specific
                  commands  of  the destination format. I recommend to
                  use this command right after  using  !begin_document
                  or !maketitle.

 See:             Tables of contents, !use_short_toc


F.17.6  !tabwidth
-----------------

 Type & position: command, preamble & main part

 Syntax:          !tabwidth <value>

 Description:     If  lines  that  are  part of a verbatim environment
                  contain TABs (ASCII 9) UDO will replace  them  by  a
                  specific  number of blanks. E.g. if you have written
                  a C source code using a tabwidth of 3 and  you  want
                  to  print  it  with UDO you can use !tabwidth 3. You
                  can reset this value before every verbatim  environ-
                  ment. UDO will use a value of 8 by default.

 Example:         !tabwidth 3

 See:             verbatim environment, !vinclude


F.17.7  !tex
------------

 Type & position: command, preamble & main part

 Syntax:          !tex <text>

 Description:     "<text>"  is  only  given  out  if  you convert into
                  LaTeX. "<text>" will be not converted!

 Example:         !tex \parindent 0pt

 See:             !=tex, raw environment


F.17.8  !tex_2e
---------------

 Type & position: switch, preamble

 Syntax:          !tex_2e

 Description:     UDO will output special LaTeX2e commands if you  use
                  this command e.g. \textbf{...} instead of {\bf ...}


F.17.9  !tex_dpi
----------------

 Type & position: command, preamble & main part

 Syntax:          !tex_dpi <value>

 Description:     Sets  the  resolution  with  which  images should be
                  output via LaTeX.

 Example:         !tex_dpi 100

 See:             !tex_strunk,   !tex_lindner,   !tex_emtex,   !image,
                  Images


F.17.10  !tex_emtex
-------------------

 Type & position: switch, preamble

 Syntax:          !tex_emtex

 Description:     This  switch  says  UDO  to  generate  special emTeX
                  commands  to  display  Microsoft  Paintshop  Bitmaps
                  (*.msp) when using the !image command.

 See:             !tex_strunk, !tex_lindner, !image, Images


F.17.11  !tex_lindner
---------------------

 Type & position: switch, preamble

 Syntax:          !tex_lindner

 Description:     This switch says UDO to generate special Lindner-TeX
                  commands to display GEM images when using the !image
                  command.

 See:             !tex_strunk, !tex_emtex, !image, Images


F.17.12  !tex_strunk
--------------------

 Type & position: switch, preamble

 Syntax:          !tex_strunk

 Description:     This  switch says UDO to generate special Strunk-TeX
                  commands to display GEM images when using the !image
                  command.

 See:             !tex_lindner, !tex_emtex, !image, Images


F.17.13  !tex_verb
------------------

 Type & position: command, preamble & main part

 Syntax:          !tex_verb <char>

 Description:     "<char"  will  be  used  as  the  sign for the LaTeX
                  command \verb. "+" will be used by default.

 Example:         !tex_verb |

 See:             (!V)...(!v)


F.17.14  !title
---------------

 Type & position: command, preamble

 Syntax:          !title <text>

 Description:     "<text>" will be displayed on the  titlepage  before
                  the  contents of !program. It's also used inside the
                  headlines.

 Example:         !title The guide to

 See:             !maketitle, Title page


F.17.15  !toc
-------------

 Type & position: command, main part

 Syntax:          !toc [<abbreviations>]

 Description:     Outputs a table of contents without special page  or
                  hypertext  commands. The example shows how to output
                  a table of contents (as raw text) for the ST-Guide.

 Example:         !toc [stg]

 See:             !tableofcontents,  !subtoc,  !subsubtoc,  Tables  of
                  contents


F.17.16  !toc_offset
--------------------

 Type & position: switch, preamble

 Syntax:          !toc_offset <value>

 Description:     "<value>"  is  added  to  the current chapter number
                  when printing a  chapter  headline  or  a  table  of
                  contents. The example shows how to set the number of
                  the first  chapter  to  10.  You  can  use  negative
                  values,  too.  This switch has no effect to chapters
                  of the appendix.

 Example:         !toc_offset 9


F.17.17  !town
--------------

 Type & position: command, preamble

 Syntax:          !town <text>

 Description:     "<text>" will  be  given  out  inside  the  author's
                  address block on the titlepage.

 Example:         !town D-59846 Sundern

 See:             !maketitle, Title page


F.17.18  (!T)...(!t)
--------------------

 Type & position: placeholder, preamble & main part

 Syntax:          (!T)<text>(!t)

 Description:     "<text>"   will   be   displayed  in  typewriter  if
                  possible.

 Example:         (!T)monospaced(!t)

 See:             Emphasizing text


F.17.19  (!TeX)
---------------

 Type & position: placeholder, preamble & main part

 Syntax:          (!TeX)

 Description:     This placeholder will  be  replaced  by  \TeX{} when
                  converting to LaTeX. Otherwise it will be replace by
                  "TeX".

 Example:         (!TeX) is printed as TeX

 See:             (!LaTeX), (!LaTeXe)


F.17.20  (!today)
-----------------

 Type & position: placeholder, preamble & main part

 Syntax:          (!today)

 Description:     This placeholder will be replaced by the  long  form
                  of the current date.

 Example:         (!today) becomes January 12, 1997

 See:             (!short_today), !language


F.18  U...
==========


F.18.1  !universal_charset
--------------------------

 Type & position: switch, preamble & main part

 Syntax:          !universal_charset [ on | off ]

 Description:     `!universal_charset [on]'  switches  on the usage of
                  the  universal  charset,  `!universal_charset [off]'
                  switches it off. UDO won't use the universal charset
                  by default because it takes some time  to  look  for
                  and convert these special characters.

 Example:         !universal_charset [on]

 See:             Universal charset


F.18.2  !unset
--------------

 Type & position: command, preamble & main part

 Syntax:          !unset <text>

 Description:     With  this  command you can delete a symbol that was
                  set with !set or with the command line option -D.

 See:             !set, !ifset, !ifnset, Symbols


F.18.3  !use_about_udo
----------------------

 Type & position: switch, preamble

 Syntax:          !use_about_udo [<abbreviations>]

 Description:     This command switches on the usage of  a  page  with
                  information  about  UDO. This page doesn't appear in
                  tables of contents. If you want to tell anybody else
                  about  UDO  please  add this switch to your preamble
                  and insert `UDO5' somewhere in your source file. The
                  example  shows  how  to add this information page in
                  Windows Help, ST-Guide and Pure C Help.

 Example:         !use_about_udo [stg,win,pch]


F.18.4  !use_alias_inside_index
-------------------------------

 Type & position: switch, preamble

 Syntax:          !use_alias_inside_index [<abbreviations>]

 Description:     If you use this switch inside the preamble  of  your
                  source file all aliases will be printed in the index
                  of the given destination formats.

 Example:         !use_alias_inside_index [win,stg]

 See:             Indices, !no_index, !index, !alias


F.18.5  !use_ansi_tables
------------------------

 Type & position: switch, preamble

 Syntax:          !use_ansi_tables [<abbreviations>]

 Description:     If you use this switch inside  the  preamble  tables
                  will  be  printed  with  graphic  chars from the DOS
                  characterset.  This  switch  has  no  function  when
                  converting into LaTeX, WinHelp or HTML.

 Example:         !use_ansi_tables [stg]

 See:             !begin_table, Tables


F.18.6  !use_auto_subsubsubtocs
-------------------------------

 Type & position: switch, preamble

 Syntax:          !use_auto_subsubsubtocs [<abbreviations>]

 Description:     Tells   UDO   to   use   the  !subsubsubtoc  command
                  automatically in every subsection. The example shows
                  how to use them inside the hypertext formats.

 Example:         !use_auto_subsubsubtocs [html,pch,stg,win]

 See:             !subsubsubtoc,   !ignore_subsubsubtoc,   Tables   of
                  contents


F.18.7  !use_auto_subsubtocs
----------------------------

 Type & position: switch, preamble

 Syntax:          !use_auto_subsubtocs [<abbreviations>]

 Description:     Tells   UDO   to   use   the   !subsubtoc    command
                  automatically  in  every  section. The example shows
                  how to use them inside the hypertext formats.

 Example:         !use_auto_subsubtocs [html,pch,stg,win]

 See:             !subsubtoc, !ignore_subsubtoc, Tables of contents


F.18.8  !use_auto_subtocs
-------------------------

 Type & position: switch, preamble

 Syntax:          !use_auto_subtocs [<abbreviations>]

 Description:     Tells UDO to use the !subtoc  command  automatically
                  in  every chapter. The example shows how to use them
                  inside the hypertext formats.

 Example:         !use_auto_subtocs [html,pch,stg,win]

 See:             !subtoc, !ignore_subtoc, Tables of contents


F.18.9  !use_chapter_images
---------------------------

 Type & position: switch, preamble

 Syntax:          !use_chapter_images [<abbreviations>]

 Description:     This command switches on the usage of chapter images
                  instead  of  chapter  titles.  Chapters that use the
                  !chapterimage command will use an image instead. The
                  example demonstrates this for Windows Help, HTML and
                  ST-Guide).

 Example:         !use_chapter_images [html,win,stg]

 See:             !chapterimage


F.18.10  !use_formfeed
----------------------

 Type & position: switch, preamble

 Syntax:          !use_formfeed [<abbreviations>]

 Description:     With this switch you can tell UDO to output  a  form
                  feed (ASCII 12) when handling the !newpage-command.

 Example:         !use_formfeed [asc]

 See:             !man_lpp, !newpage


F.18.11  !use_justification
---------------------------

 Type & position: switch, preamble

 Syntax:          !use_justification [<abbreviations>]

 Description:     If  you use this switch inside the preamble UDO will
                  print text with  justification  if  the  destination
                  format   supports   it.   RTF  and  LaTeX  will  use
                  justification by  default,  Windows  Help  and  HTML
                  don't support justification.

 Example:         !use_justification [asc]


F.18.12  !use_label_inside_index
--------------------------------

 Type & position: switch, preamble

 Syntax:          !use_label_inside_index [<abbreviations>]

 Description:     If  you  use this switch inside the preamble of your
                  source file all labels will be printed in the  index
                  of the given destination formats.

 Example:         !use_label_inside_index [win,stg]

 See:             Indices, !no_index, !index, !label


F.18.13  !use_nodes_inside_index
--------------------------------

 Type & position: switch, preamble

 Syntax:          !use_nodes_inside_index [<abbreviations>]

 Description:     If  you  use this switch inside the preamble of your
                  source file all chapter titles will  be  printed  in
                  the index of the given destination formats.

 Example:         !use_nodes_inside_index [win,stg]

 See:             Indices, !no_index, !index, !node


F.18.14  !use_output_buffer
---------------------------

 Type & position: switch, preamble

 Syntax:          !use_output_buffer [<abbreviations>]

 Description:     For  all  destination formats UDO breaks lines after
                  the amount of characters  you  set  with  !parwidth.
                  When  converting  to  Windows  Help  or  HTML it can
                  happen that UDO makes mistakes when inserting links.
                  If  you  use  this  switch UDO will print a complete
                  paragraph into  the  output  buffer,  it  will  then
                  insert the links and in the final step it will break
                  the  lines.  Because  this  method  slows  down  the
                  conversion  of  the  source file UDO doesn't use the
                  output

 Example:         !use_output_buffer [win,html]

 See:             !parwidth


F.18.15  !use_short_envs
------------------------

 Type & position: switch, preamble

 Syntax:          !use_short_envs [<abbreviations>]

 Description:     If you use this swicth inside the preamble  of  your
                  source file UDO will print all environments (without
                  the   verbatim   environment)   without   additional
                  horizontal  space.  The  example  shows  how  to use
                  "compressed" environments by default for  the  ASCII
                  format.

 Example:         !use_short_envs [asc]

 See:             !begin_itemize,                    !begin_enumerate,
                  !begin_description, !begin_xlist


F.18.16  !use_short_toc
-----------------------

 Type & position: switch, preamble

 Syntax:          !use_short_toc [<abbreviations>]

 Description:     Tells UDO to output short tables of contents. In the
                  main  table  of  contents  only  the  names  of  the
                  chapters and in chapters only the names of  sections
                  will be printed.

 Example:         !use_short_toc [all]

 See:             !tableofcontents, Tables of contents


F.18.17  !use_style_book
------------------------

 Type & position: switch, preamble

 Syntax:          !use_style_book [<abbreviations>]

 Description:     When  converting  into  LaTeX  UDO  outputs \chapter
                  instead of \section, \section instead of \subsection
                  and   \subsection instead  of  \subsubsection.  When
                  converting to other formats a booklike  output  will
                  be made, that means that chapters will be printed as
                  "Chapter #".

 Example:         !use_style_book [tex]


F.18.18  (!U)...(!u)
--------------------

 Type & position: placeholder, preamble & main part

 Syntax:          (!U)<text>(!u)

 Description:     "<text>" will be displayed underlined if possible.

 Example:         (!U)underlined(!u)

 See:             Emphasizing text


F.19  V...
==========


F.19.1  !verbatimsize
---------------------

 Type & position: switch, preamble & main part

 Syntax:          !verbatimsize [tiny|small|normal|large|huge]

 Description:     With this switch  you  can  set  the  font  size  of
                  verbatim  environments  if  the  destination  format
                  allows it to use differnet font sizes. You  can  use
                  this  switch  wherever  you  want. The smallest font
                  size is activated with `tiny', the largest one  with
                  `huge'. The default font size is `normal'.

 Example:         !verbatimsize [small]

 See:             verbatim environment


F.19.2  !version
----------------

 Type & position: command, preamble

 Syntax:          !version <text>

 Description:     "<text>"  will be given out right below the contents
                  of !program on the titlepage.

 Example:         !version Release 6

 See:             !maketitle, Title page


F.19.3  !vinclude
-----------------

 Type & position: command, main part

 Syntax:          !vinclude <file>

 Description:     "<file>"  will  be  included  and   displayed   like
                  preformated  text  inside a verbatim environment. If
                  you use this commands inside another environment UDO
                  indents the contents of this file. UDO converts tabs
                  according to !tabwidth.

 Example:         !vinclude hello.c

 See:             !tabwidth, !include, Split documents, verbatim envi-
                  ronment


F.19.4  (!V)...(!v)
-------------------

 Type & position: placeholder, preamble & main part

 Syntax:          (!V)<text>(!v)

 Description:     "<text>" will be displayed preformated if possible.

 Example:         (!V)preformated(!v)

 See:             Emphasizing text, !tex_verb


F.20  W...
==========


F.20.1  !=win
-------------

 Type & position: command, preamble & main part

 Syntax:          !=win <text>

 Description:     "<text>"  will  only be printed if you don't convert
                  into WinHelp. "<text>" will be not converted!

 See:             !win, !ifdest, raw environment


F.20.2  !win
------------

 Type & position: command, preamble & main part

 Syntax:          !win <text>

 Description:     "<text>" is only  given  out  if  you  convert  into
                  Windows Help. "<text>" will be not converted!

 See:             !=win, raw environment


F.20.3  !win_background
-----------------------

 Type & position: command, preamble

 Syntax:          !win_background [<colour>]

 Description:     With  this command you can set the background colour
                  of your Windows Help file. You can use  one  of  the
                  following  colours: red, green, blue, cyan, magenta,
                  yellow, grey and white.  But  you  should  use  only
                  white,  grey and black because the other colours are
                  quite ugly.

 Example:         !win_backgound grey


F.20.4  !win_charwidth
----------------------

 Type & position: switch, preamble & main part

 Syntax:          !win_charwidth <value>

 Description:     UDO uses a constant value for calulating the  indent
                  of  lists  and the widths of table cells. This value
                  works  even  fine  with  bold   monospaced   capital
                  letters,  but  if you use normal text the indents or
                  table cells my be too width.  You  can  adjust  this
                  value  by  using  !rtf_charwidth.  UDO  uses  150 by
                  default.

 Example:         !win_charwidth 100

 See:             Tables, Lists


F.20.5  !win_high_compression
-----------------------------

 Type & position: switch, preamble

 Syntax:          !win_high_compression

 Description:     If you use  this  switch  inside  the  preamble  the
                  Microsoft  Helpcompiler  will  compress  the Windows
                  Help file by  about  50%.  The  compression  of  the
                  Windows  Help file takes some time. A similar result
                  with  a  faster  compression  you  will   get   with
                  !win_medium_compression.

 See:             !win_medium_compression


F.20.6  !win_inline_bitmaps
---------------------------

 Type & position: switch, preamble

 Syntax:          !win_inline_bitmaps

 Description:     If  you  use this switch inside the preamble of your
                  source file  UDO  will  use  the  RTF  tag  `\bmcwd'
                  instead  of  `\bmc'  for  displaying images. In this
                  case you cannot use images larger than 64 KB. Please
                  read  the  HCP documentation to get more information
                  about the differences between these two RTF tags.

 See:             !image


F.20.7  !win_medium_compression
-------------------------------

 Type & position: switch, preamble

 Syntax:          !win_medium_compression

 Description:     If you use  this  switch  inside  the  preamble  the
                  Microsoft  Helpcompiler  will  compress  the Windows
                  Help file by about  40%.  A  better  result  with  a
                  slower     compression    you    will    get    with
                  !win_high_compression.

 See:             !win_high_compression


F.20.8  !win_propfont
---------------------

 Type & position: command, preamble

 Syntax:          !win_propfont <fontname>

 Description:     With this command you can set the font that will  be
                  used   to   display   text  inside  a  Windows  Help
                  hypertext. The default is "Times New Roman".

 Example:         !win_propfont Arial


F.21  X...
==========


F.21.1  (!xlink ...)
--------------------

 Type & position: placeholder, main part

 Syntax:          (!xlink [<text>] [<link>])

 Description:     Useful for references  to  external  documents  like
                  other  hypertexts  ore  WWW-pages.  In  contrast  to
                  (!link ...) <link> will  not   be   converted!   The
                  example  shows  how  to  make  a  link  to a popular
                  magazine in a HTML  file.  If  <link> is  empty  the
                  contents of <text> is used.

 Example:         (!xlink [Playboy] [http://www.playboy.com])

 See:             (!link ...), (!plink ...), !no_xlinks, Links


F.22  *...
==========


F.22.1  !~
----------

 Type & position: special character(s), preamble & main part

 Syntax:          !~

 Description:     These  characters will be printed as a tilde. Please
                  remember that a single tilde  is  used  for  a  non-
                  breaking space.

 Example:         !~ becomes to ~

 See:             ~, Non-breaking spaces


F.22.2  !-
----------

 Type & position: special character(s), preamble & main part

 Syntax:          !-

 Description:     With  these characters you can mark the positions of
                  a word where UDO is allowed  to  split  it  up.  The
                  example shows how to mark the syllables of "syllabi-
                  fication".

 Example:         syl!-labi!-fi!-cation

 See:             !hyphen


F.22.3  !!
----------

 Type & position: special character(s), main part

 Syntax:          !!

 Description:     Double exclamation marks are used for splitting  the
                  cells of a table row and for multiple indices.

 Example:         !index Level 1 !! Level 2

 See:             Tables, Indices


F.22.4  !..
-----------

 Type & position: special character(s), preamble & main part

 Syntax:          !..

 Description:     An  exclamation  mark followed by two points will be
                  replaced by typographical three points if the desti-
                  nation  format allows it to display them. If not UDO
                  will replace them by three normal points.

 Example:         !.. is converted to ...


F.22.5  ~
---------

 Type & position: special character(s), preamble & main part

 Syntax:          ~

 Description:     The tilde is used for a  non-breaking  space  inside
                  the UDO syntax. If a tilde is used between words UDO
                  won't  split  up  them  when   breaking   lines   or
                  calculating the justification.

 Example:         42~DM, Dr.~Helmut Kohl

 See:             !~, Non-breaking spaces


F.22.6  ""
----------

 Type & position: special character(s), preamble & main part

 Syntax:          ""

 Description:     Two  quotes  in  a row will be replaced by one typo-
                  graphical quote if the destination  format  supports
                  typographical quotes. If it doesn't UDO will replace
                  two quotes by one quote.

 Example:         "typographical quotes"

 See:             ("")


F.22.7  ("")
------------

 Type & position: special character(s), preamble & main part

 Syntax:          ("")

 Description:     If you want to print two quotes you have  to  insert
                  them between brackets. If you don't UDO will replace
                  the two quotes by a typographical quote.

 See:             ""


F.22.8  ('')
------------

 Type & position: special character(s), preamble & main part

 Syntax:          ('')

 Description:     If you want to print two  apostrophes  you  have  to
                  insert  them between brackets. If you don't UDO will
                  replace  the  two  apostrophes  by  a  typographical
                  apostrophe.

 See:             ''


F.22.9  (--)
------------

 Type & position: special character(s), preamble & main part

 Syntax:          (--)

 Description:     If  you  want to print two minus characters you have
                  to insert them between brackets. If  you  don't  UDO
                  will  replace  the  two  minus characters by a short
                  dash.

 See:             --, (---), Dashs


F.22.10  (---)
--------------

 Type & position: special character(s), preamble & main part

 Syntax:          (---)

 Description:     If you want to print three minus characters you have
                  to  insert  them  between brackets. If you don't UDO
                  will replace the three minus characters  by  a  long
                  dash.

 See:             ---, (--), Dachs


F.22.11  ''
-----------

 Type & position: special character(s), preamble & main part

 Syntax:          ""

 Description:     Two apostrophes in a row will be replaced by one ty-
                  pographical apostrophe  if  the  destination  format
                  supports  typographical  apostrophes.  If it doesn't
                  UDO will replace two apostrophes by one apostrophe.

 Example:         `typographical apostrophes'

 See:             ('')


F.22.12  --
-----------

 Type & position: special character(s), preamble & main part

 Syntax:          --

 Description:     Two minus characters in a row will be replaced by  a
                  short  dash if the destination format supports them.
                  If the destination format doesn't support  them  UDO
                  will print one normal minus character instead.

 Example:         A short - er, ah - dash.

 See:             (--), Dashs


F.22.13  ---
------------

 Type & position: special character(s), preamble & main part

 Syntax:          ---

 Description:     Three  minus characters in a row will be replaced by
                  a long dash if the destination format supports them.
                  If  the  destination format doesn't support them UDO
                  will print one normal minus character instead.

 Example:         A long - er, ah - dash

 See:             (---), Dashs



======================================================================
Appendix

UDO6
======================================================================

                       This text was made with

                                 UDO

                        Release 6 Patchlevel 0
                                 BeOS

                  Copyright (c) 1995, 1996, 1997 by
                            Dirk Hagedorn
                              Asmecke 1
                            59846 Sundern
                               Germany
                      MausNet: Dirk Hagedorn@MK2
                   America Online: DirkHage@aol.com

UDO is a program that converts files that are written in the Universal
Document Format into ASCII, ST-Guide, LaTeX, Rich Text Format, Pure C
 Help, Manualpage, HTML, WinHelp ,Texinfo, Linuxdoc-SGML, LyX, Apple
 QuickView and Turbo-Vision-Help. Further information and the current
                       versions can be found at

               http://members.aol.com/UDOENG/index.htm




