Vectronix 2/VECTRONIX2.iso/FILES_01/UDO5EREG.LZH/UDO.ASC

Text File | 1996-04-20 | 195KB | 6,499 lines

                         The documentation of

                                 UDO

                              Release 5
                            April 20, 1996

                                  by

                            Dirk Hagedorn
                           In der Esmecke 9
                        59846 Sundern, Germany

                        AOL: [e-mail]



Contents
========

 1  Introduction
    1.1  Preface
    1.2  What UDO can('t) do for you
    1.3  Do you need UDO?
    1.4  Shareware
    1.5  How much does UDO cost?
    1.6  How to register UDO
    1.7  The birth of UDO
    1.8  Contact addresses
    1.9  Thanks
    1.10  About this documentation

 2  Legal informationen
    2.1  Copyright
    2.2  Disclaimer
    2.3  Trademarks

 3  Installation
    3.1  Installing the Amgia version
    3.2  Installing the Atari version
    3.3  Installing the DOS verison
    3.4  Installing the HP-UX version
    3.5  Installing the Linux version
    3.6  Installing the Macintosh version

 4  Usage
    4.1  Command line version
         4.1.1  Command line options
         4.1.2  Environment
         4.1.3  Exit codes of the command line version
    4.2  GEM version
         4.2.1  Introducing the GEM version
         4.2.2  GEM main dialog
         4.2.3  Menu bar
         4.2.4  GEM dialog `Settings'
         4.2.5  GEM dialog `External programs'

 5  The syntax of UDO
    5.1  A short example
    5.2  Basics
         5.2.1  Let's talk about text, Baby!
         5.2.2  Commands, switches and placeholders
         5.2.3  Comments
         5.2.4  Preamble and main part
         5.2.5  Environments
    5.3  Structuring
         5.3.1  Title page
         5.3.2  Tables of contents
         5.3.3  Chapters, sections and subsections
         5.3.4  Appendix
    5.4  Emphasizing text
         5.4.1  Centered lines
         5.4.2  Indented paragraphs
         5.4.3  Itemizations
         5.4.4  Enumerations
         5.4.5  Descriptions
         5.4.6  Lists
         5.4.7  Preformatted text
         5.4.8  Footnotes
         5.4.9  Text styles
         5.4.10  Tables
    5.5  Special chars
         5.5.1  Converting 8 bit chars
         5.5.2  Double quotes
         5.5.3  Double apostrophes
         5.5.4  Non breaking spaces
         5.5.5  Dashes
    5.6  Syllabification
         5.6.1  Local definition of syllabification marks
         5.6.2  Global definition of syllabification marks
         5.6.3  Short lines
    5.7  Images
         5.7.1  *.img & ST-Guide
         5.7.2  *.img & Lindner-TeX
         5.7.3  *.img & CS-TeX/MultiTeX
         5.7.4  *.msp & emTeX
         5.7.5  *.pcx & emTeX
         5.7.6  *.gif & HTML
         5.7.7  *.bmp & WinHelp
    5.8  Miscellaneous
         5.8.1  Macros
         5.8.2  Definitions
         5.8.3  Labels
         5.8.4  Links
         5.8.5  Indices
         5.8.6  Special commands
         5.8.7  Split documents

Appendix
========

 A  FAQ
    A.1  General questions
    A.2  ASCII questions
    A.3  HTML questions
    A.4  Manualpage questions
    A.5  LaTeX questions
    A.6  Linuxdoc-SGML questions
    A.7  Pure C Help questions
    A.8  RTF questions
    A.9  ST-Guide questions
    A.10  Texinfo questions
    A.11  Turbo Vision Help questions
    A.12  Windows Help questions

 B  Known bugs

 C  Error messages and warnings
    C.1  Messages of UDO
    C.2  Syntactical messages

 D  Additional information
    D.1  Facts
    D.2  Developing environment
    D.3  Saved files

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

 F  Command index
    F.1  A...
         F.1.1  !=asc
         F.1.2  !alias
         F.1.3  !asc
         F.1.4  !author
         F.1.5  !authorimage
         F.1.6  !autoref
         F.1.7  (!alpha)
    F.2  B...
         F.2.1  !begin_appendix
         F.2.2  !begin_description
         F.2.3  !begin_document
         F.2.4  !begin_enumerate
         F.2.5  !begin_itemize
         F.2.6  !begin_quote
         F.2.7  !begin_raw
         F.2.8  !begin_table
         F.2.9  !begin_verbatim
         F.2.10  !begin_xlist
         F.2.11  !bigskip
         F.2.12  !break
         F.2.13  (!B)...(!b)
         F.2.14  (!beta)
    F.3  C...
         F.3.1  !chapterimage
         F.3.2  !code_ansi
         F.3.3  !code_ascii
    F.4  D...
         F.4.1  !date
         F.4.2  !define
    F.5  E...
         F.5.1  !else
         F.5.2  !email
         F.5.3  !end_appendix
         F.5.4  !end_description
         F.5.5  !end_document
         F.5.6  !end_enumerate
         F.5.7  !end_itemize
         F.5.8  !end_quote
         F.5.9  !end_raw
         F.5.10  !end_table
         F.5.11  !end_verbatim
         F.5.12  !end_xlist
         F.5.13  !endif
         F.5.14  !english
    F.6  F...
         F.6.1  !french
         F.6.2  !fussy
         F.6.3  (!F)...(!f)
         F.6.4  (!file)
    F.7  G...
         F.7.1  !german
         F.7.2  (!G)...(!g)
         F.7.3  (!grin)
    F.8  H...
         F.8.1  !=html
         F.8.2  !hline
         F.8.3  !html
         F.8.4  !html_merge_nodes
         F.8.5  !html_merge_subnodes
         F.8.6  !html_merge_subsubnodes
         F.8.7  !html_use_xlist
         F.8.8  !htmlname
         F.8.9  !hyphen
    F.9  I...
         F.9.1  !=info
         F.9.2  !ifdest
         F.9.3  !iflang
         F.9.4  !image
         F.9.5  !include
         F.9.6  !index
         F.9.7  !info
         F.9.8  !item
         F.9.9  !item []
         F.9.10  (!I)...(!i)
         F.9.11  (!idx ...)
         F.9.12  (!ilink ...)
         F.9.13  (!img ...)
    F.10  L...
         F.10.1  !=ldoc
         F.10.2  !label
         F.10.3  !ldoc
         F.10.4  !list_parsep
         F.10.5  (!LaTeX)
         F.10.6  (!LaTeXe)
         F.10.7  (!laugh)
         F.10.8  (!link ...)
    F.11  M...
         F.11.1  !=man
         F.11.2  !macro
         F.11.3  !maketitle
         F.11.4  !man
         F.11.5  !man_lpp
         F.11.6  !man_type
         F.11.7  !medskip
    F.12  N...
         F.12.1  !newpage
         F.12.2  !no_bottomlines
         F.12.3  !no_effects
         F.12.4  !no_headlines
         F.12.5  !no_images
         F.12.6  !no_numbers
         F.12.7  !no_quotes
         F.12.8  !no_umlaute
         F.12.9  !no_xlinks
         F.12.10  !node
         F.12.11  !node*
         F.12.12  (!N)...(!n)
         F.12.13  (!nl)
    F.13  O...
         F.13.1  (!O)...(!o)
    F.14  P...
         F.14.1  !=pch
         F.14.2  !pch
         F.14.3  !pnode
         F.14.4  !pnode*
         F.14.5  !program
         F.14.6  !programimage
         F.14.7  !psubnode
         F.14.8  !psubnode*
         F.14.9  !psubsubnode
         F.14.10  !psubsubnode*
         F.14.11  (!plink ...)
    F.15  R...
         F.15.1  !=rtf
         F.15.2  !rinclude
         F.15.3  !rtf
         F.15.4  !rtf_monofont
         F.15.5  !rtf_propfont
    F.16  S...
         F.16.1  !=stg
         F.16.2  !sloppy
         F.16.3  !smallskip
         F.16.4  !stg
         F.16.5  !stg_no_database
         F.16.6  !street
         F.16.7  !subnode
         F.16.8  !subnode*
         F.16.9  !subsubnode
         F.16.10  !subsubnode*
         F.16.11  !subsubtoc
         F.16.12  !subtoc
         F.16.13  (!S)...(!s)
         F.16.14  (!short_today)
    F.17  T...
         F.17.1  !=tex
         F.17.2  !tableofcontents
         F.17.3  !tex
         F.17.4  !tex_2e
         F.17.5  !tex_dpi
         F.17.6  !tex_emtex
         F.17.7  !tex_lindner
         F.17.8  !tex_strunk
         F.17.9  !tex_verb
         F.17.10  !title
         F.17.11  !toc
         F.17.12  !toc_offset
         F.17.13  !town
         F.17.14  (!T)...(!t)
         F.17.15  (!TeX)
         F.17.16  (!today)
    F.18  U...
         F.18.1  !use_about_udo
         F.18.2  !use_ansi_tables
         F.18.3  !use_auto_subsubtocs
         F.18.4  !use_auto_subtocs
         F.18.5  !use_chapter_images
         F.18.6  !use_formfeed
         F.18.7  !use_short_toc
         F.18.8  !use_style_book
         F.18.9  (!U)...(!u)
    F.19  V...
         F.19.1  !verbatim_no_umlaute
         F.19.2  !version
         F.19.3  !vinclude
         F.19.4  (!V)...(!v)
    F.20  W...
         F.20.1  !=win
         F.20.2  !win
         F.20.3  !win_html_look
         F.20.4  !win_propfont
    F.21  X...
         F.21.1  (!xlink ...)



Chapter 1

Introduction
************


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

Welcome to the fascinating world of UDO!

You now read the extremly updated documentation of an extremly
revised program written by an extremly overworked author.

Before I continue describing the features of UDO let me say that it
was hard work for me to translate the German documentation into
English. Well, I don't think that I'm speaking English so fine so
that I can avoid mistakes and wrong words. So please ignore these
mistakes or tell me how to explain something in a correct manner.
Thanks!

Some fellows don't like to read manuals. They just start a program
and look what it does and how it works. To use UDO isn't difficult,
but if you want to write own texts using all features of UDO you have
to read the full documentation, that's for sure.

It is recommended to read at least this introduction. Then you will
get to know why I've written UDO, if you need UDO and which pos-
sibilities it offers you if you want to use it.

If you are interested in UDO after having read this introduction I
recommend to take a look at the chapter "A short example". You will
get some basic information for writing own texts using the UDO
syntax.


If you take a look at the version of UDO you will recognize that it's
still below 1.0. I've not implemented all planned features yet. But
nevertheless this is the fifth time that I've published UDO because I
think that it could be a great help for you, too.

Hoping that UDO will be an unrenounceable utility for you, that you
will have more time for the "important" things and that you will
register UDO,

Dirk Hagedorn

Sundern, April 20, 1996


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

UDO has been developed to make it easier for you to write software
manuals or other documentation that you need in more than one format.

Sure, you can even use UDO to generate only one format. For a
beginner it's easier to learn UDO as e.g. LaTeX or HTML. Using the
latter ones you have to know e.g. which character has a special
function and how it has to be represented by other character. If you
use UDO and convert your file into LaTeX or HTML you can write you
text as you used to do it because UDO manages all of the needed
character conversion.

UDO can be used for different languages. It is possible to tell UDO
which phrases it should use for "Contents", "Figure", "Table" or the
current date. E.g. you will find the contens of the German documen-
tation of UDO titled with "Inhaltsverzeichnis".

The syntax of UDO is easy to learn. Don't get frightened if you take
a look at the "Index of commands". You will need only some commands
to write small manuals with UDO!

If you have written a text using the UDO syntax you can convert it
with UDO into

  1. LaTeX
  2. Rich Text Format (RTF),
  3. Hypertext Markup Language (HTML),
  4. GNU-Texinfo,
  5. ST-Guide,
  6. Pure C Help,
  7. Windows Help,
  8. Turbo Vision Help,
  9. Linuxdoc-SGML,
 10. a Manualpage and into
 11. ASCII

In most cases UDO just generates source files of hypertextes and
online help files that have to be converted once more e.g. *.hpj with
HC31.EXE to get a Windows Help file, *.stg with HCP.TTP to get an ST-
Guide hypertext, *.tex with LaTeX to get a DVI file, *.texi with
Makeinfo to get a file for GNU-Info.


UDO tries to help you as much as possible to get rid off hard work
like layouting or enumerating chapters. It offers you features like

   ∙ title pages, headlines, bottomlines, footnotes, tables of
     contens
   ∙ enumeration of chapters, tables and figures
   ∙ setting tables
   ∙ referencing labels and chapters
   ∙ different text styles
   ∙ conversion 8 bit chars and other special chars
   ∙ many layout features like lists, centered or indented text
   ∙ usage of images
   ∙ automatical line breaks and halfautomatical syllabification


UDO has some positive but also some negative aspects. The conversion
into ASCII, LaTeX, WinHelp and LaTeX is nearly perfect. Formats like
Texinfo, Turbi Vision Help and Linuxdoc-SGML (the implementation of
this format is only two weeks old) are implemented for only a short
period of time and still there's something to do. Don't expect too
much if you want to use these formats.

Some things that are standing right in top of my to-do-list aren't
supported yet but will be implemented in UDO6: automatic index, a
list of figures, a list of tables, the possibility to write special
commands instead of 8 bit characters to make it possible to exchange
files system wide without converting them with GNU-recode.


It's not possible to print complex files like magazines because UDO
doesn't allow it to place images where you want to and it can't
output files with two or more columns. Furthermore there are some
items UDO will never be able to handle:

   ∙ justified text,
   ∙ set free positioned pictures,
   ∙ a full syllabification,
   ∙ generation of binary files


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

If you can answer one of the following questions with "Yes, I do"
then you should take a closer look at UDO. If not UDO is hardly the
right thing for you and you should stop reading here before getting
bored of another software that you don't understand. But I think you
will take a close look, won't you?

   ∙ You are programming and you need an online help for WinHelp,
     Turbo Vision Help or the ST-Guide next to the ASCII manual?

   ∙ You are programming and you need a printed documentation printed
     out with LaTeX or a text processor that is able to import RTF?

   ∙ You are the author of a library for Pure C and you need an
     online help for Pure C next to an ASCII manual, a hypertext
     and/or printed documentation?

   ∙ You only need an ASCII manual but you are getting nervous when
     you think about layouting the text, enumerating the chapters and
     building a table of contens on your own?

   ∙ You want to publish a hypertext in the World Wide Web but you
     don't own a powerful editor for HTML files that is able to fill
     in references, to convert special chars and to split up a docu-
     ment into small files automatically?

   ∙ You need an online help for Windows but you don't want to buy a
     tool that costs more than 20 times of the price of UDO but
     cannot do much more?

   ∙ You have written an interesting text and you want to copy it to
     other people who don't use the same operating system as you do?

I'm sure that you answered one question positively. You don't? Grrr,
it was nice to meet you. ;-)


1.4  Shareware
==============

UDO is distributed as shareware. This means all of the following
itemsa:

   ∙ You may test UDO for two weeks.

   ∙ You are not allowed to publish files you have converted during
     this trial period.

   ∙ After the trial period of two weeks you have to decide if you
     want to register UDO or if you don't want to use it.

   ∙ If you want to register UDO, please go on reading the chapter
     "How to register UDO".

   ∙ If you don't want to register UDO you have to delete all files
     that are part of UDO from your hard disk or floppy disk.

   ∙ If you keep on using UDO after the trial period you are working
     with a black copy!

There are no limitations inside the command line version. Some small
limitaions are added to the GEM version. Because I think that UDO
will be used mainly by other programmers or authors of documentations
who might register UDO earlier than the rest of the unknown mass I
didn't add further limitations.

But if I have to notice that only a small ammount of people pay for
UDO I will be forced to

  1. add ugly limitations like randomly exchanged characters,

  2. copy future version only to registered users or

  3. stop developping UDO completly

Don't think that this is a joke. In the past I've been disappointed
more than once and I cannot laugh anymore about this!


1.5  How much does UDO cost?
============================

You can believe me that I thought a long time about the height of the
shareware fee. I don't want to tell you the price I had to demand for
UDO. If I would demand this price which I think UDO is worth it
nobody or too less people would register for UDO. But I think I found
a price somewhere between "dream and reality". I hope you will be
able and willing to pay this shareware fee.

The height of the shareware fee depends if you are using UDO as a
private user or as a user in a commercial field:

 Private users have to pay 20 Pounds Sterling (40 DM, US$ 25) for one
     licence of UDO. Private users are those who use UDO for manuals
     for products that cost less then 50 Pounds Sterling (100 DM,
     US$ 70). So every author of freeware or cheap shareware is a
     private user. After a registration private users are allowed to
     use UDO on one or more systems simultanously.

 Commercial users are those who use UDO for writing manuals for
     products that cost 50 Pounds Sterling (100 DM, US$ 70) or more.
     Commercial users have to pay 50 Pounds Sterling (100 DM, US$ 70)
     for the first licence of UDO and 20 Pounds Sterling (40 DM,
     US$ 25) for a further licence. Further licenses have to be paid
     for each user that is able to work with UDO.


If you are a commercial user and have paid just the shareware fee for
a private licence you have to pay the difference!


One small sentence to those users who use their registered version of
UDO at work: Please ask your "boss" if the budget of your company
allows it to buy one ore more commercial licences of UDO. Thank you!


1.6  How to register UDO
========================

It's recommended that British users register UDO via Denesh Bhabuta.
Users from outside Great Britain (espacially users from Germany,
Austria, the Netherlands and Swiss) 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?".


To register UDO via Denesh Bhabuta please send a cheque or postal
order for the appropriate ammount 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: CyberSTrider
          203 Parr Lane
          Bury
          BL9 8JW

 E-Mail:  [e-mail]
          [e-mail]
          [e-mail]

When you register, you are entitled to

   ∙ MasterDisk with latest version(s) of UDO

   ∙ Keycode to register this and future 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.


1.7  The birth of UDO
=====================

It was autumn 1994 when I finished writing some programs for which I
needed an ASCII manual, a hypertext and a printed documentation.

I began writing the ASCII manuals and to insert the needed hypertext
commands. The ASCII manual was imported into a text processor for
printing the documentation. But before I had to adjust the layout of
this documentation which took a long time. But I made some mistakes
inside the ASCII manual and so I had to correct all three version.
This way of writing the manuals was boring but there was no other
possibility.

When I finished the manuals I began to think about a program that
should enable me to write a single documentation and to convert it
into the needed formats. It took only one week to write a small
utility called "STG2ASC" that was able to filter hypertext commands
and to output a raw ASCII manual. But this tool wasn't good enough so
I've never published it (Dirk Haun received the source code and
compiled a module for `Zeig's mir').

January 1995, and still there was no solution for my problems. I
started once again to think about a software. I came to the result
that the only possible way was to develop a new format and a program
that should be able to convert this format into ASCII, LaTeX and ST-
Guide at least. The format should be easy to learn but flexible
enough, too. So I decided to develop a latexlike syntax and a
converter for this format: UDO1 was born!

Until now more than a year passed by and UDO grew up from a simple
tool for Atari computers to a very powerful piece of software for
lots of different operating systems that can generate nearly a dozen
of other formats and is able to support special features of these
formats.


1.8  Contact addresses
======================

If you want to register UDO, if you have questions or you want to see
new features please contact me using these addresses:

 Address:        Dirk Hagedorn
                 In der Esmecke 9
                 59846 Sundern
                 Germany

 Telefax:        [phone]

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

 America Online: [e-mail]

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


1.9  Thanks
===========

Without the help of the follwing persons UDO wouldn't be what it is
today.

So I would like to say "thank you" to

 Frank Baumgart for compiling the Linux version and for his tests
     when UDO produced lots of core dumps,

 Denesh Bhabuta a.k.a the CyberSTrider for supporting UDO in England,

 Andrea Bierhoff who heard me saying "I have to fix only one new
     problem, it takes only a few minutes" too often,

 Jens Brüggemann for his hints according the caching of files that
     are prehaps supported by UDO soon,

 Volker Burggräf for his hints according WinHelp,

 Alexander Clauss for his Cool Atari Browser `CAB' which enabled me
     to implement HTML in the early stage, and for testing the HP-UX
     version,

 Dirk Haun for his constructive criticism and wishes and lots more,

 Peter Klasen, the first registered user of UDO,

 Martin Loos for his effort according the mailinglist of UDO,

 Andreas Pietsch for his exciting GEM library `SysGem',

 Georg Sauerwald who enabled me to test UDO's RTF export files with
     That's Write (which doesn't imports RTF until today),

 Andreas Schrell for his hints according LaTeX,

 Manfred Ssykor for his funny ideas and the teamwork according the
     Atari Infopages,

 Holger Weets for his ST-Guide, for answering lots of questions and
     for ignoring my stupid ideas,

 Ralf Zimmermann for his hints according HTML and for zControl,

 all of you who I've forgotten in this list. Don't worry about that.
     ;-)


1.10  About this documentation
==============================

If you take a look at the size of this documentation you will
probably notice that I've tried to explain every single feature as
good as I could.

Please:

    If you have problems understanding some passages, command de-
    scriptions are missing or a command is explained in a wrong way,
    inform me about this so that I will be able to correct this docu-
    mentation!

Because I wrote both UDO and this documention it could be possible
that I've forgotten to describe a command. So please tell it to me if
something's wrong.



Chapter 2

Legal informationen
*******************


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

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

UDO is shareware and may be copied to third persons in the unregis-
tered version if all the following requirements are met:

   ∙ You have to copy it with all and unchanged files.

   ∙ You have to copy it free of charge. Uploading the original and
     unchanged archive to a noncommercial BBS or a noncommercial FTP-
     server is allowed.

   ∙ It's absolutely forbidden to add files to the original achive!

   ∙ It's not allowed to create new archives or to change the
     archiver.

   ∙ The distribution via CD-ROM needs my written permission.


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

Although UDO was tested under various conditions and Dirk Hagedorn
did everything to avoid bugs he cannot guarantee anything. So please
keep in mind that everything you do you do on your own risk!


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



Chapter 3

Installation
************


3.1  Installing the Amgia version
=================================

When writing this documentation no version for Commodore Amiga was
availabe. Please take a look at the notes added to the Amiga
distribution.


3.2  Installing the Atari version
=================================

For installing UDO on an Atari computer or one of the compatible
computers just copy all files to a directory called "UDO".

If you want to use the command line version inside a shell like
Mupfel copy or move udo.ttp to a directory that is part of $PATH.

If you are using the ST-Guide copy or move udo.hyp and udo.ref to
that directory that contains all your other hypertexts.

That's all.


3.3  Installing the DOS verison
===============================

Important hint: Because UDO has been compiled with EMX-GCC you need
the EMX Runtime Package to run UDO with MS-DOS. If you want to run
UDO inside a DOS box inside Windows you need the drivers inside
dpmigcc5.zip written by Rainer Schnitker.

If you haven't got these archives you will can get them here:

  1. via FTP:

        ∙ ftp.uni-stuttgart.de/pub/systems/os2/emx-0.9b/emxrt.zip

        ∙ ftp.uni-bielefeld.de/pub/systems/msdos/misc/dpmigcc5.zip

  2. via WWW: you will find current links on my homepage:
     http://members.aol.com/DirkHage/www/index.htm.

  3. via modem: watch the "Gruppenprogrammteil UDO.Pub" of the Maus
     MK2 ([phone])

  4. via mail: just send me (see "Dirk Hagedorn") a formatted floppy
     disk and add 2 DM for stamps


After having extracted the archive just copy all files to a directory
called "UDO".

To call UDO from COMMAND.COM you should copy or move udo386.exe to a
directory that is part of your PATH. Or add a batch file like this in
your PATH:

    [udo.bat]
    @d:\udo\udo386.exe %1 %2 %3 %4 %5 %6 %7 %8 %9


It can be very helpful to write some batch files that call UDO with
some predefined options. The following example shows how a batch file
can look like for converting an UDO file into WinHelp or HTML:

    [u2win.bat]
    @d:\udo\udo386.exe --win -o ! %1 %2 %3 %4 %5 %6 %7 %8 %9

    [u2html.bat]
    @d:\udo\udo386.exe --html -o ! %1 %2 %3 %4 %5 %6 %7 %8 %9


3.4  Installing the HP-UX version
=================================

After having extracted the archive copy the binary to /usr/local/bin,
/opt/hppd/bin or one of your directories added to $PATH.

Furthermore it makes sense to write some shell scripts. The following
example namend u2tex shows how to call UDO with some predefined
options more fast:

    if [ $# -eq 0 ]
    then
        echo "usage:" $0 "[ options ] file"
    else
        udo --tex -o ! $*
    fi

You can write similar scripts for the other destination formats if
you want. May be you will find examples in the distribution of UDO
for HP-UX.


3.5  Installing the Linux version
=================================

After having extracted the archive copy the binary to /usr/local/bin
or one of your directories added to $PATH.

Furthermore it makes sense to write some shell scripts. The following
example namend u2tex shows how to call UDO with some predefined
options more fast:

    if [ $# -eq 0 ]
    then
        echo "usage:" $0 "[ options ] file"
    else
        udo --tex -o ! $*
    fi

You can write similar scripts for the other destination formats if
you want. May be you will find examples in the distribution of UDO
for Linux.


3.6  Installing the Macintosh version
=====================================

When writing this documentation no version for Apple Macintosh was
availabe. Please take a look at the notes added to the Macintosh
distribution.



Chapter 4

Usage
*****

In this chapter you will see how to use the command line version and
the GEM version for Atari computers.


4.1  Command line version
=========================

The command line version of UDO can be used identically on every
operating system because every one was compiled with the same source
code.

When passing options to the command line version please remember
this:

  1. Don't merge options.
     Passing -a -l -y is not the same as -aly.

  2. The source file has to be the last parameter.
     When passing the command line use the name of the source file at
     the end.


4.1.1  Command line options
---------------------------

 -a, --ascii        converts the source file to ASCII.

 -c, --nocheck      UDO doesn't check the correct usage of styles.

 -h, --html         converts the source file to HTML.

 -H, --hold         UDO waits after you have pressed key before it
                    terminates.

 --help             prints a help page that describes these options.

 -i, --texinfo      converts the source file to GNU Texinfo.

 --ident            prints the date of each UDO source file.

 -l, --nologfile    UDO doesn't save a log gile if you use -o.

 -m, --man          converts the source file to a manualpage.

 -o F, --outfile F  UDO saves its output to the file named "F". If
                    you use a single "!" instead of a filename UDO
                    uses the path and name of the source file with
                    another suffix.

 -p, --pchelp       converts the source file to Pure C Help.

 -q, --quiet        UDO doesn't print any messages to standard
                    output.

 -r, --rtf          converts the source file to RTF.

 -s, --stg          converts the source file to ST-Guide.

 -t, --tex          converts the source file to LaTeX.

 --test             UDO saves a log file and a hyphenation file but
                    doesn't save the destiantion file. Use this
                    option to test your source files.

 --tree             UDO prints an include tree in a file named *.ut?
                    where you can see the logical construction of the
                    source files.

 -v, --vision       converts the source file to Turbo Vision Help.

 --verbose          prints detailed information while converting the
                    source file.

 --version          prints the number of version and the date of the
                    command line version.

 -w, --win          converts the source file to Windows Help.

 -x, --linuxdoc     converts the source file to Linuxdoc-SGML.

 -y, --nohypfile    doesn't save a hyphenation file when using -o.


4.1.2  Environment
------------------

The command line version supports the following environment settings:

 LANG         Defines the language for error messages if LC_ALL and
              LC_MESSAGES are not set.

 LC_ALL       If this environment variable contains `german' UDO uses
              German error messages. UDO uses English messages if
              LC_ALL contains any other value. If this environment
              variable doesn't exists then UDO will check LC_MESSAGES
              instead.

 LC_MESSAGES  See LC_ALL. If this environment variable doesn't exist
              UDO will check LC_ALL instead.


4.1.3  Exit codes of the command line version
---------------------------------------------

The command line version returns the following codes when finished:

 0:    Everything was OK.

 else: While converting the source file an error happened. This can
       be a syntactical error or an error due to non existing files.


4.2  GEM version
================


4.2.1  Introducing the GEM version
----------------------------------

The GEM version is more than a command line version with a GUI. The
GEM version is nearly a shell that can start editors, viewers and
external programs next to converting the source files.

In this section I will only describe the main aspects of the GEM
version. You should already know how to use GEM programs. If you
don't please take a look at the users's guide of your computer.

The GEM version runs with every GEM compatible computer e.g. Atari
ST/TT/Falcon, Eagle, Medusa, Apple Macintosh with MagiCMac,
Gemulator, Janus or STonX. You should use a resolution with 640 pixel
screen width or more.

The GEM version supports 3D look (when using 16 ore more colours),
Drag & Drop, VA protocoll, iconification, windows dialogs and
alertboxes.

When converting a source file you can interrupt it with pressing both
shift keys.


4.2.2  GEM main dialog
----------------------

The main dialog consists of a menu bar, fields for the source file
and destination file, a selection box for the destination format, a
line for status information and a button for toggling the testing
mode.


Dialog contents

 Source:
     Click the button to choose the source file inside the file
     selector.

 Destination:
     Click the button to choose the destination file inside the file
     selector.

 Destination format:
     Select the needed destination format.

 Status:
     Here you will see some information before and while converting
     the source file.

 Convert:
     Click this button to start converting the source file into the
     destination file using the selected destination format.

 Test mode:
     The selection of this button means passing the optione --test to
     the command line version.

 Help:
     The ST-Guide shall open UDO's hypertext.


4.2.3  Menu bar
---------------

 UDO/About UDO:
     Opens a dialog with more information about UDO

 UDO/Quit:
     Use this item to quit the GEM version.

 Source/Choose:
     Select the source file inside the file selector.

 Source/Edit:
     Starts the source file editor.

 Source/View:
     Starts the source file viewer.

 Source/Convert:
     Starts converting the source file into the destination file.

 Dest/Choose:
     Select the destination file inside the file selector.

 Dest/Edit:
     Starts the destination file editor.

 Dest/View:
     Starts the destination file viewer.

 Dest/Start program:
     Starts the external program you defined for the destination
     format.

 Dest/ST-Guide:
     If you select "ST-Guide" as the destination format and click
     this menu item the ST-Guide show the hypertext called
     `<destfile>.hyp'.

 Options/Settings:
     Opens the GEM dialog `Settings'.

 Options/External programs:
     Opens the GEM dialog `External programs'.

 Options/3D-Look:
     If this menu item is checked dialogs and alert boxes are
     displayed with a 3D look if you use 16 or more colours.

 Options/Register:
     Opens the GEM dialog `Registration'. Enter your name, address
     and your keycode to register UDO.

 Options/Save parameters:
     All settings are saved inside `udo.inf' in $HOME\defaults or
     $HOME.

 Options/Load parameters:
     Loads the settings from `udo.inf'.

 Help/Help:
     Shows the help text of the main dialog using the ST-Guide.

 Help/Contents:
     The ST-Guide shows the table of contents of UDO's hypertext.

 Help/Index:
     The ST-Guide shows the index of UDO's hypertext.

 Help/Command referece:
     The ST-Guide shows the command reference of UDO's hypertext.


4.2.4  GEM dialog `Settings'
----------------------------

 Adjust filename:
     If this button is selected UDO changes the name of the desti-
     nation file when changing the destination format.

     If "Completely" is selected UDO changes drive, path, name and
     suffix of the destination file.

     If "Name and suffix" is selected UDO changes name and suffix of
     the destination format. Drive and path aren't changed.

     If "Only suffix" is selecetd UDO just changes the suffix of the
     destination file.

 View destination file:
     If this button is selected the destination file will be
     displayed by the destination file viewer after having converted
     it.

 Ask before quitting:
     If this button is selected UDO ask you before terminating.

 Ask before overwriting:
     If the destination file still exists UDO asks you if it shall
     overwrite this file or not.

 Save log file:
     If this button is selected UDO writes error messages and further
     information into the file namend .ul?.

 Save hyphenation file:
     If this button is selected UDO saves proposals for !hyphen into
     the file named .uh?.

 Save tree file:
     UDO saves a tree file that show the logical construction of the
     source files if this button is selected.

 Status messages:
     UDO shows detailed information about converting the files if
     this button is selected.


4.2.5  GEM dialog `External programs'
-------------------------------------

This dialog look more confusing than it is. ;-)

In the upper part of this dialog you select which external program
you want to set. The source file editor and viewer and the destina-
tion file editor and viewer can be started from the main menu. The
specific programs can be started via "Start program" from the main
menu.

After having selected the needed program just click on the field next
to "Program:" to choose the program inside the file selector. Select
VA_START if this program supports the VA protocoll. Select TOS
program if this program is a TOS program without any GEM features.

In the lower edit field you can enter the parameters that are passed
to the external program. You can use placeholders for the name of the
source file or destination file. Just click on "Hints" to display
these placeholders.




How UDO launches external programs
----------------------------------

  1. When using Gemini UDO tells Gemini to start the program.

  2. If the program is an accessory UDO send VA_START.

  3. If MagiC or MultiTOS is installed the program is started
     parallel.

  4. If you are using SingleTOS UDO starts the program using pexec()
     after having closed all windows.



Chapter 5

The syntax of UDO
*****************


5.1  A short example
====================

Before going into details I want to show you how a source file. You
can use this example to make you own source files if you want to.

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

    ########################################
    # @(#) An example for UDO
    # @(#) Dirk Hagedorn, 1996/04/16
    ########################################

    !tex \documentstyle[11pt]{article}
    !stg @subject "Documentation/Utilities"

    !title   A short example for
    !program UDO
    !date    (!today)
    !author  Dirk Hagedorn

    !use_auto_subtocs    [info,html,stg,tvh,win]
    !use_auto_subsubtocs [info,html,stg,tvh,win]
    !no_effects          [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 splitted by using empty lines or commands.


    !node A chapter
    This is the text of this chapter.

    Due to the switches inside the preamble it folllows a
    table-of-contens-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 important for LaTeX. Without this or a similar line
LaTeX wouldn't be able to convert the tex file into a dvi file. If
you don't know LaTeX add this line at the beginning of your file.

The next line is also a special line. This line contains a special
command for the ST-Guide. If you dont'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 hypertextes. The ab-
breviations of these hypertextes 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 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 in-
formation 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 contens 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!


5.2  Basics
===========


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

UDO expects a text file that you can make 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 should
be 512 charaters long at maximum.

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

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

 Paragraphs consist of words. Paragraphs are devided by one or more
     empty line or UDO commands. UDO devides paragraphs by one empty
     line when printig the destination file.

You can compose the source file using different charsets. UDO
supports the ASCII charset of your operating system and the charset
of Windows. UDO expects the ASCII charset by default. You have to
tell UDO that text written with an editor for Windows follows with
the switch !code_ansi. If you want to use ASCII chars again you have
to insert !code_ascii.


5.2.2  Commands, switches and placeholders
------------------------------------------

 Commands:    An UDO command begins with a single "!" at the
              beginning of a line, may be indented by spaces or tabs.
              A command tells UDO to do something in this place e.g.
              the output of a table of contens through
              !tableofcontents.

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

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


5.2.3  Comments
---------------

A source file can contain comments. UDO ignores a line if the first
character of a line is a `#'. This character doesn't have to 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.


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


5.2.5  Environments
-------------------

An environment is a part of a source file that has to be converted in
a special way. Environments are started with !begin_ and ended with
!end_.

UDO supports lots of environments:

 appendix environment:    Appendix
 center environment:      Centered lines
 description environment: Descriptions
 document environment:    Main part of the document
 enumerate environment:   Enumerations
 itemize environment:     Itemizations
 quote environment:       Indented lines
 raw environment:         Special commands
 verbatim environment:    Preformatted text
 xlist environment:       Lists

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


5.3  Structuring
================


5.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 !title,
!program, !programimage, !version, !date, !author, !authorimage,
!street, !town and/or !email.

When used !maketitle should only be used directly after !begin_docu-
ment. 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
contens.

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

If you want to make your own title page you have to use tricks. This
could be very complicated so I recommend to use the title page
generated by !maketitle


5.3.2  Tables of contents
-------------------------

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

Furthermore you can tell UDO to generate only a short version of this
table of contens using the switch !use_short_toc inside the preamble.
If you write a large source file that contains lots of chapters you
should use this switch if you want to build hypertexts.

If you want to list all sections of a chapter or all subsections of
section you can output it with the commands called !subtoc and
!subsubtoc. This is useful for hypertexts where you then have the
possibility to switch directly to an interesting section or
subsection. UDO enables you to automize the output of these
"subtoc's" using the switches !use_auto_subtocs and
!use_auto_subsubtocs.

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


5.3.3  Chapters, sections and subsections
-----------------------------------------

If you want to start a new chapter you have to use the command !node
and to enter the name of this chapter. The commands !subnode and
!subsubnode have the same function for sections and subsections are

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

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

The table of contens should look like this:

    1  A chapter
       1.1  A section
            1.1.1  A subsection

    2  And a different chapter

Furthermore you are enabled to display chapters inside popups when
converting your source file to Windows Help or ST-Guide. Just add a
"p" after the "!" (!pnode instead of !node) and the text will be
displayed using a popup.

As you have seen in the upper example UDO enumerates the chapters of
your source file. If you aren't interested in these numbers you can
use the switch !no_numbers to suppress the output of numbers.


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

The table of contens should look like this:

    5  A chapter outside the appendix

    Appendix

    A  A chapter
       A.1  A section
            A.1.1  A subsection


5.4  Emphasizing text
=====================

In this section you will get to know how to format passages in
different kinds. UDO supports centered and indented paragraphs,
different kinds of lists, environments for preformatted text and
tables. Futhermore you can use different text styles and footnotes.


5.4.1  Centered lines
---------------------

Lines that are part of a center environment will be displayed centerd
on the destination format if it supports centered lines.

You cannot use this environment inside other environemnts or other
environments inside the center environments.

This short example...

    !begin_center
    A centered line.

    A centered paragraph
    with two source lines.

    The Guide to (!nl)
    UDO
    !end_center

... will be displayed as:

                          A centered line.

             A centered paragraph with two source lines.

                            The Guide to
                                 UDO

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


5.4.2  Indented paragraphs
--------------------------

To display indented paragraphs you can use the quote environment
which is started with !begin_quote and finished with !end_quote.

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.

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


5.4.3  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 up to four times inside one
another or mixed with other environments. This short example shows a
nonmixed 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 parapgraph of the
          second item of the itemize environment.
    !item This is the last item.
    !end_itemize

... becomes to:

   ∙ This is the first item.

   ∙ This is the second item with a little bit more text to
     demonstrate how UDO formats an itemization.

     This is the second parapgraph 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

... becomes to:

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


5.4.4  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 this environment inside all the other environments or all
other environments inside the enumerate environment. This short
example...

    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

... wird:

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:

    !begin_enumerate
    !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.


5.4.5  Descriptions
-------------------

Use the description environment when describing some words. Start the
environment with !begin_description and finish it using !end_de-
scription.

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

You can use the description environment up to 4 times and mixed up
with other environments.

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

... becomes to:

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 in a mixed way:

    !begin_description
    !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


5.4.6  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. Words aren't printed in bold text.

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 descriped has to used
inside the brackets of the !item [...] command.

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

... becomes to:

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)

Attention: HTML doesn't support these lists directly. So UDO displays
xlist environments like ASCII and used with the preformatted text.

Using the switch !no_xlist you can set the destination format(s)
where xlist environments have to be handled as description environ-
ments.


5.4.7  Preformatted text
------------------------

UDO formats the read text 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 displayes
the text with a nonproportional font.


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 destionation format you cannot use
this environment. You have to use the raw environment instead.


Hints:

  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. You should't use tabs (ASCII 9) inside a verbatim environment
     because they may confuse a program that is used for the desti-
     nation format.


5.4.8  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" 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
   ∙ Texinfo
   ∙ Linuxdoc-SGML
   ∙ RTF


5.4.9  Text styles
------------------

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

At the moment UDO supports bold, italic, underlined, shadowed,
hollow, framed, preformatted and nonproportional 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),
(!S)shadowed(!s),
(!G)hollow(!g),
(!F)framed(!f),
(!V)preformatted(!v) and
(!T)nonproportional 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>   |
+------+-------+----------+-------------+--------+---------+--------+
| (!S) |       | @{S}     |             | {\shad | {\shad  |        |
| (!s) |       | @{s}     |             | }      | }       |        |
+------+-------+----------+-------------+--------+---------+--------+
| (!G) |       | @{G}     |             |        |         |        |
| (!g) |       | @{G}     |             |        |         |        |
+------+-------+----------+-------------+--------+---------+--------+
| (!O) |       | @{O}     |             | {\outl | {\outl  |        |
| (!o) |       | @{o}     |             | }      | }       |        |
+------+-------+----------+-------------+--------+---------+--------+
| (!F) |       |          | {\fbox      |        |         |        |
| (!f) |       |          | }           |        |         |        |
+------+-------+----------+-------------+--------+---------+--------+
| (!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 dont'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.


5.4.10  Tables
--------------

Since Release 5 you are able to print simple tables with UDO. You can
define the justification of the columns and the usage of horizontal
and vertical 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 envi-
ronment!

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

Now you can insert the cells of the table. You have to insert a
column in one source line and you have to devide the cells by using
`!!'.

If you want to insert a horizontal line you can use the !hline
command.

Here you will see a short example that demonstrates the usage of the
upper descriped 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 centered and
the third columns is printed right justified:


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

                      (Table 2: Tables with UDO)


Because I used a `|' before and after every column they are devided
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.


A further example shows the upper table without any lines:


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

                     (Table 3: A futher 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 with
the PC graphic charset instead of +, - and | when converting into an
ASCII like format like ASCII or ST-Guide.


Notes:

   ∙ Tables are always printed centered

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

   ∙ Like HTML Windows Help doesn't allow to use free lines. Unfor-
     tunately it's not possible to print centered tables.

   ∙ Converting to RTF tables are printed in ASCII format with a
     nonproportional charset.

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


5.5  Special chars
==================


5.5.1  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
ß 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 you should
convert files that contain only characters of the MS-DOS charset etc.
If you have a source file from a different operating system you may
be have to recode it with GNU Recode.

But UDO also supports the Windows ANSI charset. So you have the
possibility to use a Windows editor for writing the complete source
file or even some passages of a source file. If a paragraph uses
Windows ANSI characters you have to tell UDO about that. Use the
switch !code_ansi before this paragraph. If you want to switch back
to the system charset use !code_ascii.


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

Note: If I've forgotten any character or a character is converted in
a wrong way please contact me!


5.5.2  Double quotes
--------------------

Double quotes of the source file will be converted to "real" quotes
if they are supported from 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.

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


5.5.3  Double apostrophes
-------------------------

Like double quotes UDO can convert double apostrophes into `real'
apostrophes:

    double ''apostrophes''

will become

    double `apostrophes'

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

The switch !no_quotes switches off the conversion of these double
apostrophes, too.


5.5.4  Non breaking spaces
--------------------------

If you want to insert non breaking spaces between two words you have
to use the tilde (~).

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:
 RTF:     \~
 WinHelp: \~


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

Note: Don't forget to quote a tilde when using external links inside
HTML!


5.5.5  Dashes
-------------

UDO supports - did you think anythink else - dashes like in this
sentence. To display a long dash you have to use three `-' in a row.
A short dash is displayed using two `-'.

Dashes 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 (--
).


5.6  Syllabification
====================

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

You have two possibilities to set the syllabification marks:

  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 !/-.


5.6.1  Local definition of syllabification marks
------------------------------------------------

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:

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


5.6.2  Global definition of syllabification marks
-------------------------------------------------

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 sourcefile:

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


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

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.


5.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 shall explain 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 automize it.


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


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


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 orginial one with the first and the copy with the second
resolution.


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


5.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{center}
    \begin{picture}(<w>,<h>)
        \put(0,<h>){\special{em:graph tiger.msp}}
    \end{picture}
    \end{center}
    \caption{A tiger}
    \end{figure}

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


5.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{center}
    \begin{picture}(<w>,<h>)
        \put(0,<h>){\special{em:graph tiger.pcx}}
    \end{picture}
    \end{center}
    \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.


5.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=center>
    <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=center>
    <img src="../gif/tiger.gif" alt="">
    </p><br>


5.7.7  *.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


5.8  Miscellaneous
==================


5.8.1  Macros
-------------

Macros are userdefined placeholders that you can use for different
things. Let me show you some examples:

    !macro HTML Hypertext Markup Language
    !macro UDO  (!B)U(!b)niversal (!B)Do(!b)cument
    !macro TOSG (!T)UDO5GDOS.ZIP(!t)
    !ifdest [html]
      !macro PICPATH gif/
    !else
      !macro PICPATH img/
    !endif
    [...]
    The (!HTML) ...
    The (!UDO) Format ...
    The archive named (!TOSG) ...
    !image (!PICPATH)/tiger

Macros can help you to save time when typing often used long words.
Furthermore nacros can help you to change the contents of your file
if something has changed. Another example is the usage of
standardized text 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 dislaimer 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.

Please remember that you shouldn't use the names of predefined macros
like (!B) or (!nl). 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 64.


5.8.2  Definitions
------------------

Like macros definitions are user defined placeholders. You can use
them to insert special commands inside the text 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 see you can use definitions to insert special commands that
aren't supported by UDO. The last release offered a lot of special
commands for LaTeX that you know have to simulate with the !define
command:

    !ifdest [tex]
      !define nolb3 \nolinebreak[3]
      !define lb2 \linebreak[2]
    !else
      !define nolb3
      !define lb2
    !endif


UDO allows up to 64 definitions. You shouldn't name definitions as
predefined placeholders like (!nl) or (!B).


5.8.3  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 ari example
 Turbo-Vision:  .topic example inside the header
 WinHelp:       K{\footnote K example}
                #{\footnote # example}


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


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

Using the (!link ...) command you can set links to parts of the
current document. You can link to chapters, sections, subsections,
labels and aliases.

    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")

When converting to HTML or Windows Help 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!


With the (!xlink ...) ("external link") command you can add links
from your document to other documents, net sites or hypertexts. The
difference to the upper command: UDO doesn't adjust special chars of
the link destination expecting the tilde.

    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)


Espacially 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


Espacially 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])


Hints
-----

  1. An often mistake is to forget that you have to "quote" the tilde
     when using external links. If you don't use !~ the HTML browser
     tries to connect to a site with a blank inside the URL. In most
     cases the connection will fail.

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

  3. If you want to use the characters ")" or "]" inside these
     commands you have to mark it with a "!". If you don't mark them
     UDO will think that a command is finished and it would display
     an error message. An example:

         Falsch:  (!link [brackets])] [link])
         Richtig: (!link [brackets!]!)] [link])
                                  ----

  4. Inside a paragraph you can use up to 200 links. If this number
     is exceeded UDO will print an error message. Try to split up
     this paragraph into two paragraphs.


5.8.5  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 in the index of LaTeX, in the index of an ST- Guide
hypertext or in the search dialog of Windows Help.


If you use the placeholder (!idx ...) you can use up to four
parameters. This placeholder will only be converted to LaTeX. If the
source file is converted to another format only the first parameter
will be printed:

    UDO:    an (!idx [entry])
    LaTeX:  an entry\index{entry}
    else:   an entry

    UDO:    a (!idx [word] [entry])
    LaTeX:  a Wort\index{entry}
    else:   a Wort

    UDO:    a (!idx [word] [entry] [subentry])
    LaTeX:  a word\index{entry!subentry}
    else:   a word

    UDO:    a (!idx [word] [entry] [subentry] [subsubentry])
    LaTeX:  a word\index{entry!subentry!subsubentry}
    else:   a word

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] )


5.8.6  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
 html  HTML
 info  Texinfo
 ldoc  Linuxdoc-SGML
 man   Manualpage
 pch   Pure C Help
 rtf   RTF
 stg   ST-Guide
 tex   LaTeX
 tvh   Turbo Vision Help
 win   Windows Help

For every destionation 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 exmple 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


If you want to add different text for the destination formats with
UDO commands and conversion of special commands you can use the
following environment that begins with !ifdest ("if destination"),
may be followed by !else and ends with !endif. You can use this en-
vironment like "programming" a source file. This example shows what I
mean:

    !ifdest [stg,win]
      !title The hypertext of
    !else
      !title The documentation of
    !endif

For ST-Guide and Windows Help the title of the source file is set to
"The hypertext of" and to "The documentation of" for all the other
destination format. As you see in the upper example you can insert
more than one abbreviation in brackets.

A similar environment is used for the other way. It begins with
!ifndest ("if not destination"). The following example demonstrates
how to generate a titlepage for all formates excepting RTF:

    !ifndest [rtf]
    !maketitle
    !endif


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.

Text that is part of a raw environment is printed "as is". That means
that it's not converted and not indented. You can use this environ-
ment e.g. to insert large and very special blocks of LaTeX or HTML
commands like tables or HTML formulars.


5.8.7  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 whereever you want. So you can define macros,
definitions or hyphenations 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").




Appendix A

FAQ
***

The following sections shall answer some frequently asked questions
and they shall help you to solve smaller problems. Futhermore you
will get some information about the internal aspects of UDO. In first
place I want to answer some general question before I go on with
answering some specific questions.


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

 What does `FAQ' mean?

     "FAQ" is the abbreviation for "Frequently Asked Questions". An
     FAQ shows these questions with the answers.

 Why is UDO named `UDO'?

     When I started programming UDO I needed a name for this project.
     I had no better idea than naming it UDO, the abbreviation for
     "Universal Document".

     By the way: my prename is Dirk, not Udo!

 Where do I find the current versions?

     I will upload current versions of UDO to the "Gruppenpro-
     gramm teil UDO.Pub" of the Maus Iserlohn MK2 ([phone]).
     New versions will be introduced inside the MausNet newsgroup
     called "ATARI.NEWS". This newsgroup isn't exported to Usenet.

     The current version are also available via FTP. You will find
     the German versions on members.aol.com/UDODH/ and the English
     version on members.aol.com/UDOENG/.

     If you have access to the World Wide Web you can use the URL
     http://members.aol.com/UDODH/index.htm to download the current
     version of UDO.

     If you don't have the possibility to call the BBS Maus MK2 or to
     connect to AOL's FTP server you can send me a formatted floppy
     disk and a readdressed envelope. Please add 2 DM, 1 Pound
     Sterling or US$ 1 for stamps.

     The archives are named the following way:

         udorlyyy.sss
            ||| ||  |
            ||| |+--+--- .zip: compressed with ST-Zip or PKZIP
            ||| |        .tgz: tar archive compressed with gzip
            ||| |
            ||+-+------- lin:  Linux i86 version
            ||           l68:  Linux 68k version
            ||           hpx:  HP-UX version
            ||           tos:  Atari version
            ||           dos:  DOS, OS/2, Windows version
            ||           ami:  Amiga version
            ||           man:  documentation source files
            ||
            |+---------- g:    German version
            |            e:    English version
            |
            +----------- release: 5 for UDO Rel. 5

     The archive containing the English Atari release 5 is named
     udo4etos.zip. The archive containing the German documentation
     source files is named udo5gman.zip.

     If the archives are uploaded to an FTP server the will be named
     with longer names e.g. udo5_eng_linux.tar.gz or udo5_ger_hp-
     ux-700.tar.gz.

 Will UDO be ported to other operating systems?

     Today there are existing versions for Atari, DOS, Linux and HP-
     UX. In a few months there will be versions for Macintosh, Amiga,
     Sparc and Indy.

     UDO was written with highly portable C. That means that I don't
     use any specific funtions so that UDO can be compiled with any
     ANSI C compiler.

     If you are interested in porting UDO to a specific system just
     send me (see "Dirk Hagedorn") an email.

 Can I generate formats that aren't existing on my system?

     Sure. You can make ST-Guide hypertexts on a DOS computer or
     Windows Help files on a Unix computer. In some cases you just
     have to convert the files into another charset because UDO uses
     the charset of the current system.

 Do you add other formats in the future?

     That depends on the information I will get. I'm interested in
     Adobe Acrobat for myself but until today I've not found any in-
     formation about this format.

     Furthermore some people asked for the OS/2 Book format. I
     couldn't implement this format because I don't know anything
     about this one. If you are interested in this OS/2 Book just
     send me any information about it. Then I will try to implement
     it.

 May the UDO syntax change in the future?

     Until UDO hasn't reached the magical version of 1.0 the syntax
     of UDO may change. New formats sometimes need new commands. If
     the syntax changes I will give special information so that you
     will be able to change your source files in a few moments.

 How does UDO work?

     UDO needs two passes to convert a source file. In the first pass
     it reads in macros, definitions and the names of the chapters it
     needs for the tables of contents and for inserting references.
     During the second pass UDO reads in the source file line by line
     and saves the words of a paragraph. If a command or an empty
     line appears UDO starts layouting the paragraph or handles the
     command.

 How does UDO insert references?

     UDO inserts links to other parts of the document when converting
     to hypertext formats like HTML, Windows Help, Pure C Help and
     Turbo Vision Help. UDO just insert links to other pages.

     The switch called !autoref is used to switch on or off this
     feature.

     Because UDO doesn't insert links to the same page you have to
     use a trick e.g. to jump to the top of the current page. Insert
     a link on your own using the link command:

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


A.2  ASCII questions
====================

 Do you plan to split up files like in HTML?

     Until today just one (unregistered) user asked for the
     possibility to split up an ASCII document into different files.
     Because no one else asked for this I didn't implement this
     feature.

     But anybody needs it it would take only take one or two hours to
     implement it.

 Some lines are longer than 70 characters, why?

     These are the lines with text styles like bold, italic or
     underlined text. UDO uses the same characters as they are used
     inside Usenet to switch on text styles. These are * for bold
     text, / for italics and _ for underlined text.

     Because some printing software convert these characters into
     printer commands UDO doesn't count these characters.


A.3  HTML questions
===================

 How can I suppress splitting up the document

     In contrast to the other files UDO splits up the document into
     different HTML files. For every chapter, section and subsection
     UDO saves a single .htm file. The names are built with the
     number of the current chapter, section and subsection. The table
     of contents and the title page are saved into the file you pass
     UDO inside the command line with --outfile.

     Using the switches called !html_merge_nodes,
     !html_merge_subnodes or !html_merge_subsubnodes you can suppress
     the splitting up of the document.

     If you use !html_merge_nodes inside the preamble all chapters,
     sections and subsections are saved inside a single HTML file.
     That means that the whole document is saved into a single file.
     You should only use this feature if you convert small files.

     If you use !html_merge_subnodes all sections and subsections are
     saved inside the same file of the current chapter. The chapters
     are saved inside different files.

     Finally the !html_merge_subsubnodes command tells UDO to save
     the subsections inside the same file as the current section. All
     sections and chapters are saved inside a single file.

 Can I change the filenames when converting to HTML?

     Using the !htmlname command you can set the filename UDO uses
     the given name for generating the HTML file instead of
     "c_0a1009.htm". E.g. use

         !htmlname intro

     to set the filename for a chapter called "Introduction".

 How can I suppress the headlines?

     UDO automatically generates headlines on each page containing
     images with links to the previous, upper and next page and the
     title of the document. If you don't like the headlines you can
     use the switch called !no_headlines [html] that suppresses them.

 How can I easily set headlines and bottomlines?

     To set headlines or bottomlines on your own you can use macros
     that you enter at the beginning and the end of each chapter. I
     used them on my homepage using these macros:

      Main file:

          !ifdest [html]
          !define HR <hr>
          !define ADR <address>
          !define adr </address>
          !macro  HEAD [ Software | Contact | Links ] (!HR)
          !macro  FOOT (!ADR)Dirk Hagedorn - last update (!short_today)(!adr)
          !else
          !define HR
          !define ADR
          !define adr
          !macro  HEAD
          !macro  FOOT

      software.ui:

          !node Software
          !htmlname software
          (!HEAD)
          [...]
          (!FOOT)

     If you convert to HTML on the macros "(!HEAD)" and "(!FOOT)"
     will be replaced with the defined text and UDO sets links to the
     other chapters automatically.

     For the other formats empty macros are defined. UDO will then
     display nothing.


A.4  Manualpage questions
=========================

This format is a special kind of ASCII where bold and underlined text
is simulated with backspace sequences. Manualpages are used for Unix
and its tools.

Something's still missing here...


A.5  LaTeX questions
====================

Something's still missing here...


A.6  Linuxdoc-SGML questions
============================

It happened in the middle of march 1996 when I read something about
Linuxdoc-SGML in the German magazine "iX". Interested in this
software I downloaded the current version, read the documentation and
implemented this new format into UDO. Because I've no computer
running Linux I wasn't able to test the output of UDO. But I think it
will work because everything is based on the "User's Guide" of
Linuxdoc- SGML.

Like UDO Linuxdoc-SGML is a multiformat converter that converts SGML
into LaTeX, manualpages, RTF, HTML and Texinfo. But I want to say
that UDO can do much more as Linuxdoc-SGML 1.5 and UDO is much more
easy to install.

 UDO saves the xlist environment like the description environment!?

     Linuxdoc-SGML can't generate an xlist environment like thing so
     UDO interprets xlist environments like description environments
     instead because this is the most similar environment.


A.7  Pure C Help questions
==========================

This format is just interesting for authors who use the Pure C
compiler. It plays no other role inside the (still existing) world of
Atari computers.

 How does UDO saves the title page and the table of contents?

     UDO saves an own page containing the title information and the
     table of contents. Writing huge documents you should use the
     switch !use_short_toc [pch] together with !use_auto_subtocs to
     enable owners of "small" monitors to see immediately what you
     have written.

 How can I suppress the headlines?

     UDO generates on each page a headline containing the name of the
     current chapter and the title of the document. The reader can
     jump to the table of contents clicking the title information.

     Using the switch !no_headlines [pch] you can suppress the output
     of these headlines.

 And the bottomlines?

     UDO saves on each page some bottomlines. In these bottomlines
     you will find the previous, upper and next chapter. The reader
     of the Pure C Help file can click these bottomlines to jumo to
     these chapters.

     Using the switch !no_bottomlines [pch] you can suppress the
     output of these bottomlines.

 What can I do with the project file?

     When having converted the document UDO saves a project file that
     is used by the Pure C helpcompiler to make a hypertext out of
     UDO's output.

     UDO overwrites this file without any warning. To save manual
     changes of this enable set write protection of this file.


A.8  RTF questions
==================

The Rich Text Format (RTF) was developed to exchange documents
systemwide. This format has been defined by Microsoft but there can
be added new commands. A parser that interprets an RTF file should
ignore all the commands it doesn't know. Unfortunately not all text
processors act like this.

 Why doesn't UDO generate a table of contents?

     UDO thinks that you want to print your document with a text
     processor that can import RTF. But UDO doesn't know on which
     page a chapter will be disaplayed. So you should generate the
     table of contents with the text processor.

     It for sure that UDO could generate a table of contents if I
     want it. But I think you wouldn't like to have a printed docu-
     mentation without page numbers.

 Why can't UDO include images into an RTF file?

     Until today I dont't know how to insert images into an RTF file.
     When I will have got further information I will implement this
     feature.

 My text processor displays a lot of rubbish!?

     Well, then you have bad luck. UDO generates RTF files that use
     only commands that have been defined. If you have the
     possibility to contact the authors of your text processor send
     them the file UDO has generated.

     By the way: Expect Christian Nieber from R.O.M.-Logicware
     (Papyrus) nobody answered my emails according problems with RTF!

 Umlauts are displayed in a wrong way, why?

     UDO generates RTF files using the PC charset. Every text
     processor should be able to understand the ANSI, Macintish and
     PC charset. If your text processor gets in trouble please
     contact the authors of it. It's a bug of your text processor.

 Why are "real" quotes displayed in a wrong way?

     That's a serious problem because the PC charset doesn't support
     these real quotes. If you have problems

       1. remap your font or

       2. use the swicth !no_quotes [rtf] inside the preamble.

 Atari Works can't import the RTF file?

     The RTF import function of Atari Works is a catastrophe. Because
     Atari wouldn't do anything concerning computers in the future I
     just can give you the advice to buy a good text processor like
     Papyrus.

 That's Write displays bombs when importing an RTF file!?

     That's a problem of That's Write that cannot import RTF files
     correctly (against the meaning of its authors). Try to switch of
     the dictionary function of That's Write. May be that will help.


A.9  ST-Guide questions
=======================

 Images aren't displayed centered, why?

     Until today there's just the possibility to set a vertical
     offset for displaying images. Because this offset will be
     calculated using the width of the system charset with 10pt
     images might be displayed in a wrong way when using other fonts.

     So use a nonpropotional an 10pt sized font to read your
     hypertext.

 How does UDO generate the title page and table of contents?

     The title page and the table of contents are displayed on a
     single page. The title page gets the name "Main". The table of
     contents is named "Table of contents" and gets the primary name
     "Main".

     To tell the ST-Guide to display the first node of the hypertext
     just pass the name of the hypertext to it. To display the table
     of contents tell him to display the node "Main".

 How can I suppress the output of headlines?

     UDO generates on every page a headline containing the title of
     the chapter and the title of the document by default. The
     headlines will be displayed underlined.

     To suppress these headlines use the switch !no_headlines [stg]
     inside the preamble.

 How does UDO reference?

     Except links commands like (!link ...) or (!xlink ...) UDO
     doesn't insert references. This will be done by the HCP of the
     ST-Guide.

 How will labels be converted?

     UDO converts its command !label into the HCP command @symbol
     ari. You aren't allowed to use the text of a label twice because
     then the HCP would display an error message.

 How can I generate popup nodes?

     Using the commands like !pnode you can say UDO that he should
     generate a popup node. When displaying popup nodes keep this in
     mind:

     The ST-Guide allowes only 12 lines of text inide a popup node
     that are 60 chars long. Popup nodes shouldn't contain images or
     links to other nodes.

     UDO uses a linelength of 60 chars per line when displaying popup
     nodes but it doesn't check the number of lines or the usage of
     links or images. So be careful.

 HCP displays "please add...", why?

     If the HCP displays the error message "please add a @subject-
     command to this text" at the end of converting UDO's ouput you
     have forgotten to add a special ST-Guide command to your source
     file:

         !stg @subject "..."

     If you don't know the ST-Guide just insert
     "Documentation/Utilities". More information will be found inside
     the hypertext of the ST-Guide or HCP.


A.10  Texinfo questions
=======================

Inside the world of GNU software Texinfo is used for printed docu-
mentations and online help files for lots of programs. You can use
Plain-TeX to get a printed manual or Makeinfo to generate a hypertex
for Info, the hypertext browser,

UDO uses on systems that only support 8+3 filenames the suffix .tex.
On other systems it uses .texi.

 Why does UDO change the name of the chapters?

     Makeinfo or Info get into trouble if the name of a chapter
     contains special chars like brackets, commas or points. UDO
     deletes these chars to avoid this trouble.

     If you print out the Texinfo file with (!Tex) you will see these
     special chars.

     Something's still missing here...


A.11  Turbo Vision Help questions
=================================

This format is used to generate online help files for programs that
are compiled with the Turbo Vision library of Borland. You have to
convert UDO's output with the Turbo Vision Help Compiler TVHC.EXE
that is distributed with the complete source code.

Unfortunately there are existing different version of this compiler
so I wasn't able to check UDO's output until today. If I will be able
to check it I'm going to discuss question at this place.


A.12  Windows Help questions
============================

 Windows Help thinks that *.rtf or *.hpj are no help files?

     Both aren't complete help files. You have to pass the project
     file .hpj to the help compiler called HC.EXE or HC31.EXE to
     compile a help file for Windows Help. The RTF file just contains
     the source code of the help file.

 Where can I get HC31.EXE?

     HC31.EXE isn't freeware I think. Microsoft and Borland add this
     help compiler to their development system. May be both of them
     think that Windows Help wasn't developed to display general help
     files.

     Please ask one of them if you can get the help compiler without
     buying a complete compiler package. That's difficult, I know.

 Why does the HC always displays error messages?

     If the help compiler doesn't generate a help file please take a
     further look at the log file of UDO called .ulw. If you will
     find some error messages correct the errors and try it again.

     If the HC still displays the error messages check out the RTF
     file at the given position.

     In most cases you have made an error inside the source file.
     Make sure that you have inserted the commands !begin_document
     and !end_document!

     In some cases you can add a `}' at the end of the RTF file and
     hope that it will work.

 What is the file `hpj' good for?

     UDO generates a project file for the help compiler of Windows
     Help. The help compiler uses this project file to make a Windows
     Help file. In this project file certain information is added
     like the title of the help file, the generation of further
     button and so on.

     UDO overwrites this project file without asking you. If you want
     to protect your manually added changes enable write protection
     to this file.

 In which way does UDO generate the headlines?

     UDO generates on every page (except the title page and the table
     of contents) a headline. In this headline UDO displays the
     chapter title of the current page inside a non scrolling region.
     So you can still see the title of the current chapter if you
     scroll down.

     If you use the switch !no_headlines [win] UDO will still display
     the headlines but it will suppress the non scrolling regions.
     Then the chapter title will be scrolled as the rest of the text.

 How does UDO generate context strings?

     If you want to link from other Windows Help files to the file
     generated by UDO and HC you have to know how the context strings
     of a chapter looks like.

     Windows Help doesn't allow special chars inside a context string
     so UDO has to convert them:

       1. UDO replaces special chars by the RTF syntax

       2. Blanks will be replaced by underscores.

       3. All other chars (excepting numbers and letters) will be
          replaced by hex values with a preceeding underscore.

     An example:

         UDO:     !node Introducing LaTeX Part 1
         WinHelp: #{footnote # Introcuding_LaTeX_Part_1}

 UDO doesn't display centered tables, why?

     I think it's not possible to make centered tables. Or I still
     haven't found the possibility to generate them.

 Why does UDO indent items of an xlist environemt so widely?

     UDO doesn't know the wide of each char of the used charset. So
     he uses a constant value that will work fine even with bold,
     capitalized and nonproportinal charsets. The indent is a bit
     high for a normal charset, that's true. But I think this is
     better than a indent that is too small when using "wide"
     charsets.



Appendix B

Known bugs
**********

 Text styles inside indices: You cannot use text styles inside
     indices at the moment. Use them outside the (!idx ...) command.

 Images & emTeX: The generation of emTeX macros for MSP and PCX
     graphics is still young. First tests delivered good results. If
     something will go wrong use the switch !no_images [tex] and
     insert your own commands using the raw environment.

 Small errors at the layout of a Windows Help file: If many chapters
     are used and the numbers are getting wide the indents inside a
     table of contens can be wrong. Use the switch !no_numbers [win]
     then.

 Tildes inside !node, !alias and !label: The `~' symbol inside the
     name of a chapter etc. makes big problems. Try to avoid them.

 Headlines and HTML: If you merge nodes some links inside the
     headlines are wrong.


If you notice another bug please send me (see "Dirk Hagedorn") an
email.

Try to add a short example in which I can see what goes wrong. You
should also write what UDO should output instead. Then I will be able
to understand what you mean.

I think you will believe me that I can't say anything to messages
like "UDO's output is rubbish", "Why doesn't work the version for X?"
or "Why does UDO save it this way and not the other way?".



Appendix C

Error messages and warnings
***************************

UDO prints error messages and warnings to the standard output, the
standard error device or to a log file called *.ul?.


C.1  Messages of UDO
====================

 couldn't open hypfile: UDO couldn't open the printed file. If
     there's already existing a file like that remove file
     protection.

 couldn't open logfile: UDO couldn't open the printed file. If
     there's already existing a file like that remove file
     protection.

 couldn't open destinationfile: UDO couldn't open the printed file.
     If there's already existing a file like that remove file
     protection.

 couldn't open source file: UDO couldn't open the printed file. The
     file doesn't exist or UDO isn't allowed to open that file.

 couldn't open treefile: UDO couldn't open the printed file. If
     there's already existing a file like that remove file
     protection.

 couldn't read BMP header: UDO couldn't open the printed file or
     wasn't able to read the header of this graphic. The file doesn't
     exist or it isn't a Windows bitmap.

 couldn't read IMG header: UDO couldn't open the printed file or
     wasn't able to read the header of this graphic. The file doesn't
     exist or it isn't a GEM image.

 couldn't read MSP header: UDO couldn't open the printed file or
     wasn't able to read the header of this graphic. The file doesn't
     exist or it isn't a Microsoft Picture. If you are using
     Paintbrush graphics just ignore this message.

 couldn't read PCX header: UDO couldn't open the printed file or
     wasn't able to read the header of this graphic. The file doesn't
     exist or it isn't a Paintbrush graphic.

 couldn't write IMG header: UDO couldn't change the information of
     the GEM image header. Check the file name or remove file
     protection.

 couldn't open <file> pass 1: UDO couldn't open the file named <file>
     in the first pass. Check the file name.

 couldn't open <file> pass 2: UDO couldn't open the file named <file>
     in the second pass. Check the file name.

 memory allocation failed: UDO wasn't able to allocate needed memory.
     UDO keeps on converting the source file. So check the result
     espacially the output of tables.


C.2  Syntactical messages
=========================

Warnings and errors that are printed during the conversion of the
source file look like this:

    ! <file> <line>: <text>

To remove this message take a look at the file and the printed line
and try to find and correct the error. Start correcting the first
error because the following errors may be caused by earlier ones.

 `...' expected: UDO expected the printed command. Check the printed
     part of the source file or insert the printed command.

 `...' ignored outside preambel: You tried to use a command outside
     the main part that is only allowed inside the preamble. Move
     this command to a place before !begin_document.

 `...' inside preambel may cause trouble: You tried to use a command
     inside the preamble that is not allowed there. UDO notices the
     wrong use of this command but doesn't ignore it!

 `...' not active: You wanted to mark the end of a footnote or to
     switch off a text style that wasn't started or switched on
     before.

 `...' still active: You wanted to mark the start of a footnote or to
     switch on a text style but you are already inside a footnote or
     the text style is already switched on.

 `...' not available in this charset: You used a specific character
     inside your source file that isn't available inside the charset
     of the destination format.

 couldn't replace (!*link ...): UDO couldn't make a link to another
     position of the source file. This problem appears if too many
     links are uses inside a paragraph. Try to split up the paragraph
     into two parts.

 couldn't replace (!img ...): UDO couldn't print a command to include
     an image. This problem appears if too many images are uses
     inside a paragraph. Try to split up the paragraph into two
     parts.

 `!else' without `!if...': The !else command was used without !ifdest
     or !iflang.

 empty !define: You used the !define command with none or to less
     parameters. UDO ignores this command.

 empty !hyphen: You used the !hyphen command with no parameter. UDO
     ignores this command.

 empty !macro: You used the !macro command with none or to less
     parameters. UDO ignores this command.

 `!endif' without `!if...': The !endif command was used without
     !ifdest or !iflang.

 `!end_...' without `!begin_...': You wanted to finish an environment
     that hasn't been started yet.

 `!item' outside environment: The !item command was used outside an
     itemize, enumerate, description or xlist environment.

 link destination possibly undefined: The destination of the link may
     be is not existing. Check the link destination.

 missing parameter(s) at `...': You didn't use the right number of
     parameters.

 odd number off "": Your source file contains an odd number of double
     quotes.

 odd number off '': Your source file contains an odd number of double
     apostrophes.

 paragraph with short line: The printed line is too short so an ugly
     right margin will appear in your destination file. Try to insert
     syllabification marks or use the !hyphen command.

 too many columns used: You used too man columns inside a table.

 too many defines defined: You used too many !define commands inside
     your source file.

 too many environments used: You reached the maximum depth of envi-
     ronments. Try to use less environments.

 too many hyphens defined: You used too many !hyphen commands inside
     your source file.

 too many macros defined: You used too many !macros commands inside
     your source file.

 too many rows used: You used too man rows inside a table.

 unexpected end of line in command: This message appears when you
     have forgotten to mark the end of a placeholder or if a command
     isn't part of one source line.

 unknown command: The printed command is unknown to UDO. If you try
     to display a word that begin with a `!' you have to insert a
     slash (e.g `!/word').

 wrong number of parameters: You used the wrong number of parameters
     inside a command or placeholder.



Appendix D

Additional information
**********************


D.1  Facts
==========

Keep in mind these maximums:


                    +---------------------+------+
                    | !macro's            |   64 |
                    | !define's           |   64 |
                    | !hyphen's           |  512 |
                    +---------------------+------+
                    | Chapters            | 1024 |
                    | Labels              | 1024 |
                    +---------------------+------+
                    | Chars per line      |  512 |
                    | Chars per word      |  128 |
                    | Syllables per word  |   32 |
                    | Words per paragraph |  800 |
                    | Links per paragraph |  200 |
                    +---------------------+------+
                    | Table rows          |  128 |
                    | Table columns       |   32 |
                    +---------------------+------+
                    | Environment depth   |    6 |
                    +---------------------+------+



The facts shall demonstrate how much work it has been to develop UDO
and this documentation:


          +-----------------------------------+------------+
          | Kind                              |  Size/Time |
          +-----------------------------------+------------+
          | Size of the source code           | ca. 500 KB |
          | Size of the German documentation  | ca. 300 KB |
          | Size of the English documentation | ca. 240 KB |
          +-----------------------------------+------------+



D.2  Developing environment
===========================

I used the following software to develop UDO:

 Amiga:     Something's still missing here...

 Atari:     Pure-C 1.1, MiNT-Libs PL 46, SysGem 2.03 ß, Interface
            2.3, Programming Tools by Julian F. Reschke

 DOS:       EMX-GCC 2.6.3 emxfix06, Joe Allan's Own Editor `Joe' for
            MS-DOS

 HP-UX:     GCC 2.7.2

 Linux:     GCC 2.6.3

 Macintosh: Something's still missing here...

At the moment the main development of UDO is done on my Compaq
Contura notebook (yes, it works!). I use Joe fo writing the source
code. To make the other versions of UDO I still have to copy the
source code to the destination computer and start a "Make All".
That's all.



The following software has been used to write this documentation:

   ∙ Joe Allan's Own Editor `Joe' for MS-DOS
   ∙ Allan Phillips' Programmer's File Editor `PFE' 0.06.01
   ∙ Phoenix for Windows by Application Systems Heidelberg
   ∙ Everest by Oliver Schmidt

DOS-, Windows- and Atari users are recommended to take a look at
these programs.


D.3  Saved files
================

In this list you will see the sense of each file UDO or additional
programs saves:

 .asc: ASCII
 .1:   Manualpage
 .cmd: Command file for Pure-C's hypertext compiler
 .hpj: Prohect file for Windows' helpcompiler
 .htm: HTML
 .rtf: RTF or Windows Help source file
 .scr: Pure C Help soure file
 .stg: ST-Guide source file
 .txt: Turbo Vision Help source file
 .tex: LaTeX or Texinfo source file
 .uha: file with hyphenations for ASCII
 .uhp: the same for Pure C Help
 .uhs: the same for ST-Guide
 .uh1: the same for manualpages
 .ula: logfile of the ASCII conversion
 .ulh: logfile of the HTML conversion
 .uli: logfile of the Texinfo conversion
 .ulp: logfile of the Pure C Help conversion
 .ulr: logfile of the RTF conversion
 .uls: logfile of the ST-Guide conversion
 .ult: logfile of the TeX conversion
 .ulv: logfile of the Turbo Vision Help conversion
 .ulw: logfile of the Windows Help conversion
 .ul1: logfile of the manualpage conversion
 .uta: treefile of the ASCII conversion
 .uth: treefile of the HTML conversion
 .uti: treefile of the Texinfo conversion
 .utp: treefile of the Pure C Help conversion
 .utr: treefile of the RTF conversion
 .uts: treefile of the ST-Guide conversion
 .utt: treefile of the TeX conversion
 .utv: treefile of the Turbo Vision Help conversion
 .utw: treefile of the Windows Help conversion
 .ut1: treefile of the manualpage conversion

The following files you will see when you go on converting the files
generated by UDO with external programs (see brackets):

 .err: logfile of the Windows Help compiler (HC.EXE)
 .h:   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 references file (HCP.TTP)



Appendix E

History
*******

In this chapter you will find a short description of the changes of
each release.


E.1  Last minute changes
========================

These are the changes I made right before publishing this release.
These changes may be missing in the rest of this documentation.


   ∙ I completely chanded the tables that are used for converting a
     character set into another. May be I inserted some mistakes.

   ∙ A new switch enables you to use predefined placeholdes for
     system wide exchange of source files. This switch is named
     !universal_charset [ on | off ].

     If you switch on this "universal charset" you can use the
     following plaveholders (ph):


             +-------+----------------+-----------------+
             | ph    | x from         | example         |
             | (!"x) | aeiosuyAEIOU   | (!"a) = ä   |
             | (!'x) | aeiouyAEIOUY   | (!'e) = é   |
             | (!`x) | aeiouAEIOU     | (!`i) = ì   |
             | (!^x) | aeiouAEIOU     | (!^o) = ô   |
             | (!&x) | ae, oe, AE, OE | (!&AE) = Æ |
             | (! x) | anoANO         | (! n) = (~n)    |
             | (!,x) | cC             | (!,C) = Ç   |
             | (!.x) | aA             | (!.A) = Å   |
             | (!_x) | ao             | (!_a) = ª   |
             | (!\x) | oO             | (!\O) = O   |
             +-------+----------------+-----------------+


     The German `₧' is produced by (!"s).

     If a destination format doesn't have a character inside its
     charset UDO uses the most similar character e.g. `a' instead of
     `â'.

     In the future you will be able to insert further characters like
     characters from the Greek charset.


E.2  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 Frensh 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
          evironment
        ∙ !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 ouput
          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.
        ∙ Paintbruch 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

 Bugfixes:
     Unnumerous. ;-)


E.3  Release 4
==============

This was the first English version with an English documentation!


E.4  Release 3
==============

I think that nobody is interested in those things that changed a year
ago.



Appendix F

Command index
*************

In this appendix you will find a short description of nearly every
command in alphabetical order. Each command is descriped in the
following way:

 Type & position:
     The type of a command and the position where you can use it.

     A command starts a specific action, a switch says UDO how to
     handle different things, a placeholder will be simply replaced
     by other text.

     If you read "preamble" you only are allowed to use a command
     before !begin_document, "main part" means that you are only
     allowed to use the commands after !begin_document. If "preamble
     & main part" is displayed you can use the command inside or
     outside the preamble.

 Syntax:
     You will see how to use this command. "<text>" means one or more
     words, "<file>" means the name of a file, "<value>" means a
     numerical value, "<char>" means a single character "<abbrevia-
     tions>" means one or more of the abbreviations of a destination
     format (asc=ASCII, html=HTML, info=Texinfo, ldoc=Linuxdoc-SGML,
     man=Manualpage, pch=Pure-C-Help, rtf=RTF, stg=ST-Guide,
     tex=LaTeX, tvh=Turbo-Vision-Help, win=WinHelp)

 Example:
     You will perhaps find a short example here

 See also:
     Take a look at the listed commands or chapters that contain
     additional information.


F.1  A...
=========


F.1.1  !=asc
------------

 Type & position: command, preamble & main part

 Syntax:          !=asc <text>

 Description:     "<text>" is only given out if you don't convert
                  into ASCII. "<text>" will be not converted!

 See:             !asc, !ifdest, raw environment


F.1.2  !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.

 See:             !node, !subnode, !subsubnode


F.1.3  !asc
-----------

 Type & position: command, preamble & main part

 Syntax:          !asc <text>

 Description:     "<text>" is only given out if you convert into
                  ASCII. "<text>" will be not converted!

 See:             !=asc, !ifdest, raw environment


F.1.4  !author
--------------

 Type & position: command, preamble

 Syntax:          !author <text>

 Description:     "<text>" will be used as the name of the author on
                  the titlepage.

 Example:         !author Dirk Hagedorn

 See:             !maketitle, Title page


F.1.5  !authorimage
-------------------

 Type & position: command, preamble

 Syntax:          !authorimage <file>

 Description:     "<file>" will be displayed above the name of the
                  author on the titlepage if the destination format
                  supports images.

 Example:         !authorimage dh

 See:             !maketitle, !author, Title page, Images


F.1.6  !autoref
---------------

 Type & position: switch, main part

 Syntax:          !autoref [ on | off ]

 Description:     Switches on or off automatic references. For the
                  ST-Guide UDO prints @autorefon or @autorefoff.

 Example:         !autoref [off]


F.1.7  (!alpha)
---------------

 Type & position: placeholder, preamble & main part

 Syntax:          (!alpha)

 Description:     This placeholder will be replaced by an α.

 See:             (!beta), Special chars


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.

 See:             !end_appendix, Appendix


F.2.2  !begin_description
-------------------------

 Type & position: command, main part

 Syntax:          !begin_description

 Description:     Starts a new description environment that has to be
                  finished with !end_description.

 See:             !end_description, !item [], Descriptions


F.2.3  !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.4  !begin_enumerate
-----------------------

 Type & position: command, main part

 Syntax:          !begin_enumerate

 Description:     Starts a new enumerate environment that has to be
                  finished with !end_enumerate.

 See:             !end_enumerate, !item, Enumerations


F.2.5  !begin_itemize
---------------------

 Type & position: command, main part

 Syntax:          !begin_itemize

 Description:     Starts a new itemize environment that has to be
                  finished with !end_itemize.

 See:             !end_itemize, !item


F.2.6  !begin_quote
-------------------

 Type & position: command, main part

 Syntax:          !begin_quote

 Description:     This command starts a new quote environment. Text
                  is printend indented until UDO read the !end_quote
                  command.

 See:             !end_quote


F.2.7  !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 environmant
                  will be output directly without any conversion.

 See:             !end_raw, raw environment, !rinclude


F.2.8  !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:             Tables


F.2.9  !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.

 See:             !end_verbatim, Preformatted text, !vinclude


F.2.10  !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.

 See:             !end_xlist, !item [], Lists


F.2.11  !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.12  !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.


F.2.13  (!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.14  (!beta)
---------------

 Type & position: placeholder, preamble & main part

 Syntax:          (!beta)

 Description:     This placeholder will be replaced by ß.

 See:             (!alpha), Special chars


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.

 See:             Images, !use_chapter_images


F.3.2  !code_ansi
-----------------

 Type & position: switch, preamble & main part

 Syntax:          !code_ansi

 Description:     UDO expects ANSI-umlauts after this command. You
                  can switch back to ASCII with !code_ascii.

 See:             !code_ascii


F.3.3  !code_ascii
------------------

 Type & position: switch, preamble & main part

 Syntax:          !code_ascii

 Description:     UDO expects ASCII-umlauts after this command. This
                  is the default setting.

 See:             !code_ansi


F.4  D...
=========


F.4.1  !date
------------

 Type & position: command, preamble

 Syntax:          !date <text>

 Description:     "<text>" will be displayed on the titlepage below
                  the contents of !version.

 Example:         !date April 20, 1996

 See:             !maketitle, (!today) (!short_today), Title page


F.4.2  !define
--------------

 Type & position: command, preamble

 Syntax:          !define <word> <text>

 Description:     Defines a definition. Later on every "(!<word>)"
                  will be replaced 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.

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

 See:             !ifdest, !iflang, !endif


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.

 Example:         !email Internet: [e-mail]

 See:             !maketitle, Title page


F.5.3  !end_appendix
--------------------

 Type & position: command, main part

 Syntax:          !end_appendix

 Description:     Finishes the appendix.

 See:             !begin_appendix, Appendix


F.5.4  !end_description
-----------------------

 Type & position: command, main part

 Syntax:          !end_description

 Description:     Finishes the last descripion environment.

 See:             !begin_description, !item []


F.5.5  !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.

 See:             !begin_document


F.5.6  !end_enumerate
---------------------

 Type & position: command, main part

 Syntax:          !end_enumerate

 Description:     Finishes the latest enumerate environment.

 See:             !begin_enumerate, !item


F.5.7  !end_itemize
-------------------

 Type & position: command, main part

 Syntax:          !end_itemize

 Description:     Finsihes the latest itemize environment.

 See:             !begin_itemize, !item


F.5.8  !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


F.5.9  !end_raw
---------------

 Type & position: command, preamble & main part

 Syntax:          !end_raw

 Description:     Finsihes the raw environment.

 See:             !begin_raw, raw environment


F.5.10  !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.11  !end_verbatim
---------------------

 Type & position: command, main part

 Syntax:          !end_verbatim

 Description:     Finishes the verbatim environment.

 See:             !begin_verbatim, Preformatted text


F.5.12  !end_xlist
------------------

 Type & position: command, main part

 Syntax:          !end_xlist

 Description:     Finsihes the latest xlist environment.

 See:             !begin_xlist, !item [], Lists


F.5.13  !endif
--------------

 Type & position: command, preamble & main part

 Syntax:          !endif

 Description:     Finishes a special command that was started with
                  !ifdest.

 See:             !ifdest, !else


F.5.14  !english
----------------

 Type & position: switch, preamble

 Syntax:          !english

 Description:     Tells UDO to use English words inside the desti-
                  nation file e.g. "Appendix" instead of "Anhang".

 See:             !german, !french, !iflang


F.6  F...
=========


F.6.1  !french
--------------

 Type & position: switch, preamble

 Syntax:          !german

 Description:     Tells UDO to use French words inside the destina-
                  tion file e.g. "Table des matières" instead of
                  "Contents". German words are default, so you have
                  to place !french inside the preamble to get French
                  words.

 See:             !german, !english, !iflang


F.6.2  !fussy
-------------

 Type & position: switch, main part

 Syntax:          !fussy

 Description:     Switches on warning messages according to short
                  lines.

 See:             !sloppy


F.6.3  (!F)...(!f)
------------------

 Type & position: placeholder, preamble & main part

 Syntax:          (!B)<text>(!b)

 Description:     "<text>" will be displayed in a box only in LaTeX.
                  (!F)...(!f) will be replaced by \fbox{...}.

 Example:         (!F)Living in a box(!f)

 See:             Emphasizing text


F.6.4  (!file)
--------------

 Type & position: placeholder, preamble & main part

 Syntax:          (!file)

 Description:     This placeholder will be replaced by the current
                  filename.


F.7  G...
=========


F.7.1  !german
--------------

 Type & position: switch, preamble

 Syntax:          !german

 Description:     Tells UDO to use German words inside the destina-
                  tion file e.g. "Anhang" instead of "Appendix".
                  German words are default, so you have to place
                  !english inside the preamble to get English words.

 See:             !english, !french, !iflang


F.7.2  (!G)...(!g)
------------------

 Type & position: placeholder, preamble & main part

 Syntax:          (!G)<text>(!g)

 Description:     "<text>" will be displayed in ghosted text if
                  possible.

 Example:         (!G)ghosted(!g)

 See:             Emphasizing text


F.7.3  (!grin)
--------------

 Type & position: placeholder, preamble & main part

 Syntax:          (!grin)

 Description:     (!grin) will be replaced by a grinning emoticon
                  displayed in typewriter.

 Example:         (!grin) will be ;-)

 See:             (!laugh)


F.8  H...
=========


F.8.1  !=html
-------------

 Type & position: command, preamble & main part

 Syntax:          !=html <text>

 Description:     "<text>" is only given out if you don't convert
                  into HTML. "<text>" will be not converted!

 See:             !html, !ifdest, raw environment


F.8.2  !hline
-------------

 Type & position: command, main part

 Syntax:          !hline

 Description:     This command displays a horizontal line inside
                  normal text or inside a table.

 See:             Tables


F.8.3  !html
------------

 Type & position: command, preamble & main part

 Syntax:          !html <text>

 Description:     "<text>" is only given out if you convert into
                  HTML. "<text>" will be not converted!

 See:             !=html, !ifdest, raw environment


F.8.4  !html_merge_nodes
------------------------

 Type & position: switch, preamble

 Syntax:          !html_merge_nodes

 Description:     If you use this switch inside the preamble all
                  chapters, sections and subsection are written into
                  one file.

 See:             !html_merge_subnodes, !html_merge_subsubnodes


F.8.5  !html_merge_subnodes
---------------------------

 Type & position: switch, preamble

 Syntax:          !html_merge_subnodes

 Description:     If you use this switch inside the preamble all
                  sections are written into the same file in that you
                  can read the contents of the chapter.

 See:             !html_merge_nodes, !html_merge_subsubnodes


F.8.6  !html_merge_subsubnodes
------------------------------

 Type & position: switch, preamble

 Syntax:          !html_merge_subsubnodes

 Description:     If you use this switch inside the preamble all
                  subsections are written into the same file in that
                  you can read the contents of the section.

 See:             !html_merge_nodes, !html_merge_subnodes


F.8.7  !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 de-
                  scription 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.8  !htmlname
----------------

 Type & position: command, main part

 Syntax:          !htmlname <file>

 Description:     If you use this command inside a chapter, section
                  or subsection "<file>" is used as the name of the
                  HTML file instead of C_CCSSUU (CC chapter, SS
                  section, UU subsection).

 Example:         !htmlname software


F.8.9  !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>" is only given out if you don't convert
                  into Texinfo "<text>" will be not converted!

 See:             !info, !ifdest, raw environment


F.9.2  !ifdest
--------------

 Type & position: command, preamble & main part

 Syntax:          !ifdest [<abbreviations>]

 Description:     This command starts a special environment. All
                  lines inside this environment will be converted
                  until !else or !endif appears. The following
                  example shows how to use it with the ST-Guide or
                  WinHelp format.

 Example:         !ifdest [stg,win]

 See:             !else, !endif


F.9.3  !iflang
--------------

 Type & position: command, preamble & main part

 Syntax:          !iflang [ german | english | french ]

 Description:     This command starts a lingual environment. The
                  example shows how to add text that is only
                  converted if you convert a French source file.

 Example:         !iflang [french]

 See:             !ifdest, !english, !french, !german


F.9.4  !image
-------------

 Type & position: command, main part

 Syntax:          !image <file>

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

 Example:         !image tiger

 See:             !no_images, (!image ...), Images


F.9.5  !include
---------------

 Type & position: command, preamble & main part

 Syntax:          !include <file>

 Description:     Opens the file named "file" and converts its
                  contents.

 See:             !vinclude, !rinclude, Split documents


F.9.6  !index
-------------

 Type & position: command, main part

 Syntax:          !index <text>

 Description:     <text> will pe printed as \index {...} for LaTeX,
                  K{\footnote K ...} for WinHelp 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


F.9.7  !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.8  !item
------------

 Type & position: command, main part

 Syntax:          !item <text>

 Description:     Starts a new item of an itemize or enumerate envi-
                  ronment.

 See:             !item [], Itemizations, Enumerations


F.9.9  !item []
---------------

 Type & position: command, main part

 Syntax:          !item [<text>]

 Description:     Starts a new item of a description or an xlist en-
                  vironment. "<text>" will be displayed in bold text
                  inside a description environment.

 See:             !item, Descriptions, Lists


F.9.10  (!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.11  (!idx ...)
------------------

 Type & position: placeholder, main part

 Syntax:          (!idx [<text>] {[<index1>]} {[<index2>]}
                  {[<index3>]} )

 Description:     Useful for adding indices right inside the source
                  file. Indices are currently only converted to
                  LaTeX.

 See:             Indices


F.9.12  (!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.13  (!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>" is only given out 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.

 See:             Labels


F.10.3  !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.4  !list_parsep
--------------------

 Type & position: command, preamble & main part

 Syntax:          !list_parsep [ on | off ]

 Description:     !list_parsep [off] disables the output of empty
                  lines between items of the next itemize, enumerate,
                  description or xlist-environment.
                  !list_parsep [on] enables it and is the default
                  setting.


F.10.5  (!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.6  (!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.7  (!laugh)
----------------

 Type & position: placeholder, preamble & main part

 Syntax:          (!laugh)

 Description:     (!laugh) will be replaced by a laughing emoticon
                  displayed in typewriter.

 Example:         (!laugh) will be :-)

 See:             (!grin)


F.10.8  (!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.

 See:             (!xlink ...), (!plink ...), Links


F.11  M...
==========


F.11.1  !=man
-------------

 Type & position: command, preamble

 Syntax:          !=man <text>

 Description:     "<text>" is only given out 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, !program, !programimage, !version, !date,
                  !author, !authorimage, !street, !title, !email,
                  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 [<abbreviation>]

 Description:     Tells UDO not to generate bottomlines. In the
                  example this is done for the Pure C Help format.

 Example:         !no_bottomlines [pch]


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]


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_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.7  !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.8  !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 chars


F.12.9  !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.10  !node
--------------

 Type & position: command, main part

 Syntax:          !node <text>

 Description:     Starts a new chapter named "<text>".

 Example:         !node Command reference

 See:             !pnode, !subnode, !subsubnode, Structuring


F.12.11  !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.

 See:             !node, !pnode*, Structuring


F.12.12  (!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:         (!N)a footnote(!n)

 See:             Footnotes


F.12.13  (!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!


F.13  O...
==========


F.13.1  (!O)...(!o)
-------------------

 Type & position: placeholder, preamble & main part

 Syntax:          (!O)<text>(!o)

 Description:     "<text>" will be displayed in outlined text if
                  possible.

 Example:         (!O)outlined(!o)

 See:             Emphasizing text


F.14  P...
==========


F.14.1  !=pch
-------------

 Type & position: command, preamble & main part

 Syntax:          !=pch <text>

 Description:     "<text>" is only given out if you don't convert
                  into Pure C Help. "<text>" will be not converted!

 See:             !pch, !ifdest, raw environment


F.14.2  !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.3  !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.

 See:             !psubnode, !psubsubnode


F.14.4  !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.

 See:             !pnode, !node*, Structuring


F.14.5  !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.6  !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.7  !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.

 See:             !pnode, !psubsubnode


F.14.8  !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.

 See:             !psubnode, !subnode*, Structuring


F.14.9  !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.

 See:             !pnode, !psubnode


F.14.10  !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.

 See:             !psubsubnode, !subsubnode*, Structuring


F.14.11  (!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.

 See:             (!link ...), (!xlink ...), Links


F.15  R...
==========


F.15.1  !=rtf
-------------

 Type & position: command, preamble & main part

 Syntax:          !=rtf <text>

 Description:     "<text>" is only given out 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.

 See:             !include, !vinclude, Split documents, raw envi-
                  ronment


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_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.5  !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>" is only given out if you don't convert
                  into ST-Guide. "<text>" will be not converted!

 See:             !stg, !ifdest, raw environment


F.16.2  !sloppy
---------------

 Type & position: switch, main part

 Syntax:          !sloppy

 Description:     Switches off warning messages according short
                  lines.

 See:             !fussy


F.16.3  !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.4  !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.5  !stg_no_database
------------------------

 Type & position: switch, preamble

 Syntax:          !stg_no_database

 Description:     Switches off the output of the ST-Guide @database
                  line.


F.16.6  !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 In der Esmecke 9

 See:             !maketitle, Title page


F.16.7  !subnode
----------------

 Type & position: command, main part

 Syntax:          !subnode <text>

 Description:     Starts a new section named "<text>".

 See:             !node, !subsubnode, Structuring


F.16.8  !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.

 See:             !subnode, !psubnode*, Structuring


F.16.9  !subsubnode
-------------------

 Type & position: command, main part

 Syntax:          !subsubnode <text>

 Description:     Starts a new subsection named "<text>".

 See:             !node, !subnode, Structuring


F.16.10  !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.

 See:             !subsubnode, !psubsubnode*, Structuring


F.16.11  !subsubtoc
-------------------

 Type & position: command, main part

 Syntax:          !subsubtoc

 Description:     Lists all subsections of a section.

 See:             !tableofcontents, !toc, !subtoc,
                  !use_auto_subsubtocs, Tables of contents


F.16.12  !subtoc
----------------

 Type & position: command, main part

 Syntax:          !subtoc

 Description:     Lists all sections of a chapter.

 See:             !tableofcontents, !toc, !subsubtoc,
                  !use_auto_subtocs, Tables of contents


F.16.13  (!S)...(!s)
--------------------

 Type & position: placeholder, preamble & main part

 Syntax:          (!S)<text>(!s)

 Description:     "<text>" will be displayed shadowed if possible.

 Example:         (!S)shadowed(!s)

 See:             Emphasizing text


F.16.14  (!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) will be 1996/04/20

 See:             !german, !english, (!today)


F.17  T...
==========


F.17.1  !=tex
-------------

 Type & position: command, preamble & main part

 Syntax:          !=tex <text>

 Description:     "<text>" is only given out if you don't convert
                  into LaTeX. "<text>" will be not converted!

 See:             !tex, !ifdest, raw environment


F.17.2  !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.3  !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 \documentstyle[11pt]{article}

 See:             !=tex, raw environment


F.17.4  !tex_2e
---------------

 Type & position: switch, preamble

 Syntax:          !tex_2e

 Description:     UDO will output special LaTeX2ee commands if you
                  use this command e.g. \textbf{...} instead of {\bf
                  ...}


F.17.5  !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.6  !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.7  !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.8  !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.9  !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.10  !title
---------------

 Type & position: command, preamble

 Syntax:          !title <text>

 Description:     "<text>" will be displayed on the titlepage before
                  the contents of !program.

 Example:         !title The guide to

 See:             !maketitle, Title page


F.17.11  !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.12  !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. This switch has no
                  effect to chapters of the appendix.

 Example:         !toc_offset 9


F.17.13  !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.14  (!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.15  (!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.16  (!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) will be April 20, 1996

 See:             !german, !english, (!short_today)


F.18  U...
==========


F.18.1  !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.2  !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.3  !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, Tables of contents


F.18.4  !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, Tables of contents


F.18.5  !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.6  !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.7  !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.8  !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.9  (!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  !verbatim_no_umlaute
----------------------------

 Type & position: switch, preamble

 Syntax:          !verbatim_no_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:         !verbatim_no_umlaute [tex]

 See:             !begin_verbatim, !end_verbatim, Preformatted text


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 5

 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.

 See:             !include, Split documents, verbatim environment


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>" is only given out 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
                  WinHelp. "<text>" will be not converted!

 See:             !=win, raw environment


F.20.3  !win_html_look
----------------------

 Type & position: switch, preamble

 Syntax:          !win_html_look

 Description:     If you use this switch inside the preamble of your
                  source files the Windows Help will use a grey
                  background and Times New Roman instead of a white
                  background and Arial for displaying the text.


F.20.4  !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 "Arial".

 Example:         !win_propfont Times New Roman

 See:             !win_html_look


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

 Example:         (!xlink [Playboy] [http://www.playboy.com])

 See:             (!link ...), (!plink ...), !no_xlinks, Links



Appendix

UDO5
****

                     This text was generated by

                                 UDO

                              Release 5
                          Version 0.48 TOS

                     Copyright (c) 1995, 1996 by
                            Dirk Hagedorn
                          In der Esmecke 9
                            59846 Sundern
                               Germany
                     MausNet: Dirk Hagedorn@MK2
                  America Online: [e-mail]

    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 and Turbo-Vision-Help.

    Further information and the current versions can be found at
           http://members.aol.com/DirkHage/www/eng/udo.htm