Home Tips & tricks Seven rules for writing UDO source files Tips & tricks according to LaTeX

General tips & tricks


Split large documentations

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

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

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

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

[main.u]
!include header.ui
!begin_document
!maketitle
!tableofcontents
!include chapter1.ui
!include chapter2.ui
!include chapter3.ui
!include chapter4.ui
!include chapter5.ui
!end_document

[header.ui]
!title ...
!program ...
!author ...

[chapter1.ui]
!node Chapter 1
...

[chapter2.ui]
!node Chapter 2
...

[etc]

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

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

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

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

Use standardized source files

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

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

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

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

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

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

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

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

Write your own commands

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

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

!code_iso
!program Changing the font size
!author Dirk Hagedorn
!date August 19th 1996

!ifdest [tex]
!define tiny  {\tiny{(!1)}}
!define large {\large{(!1)}}
!define Large {\Large{(!1)}}
!define LARGE {\LARGE{(!1)}}
!define huge  {\huge{(!1)}}
!define Huge  {\Huge{(!1)}}
!endif

!ifdest [win,rtf]
!define tiny  {\fs14 (!1)}
!define large {\fs28 (!1)}
!define Large {\fs36 (!1)}
!define LARGE {\fs44 (!1)}
!define huge  {\fs50 (!1)}
!define Huge  {\fs60 (!1)}
!endif

!ifndest [tex,win,rtf]
!macro  tiny  (!2)
!macro  large (!2)
!macro  Large (!2)
!macro  LARGE (!2)
!macro  huge  (!2)
!macro  Huge  (!2)
!endif

!begin_document
!maketitle
!tableofcontents

!node Test

(!tiny [tiny]),
normal,
(!large [large]),
(!Large [Large]),
(!LARGE [LARGE]),
(!huge [huge]) und
(!Huge [Huge]).

!end_document

Home Tips & tricks Seven rules for writing UDO source files Tips & tricks according to LaTeX