Home The syntax of UDO Basics Emphasising text

Structuring

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


Title page

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

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

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

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

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

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

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

Tables of contents

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

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

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

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

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

Summary of all commands and switches

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

Please note:

  1. When converting to HTML the title page and the table of contents will be printed in the file you passed via the command line.
     
  2. When converting to RTF no table of contents will be generated! You should make this with the functions of your text processor that is used to import the converted RTF file.
     

Chapters, sections, subsections and paragraphs

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

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

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

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

The table of contents should look like this:

1  A chapter
   1.1  A section
        1.1.1  A subsection
               1.1.1.1  A Paragraph

2  And a different chapter

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

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

Please note:

  1. Chapters that aren't listed in the table of contents aren't numbered, too. UDO will create hypertext links to them as it does for all other chapters.
     
  2. UDO enumerates the chapters automatically. If you want to display the chapter names without numbers you can use the switch !no_numbers inside the preamble.
     

Appendix

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

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

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

The table of contents should look like this:

5  A chapter outside the appendix

Appendix

A  A chapter
   A.1  A section
        A.1.1  A subsection
               A.1.1.1  A paragraph

Please note:

  1. You should use the appendix at the end of your source file. In other words !end_appendix should be the last but one command before !end_document. You shouldn't use any additional chapters behind !end_appendix because UDO will get confused especially while enumerating the chapters.
     
  2. Because UDO uses letters for creating the numbers for the chapters of the appendix you shouldn't use more than 26 chapters inside the appendix.
     

Home The syntax of UDO Basics Emphasising text