Home The syntax of UDO Structuring Special characters

Emphasising text

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


Itemizations

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

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

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

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

      This is the second paragraph of the
      second item of the itemize environment.
!item This is the last item.
!end_itemize

... will be printed this way:

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

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

... will be printed this way:


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

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

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

Without !short...

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

... will be displayed this way:

With !short...

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

... will be displayed this way:

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


Please note:

  1. The items of the first itemize environment will be marked with a bullet that is defined on different positions inside the character set of each operating system.
     
  2. If you use the switch !no_umlaute inside the preamble of the source file the items of the first itemize environment will be marked with an `o' instead of a bullet.
     

Enumerations

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

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

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

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

... will be displayed this way:

UDO offers you the following environments:

  1. itemize environment
     
  2. enumerate environment (discussed in this section)
     
  3. description environment
     
  4. xlist environment
     

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

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

... becomes to:

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

Please note:

  1. UDO doesn't enumerate the items for all destination formats. E.g. HTML and LaTeX enumerate the items themselves so you have to be cautious with using text like "see item 1" or "see point b)".
     
  2. The third layer of enumerate environments will be indented deeper than the other layers because Roman numbers need a little bit more space.
     
  3. Because the second layer is enumerated with letters you shouldn't use more than 26 items.
     
  4. A description of the !short command is part of the chapter "Itemizations".
     

Descriptions

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

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

The description environment can be used inside other (description) 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

... will be display this way:

UDO offers you the following environments:

the itemize environment
for simple lists,
 
the enumerate environment
for enumerated lists,
 
the description environment
for descriptions and
 
the xlist environment
for lists
 

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

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

... becomes to:

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

Please note:

  1. If the word that shall be displayed in bold text contains a "]" you have to quote it with an exclamation mark to tell UDO that it has to be printed in bold text, too.
     
  2. The HTML version of your source file will print the descriptions in bold text, too, even if this not typical for HTML. The next versions of UDO will offer a command to disable the bold text inside descriptions for HTML.
     
  3. A description of the !short command is part of the chapter "Itemizations".
     

Lists

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

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

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

This short example...

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

... will be displayed this way:

UDO offers you the following environments:

itemize environment: for itemizations
 
enumerate environment: for enumerations
 
description environment: for descriptions
 
xlist environment: for lists (discussed in this section)
 

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

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

... will be displayed this way:

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

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

  1. When using the blist environment (bold list) the items will be displayed in bold text. A blist environment will be started with !begin_blist and finished with !end_blist.
     
  2. When using the ilist environment (italic list) the items will be displayed in italic text. A blist environment will be started with !begin_ilist and finished with !end_ilist.
     
  3. When using the tlist environment (typewritered list) the items will be displayed in typewritered text. A tlist environment will be started with !begin_tlist and finished with !end_tlist.
     

The following example shall demonstrate the results:

!begin_xlist [typewritered:]
!item [normal:] !..
!end_xlist

!begin_blist [typewritered:]
!item [bold:] !..
!end_blist

!begin_ilist [typewritered:]
!item [italic:] !..
!end_ilist

!begin_tlist [typewritered:]
!item [typewritered:] !..
!end_tlist

... will be displayed this way:

normal: ...
 
bold: ...
 
italic: ...
 
typewritered: ...
 

You have to notice some aspects:

  1. If the text inside the brackets contains a "]" you have to quote it with an exclamation mark so that UDO will recognize that this "]" shall be part of the item and shall be displayed on the "left side".
     
  2. HTML, Linuxdoc-SGML and Texinfo don't support an environment like UDO's xlist environment. In these formats the xlist environments are displayed like a description environment by default. But if you use the switch !use_xlist inside the preamble UDO will print xlist environments like in ASCII, but with preformatted text.
     
  3. UDO doesn't know the character widths when converting the source file to RTF and Windows Help. If the indents are too wide you can adjust the indent by using the commands !rtf_charwidth and !win_charwidth.
     
  4. A description of the !short command is part of the chapter "Itemizations".
     

Centred text

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

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

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

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

!begin_center
A centred line.

A centred paragraph
with two source lines.

The Guide to (!nl)
UDO
!end_center

... will be printed in this way:

A centred line.
A centred paragraph with two source lines.
The Guide to
UDO

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

Right justified text

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

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

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

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

!begin_flushright
A right justified line.

A right justified paragraph
with two source lines.

The Guide to (!nl)
UDO
!end_flushright

... will be printed in this way:

A right justified line.
A right justified paragraph with two source lines.
The Guide to
UDO

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

Left justified text

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

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

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

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

This short example...

!begin_flushleft
A left justified line.

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

The Guide to (!nl)
UDO
!end_flushleft

... will be printed in this way:

A left justified line.

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

The Guide to
UDO

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

Indented paragraphs

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

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

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

... becomes to:

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

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

Preformatted text

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

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

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

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


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

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

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


Please note:

  1. Because the text of a verbatim environment is indented like normal text you shouldn't use extra spaces at the beginning of each line.
     
  2. The difference between the raw environment and the verbatim environment is that text of a verbatim environment will be displayed an you entered it, but text of a raw environment will be saved into the destination file as you entered it.
     

Footnotes

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

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

This example...

UDO(!N)Universal Document(!n)

... becomes to:

UDO (Universal Document)

Footnotes are supported by these formats:

Please note:

  1. I'm a bit unlucky that UDO just prints brackets if the destination format doesn't support footnotes. It will be better if UDO saves the footnote text and prints it at the end of a chapter or page. Unfortunately this is a very tricky problem that cannot be solved in some days.
     
  2. Don't forget not to use a space or tab before (!N).
     

Text styles

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

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

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

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

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

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

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

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

!ifdest [stg]
    !define G @{G}
    !define g @{g}
!else
    !define G
    !define g
!endif

Normal and (!G)ghosted(!g).

Tables

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

To print tables with UDO you need the following commands:

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

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

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

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

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

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

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

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

Table 2: Tables with UDO
upper left up upper right
lower left cell lower cell lower right cell

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


The following example shows the upper table without any lines:

Table 3: Another example
upper left up upper right
lower left cell lower cell lower right cell

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


Please note:


Home The syntax of UDO Structuring Special characters