############################################################
# @(#) Structuring, Dirk Hagedorn, 1996/04/16
############################################################

!subnode Structuring

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

#-----------------------------------------------------------

!subsubnode Title page

!index !/maketitle
Using the command (!I)!/maketitle(!i) you can tell UDO to generate a title
page built with information you set in the preamble with the following
commands:

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

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

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

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

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

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

#-----------------------------------------------------------

!subsubnode Tables of contents

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

You should use (!I)!/tableofcontents(!i) directly after (!I)!/maketitle(!i)
or (!I)!/begin_document(!i) to avoid problems.

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

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

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

!subsubheading Summary of all commands and switches

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

(!HINTS)

!begin_enumerate

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

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

!end_enumerate

#-----------------------------------------------------------

!subsubnode Chapters, sections, subsections and paragraphs

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

!index !/node
!index !/subnode
!index !/subsubnode
!index !/subsubsubnode

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

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

!begin_quote
!begin_verbatim
!node          A chapter
!subnode       A section
!subsubnode    A subsection
!subsubsubnode A paragraph
!node          And a different chapter
!end_verbatim
!end_quote

The table of contents should look like this:

!begin_quote
!begin_verbatim
1  A chapter
   1.1  A section
        1.1.1  A subsection
               1.1.1.1  A Paragraph

2  And a different chapter
!end_verbatim
!end_quote

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

!index !/pnode
!index !/psubnode
!index !/psubsubnode
!index !/psubsubsubnode

!begin_itemize !short
!item (!I)!/pnode(!i) for popup chapters,
!item (!I)!/psubnode(!i) for popup sections,
!item (!I)!/psubsubnode(!i) for popup subsections and
!item (!I)!/psubsubsubnode(!i) for popup paragraphs
!end_itemize

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

!index !/node*
!index !/subnode*
!index !/subsubnode*
!index !/subsubsubnode*
!index !/pnode*
!index !/psubnode*
!index !/psubsubnode*
!index !/psubsubsubnode*

!begin_itemize !short
!item (!I)!/node*(!i) for chapters,
!item (!I)!/subnode*(!i) for sections,
!item (!I)!/subsubnode*(!i) for subsections,
!item (!I)!/subsubsubnode*(!i) for paragraphs
!item (!I)!/pnode*(!i) for popup chapters,
!item (!I)!/psubnode*(!i) for popup sections,
!item (!I)!/psubsubnode*(!i) for popup subsections and
!item (!I)!/psubsubsubnode*(!i) for popup paragraphs.
!end_itemize


(!HINTS)

!begin_enumerate

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

!index !/no_numbers
!item UDO enumerates the chapters automatically. If you want to display the
chapter names without numbers you can use the switch (!I)!/no_numbers(!i)
inside the preamble.

!end_enumerate

#-----------------------------------------------------------

!subsubnode Appendix

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

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

!begin_quote
!begin_verbatim
!node  A chapter outside the appendix
!begin_appendix
!node           A chapter
!subnode        A section
!subsubnode     A subsection
!subsubsubnode  A paragraph
!end_appendix
!end_verbatim
!end_quote

The table of contents should look like this:

!begin_quote
!begin_verbatim
5  A chapter outside the appendix

Appendix

A  A chapter
   A.1  A section
        A.1.1  A subsection
               A.1.1.1  A paragraph
!end_verbatim
!end_quote


(!HINTS)

!begin_enumerate

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

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

!end_enumerate
