################################################################################
#
# Project     : UDO manual
# Chapter     : Practice: Tips & Tricks
# Language    : English
# Initial Date: 2009-06-06
# Author      : Dirk Hagedorn
# Co-author(s): Ulf Dunkel (fd)
# Write-access: fd
#
# ------------------------------------------------------------------------------
# 
# History
# -------
# 2009:
#   fd  Jun 06: introduced (extracted from working.ui)
#   fd  Jun 09: multi-language paragraph added
#   fd  Jun 09: using more macros for text style formatting
#   fd  Jun 09: macro (!file) introduced
#   fd  Jun 10: using macro (!file [])
#   fd  Jun 10: using EXAMPLE_... macros
# 2010:
#   fd  May 21: chapter 'Use standardized file names' added
#
################################################################################

!begin_node Tips & Tricks
!html_name working_tips

################################################################################

!begin_node Split large documentations
!html_name working_tips_split

If you write a documentation that is 30~kB or larger you should split it up 
into different parts which you can merge with (!KW [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.
Maybe you have a documentation with five chapters. Write a preamble file, a
main file and five files that contain the chapters:

(!EXAMPLE_BEGIN)
!vinclude (!EXAMPLES)main.u
(!EXAMPLE_END)

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

(!EXAMPLE_BEGIN)
!vinclude (!EXAMPLES)ch5test.u
(!EXAMPLE_END)

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.

!end_node

################################################################################

!begin_node Use standardized source files
!html_name working_tips_standardize

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:

!autoref [off]
(!EXAMPLE_BEGIN)
!begin_verbatim
""Hello, World!"" Version 8.15 (!nl)
Copyright (!copyright) 1996 by C. Rookie
!end_verbatim
(!EXAMPLE_END)
!autoref [on]

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?

!autoref [off]
(!EXAMPLE_BEGIN)
!begin_verbatim
""(!PrgName)"" Version (!PrgVersion) (!nl)
Copyright (!copyright) (!PrgYear) by C. Rookie
!end_verbatim
(!EXAMPLE_END)
!autoref [on]

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.

!autoref [off]
(!EXAMPLE_BEGIN)
!begin_verbatim
!macro PrgName    Hello, World!
!macro PrgVersion 8.15
!macro PrgYear    1996
...
!begin_document
...
!include copyleft.ui
!end_verbatim
(!EXAMPLE_END)
!autoref [on]

Surely this is only a small example. But you can make more complex
files if you want to.

!end_node

################################################################################

!begin_node Use standardized file names
!html_name working_tips_standardize_files

UDO does not concern how you name the files which make up your UDO source text document.
But for structurized workflows, it can be very useful to create your own standards.
Especially when you exchange work with other persons, you should even name files in a standardized way.

As soon as you are going to create documentations for multiple languages, you should use English file names if you're not completely sure that all co-authors and colleagues really understand your language (e.g. German) and that no file system they are working with, has any difficulties with e.g. German umlauts in file names.

Here is our suggestion:

!begin_blist
!item [.u]
      Mnemonic: (!code [.u]) like (!B)U(!b)DO. This is the main file for the document, e.g. (!file [manual.u]).

!item [.ui]
      Mnemonic: (!code [.ui]) like (!B)U(!b)DO (!B)I(!b)nclude. These files are included by the .u file. 
      These files should contain just more control commands, but no text which might want to be localized.

!item [.uli]
      Mnemonic: (!code [.uli]) like (!B)U(!b)DO (!B)L(!b)ibrary (!B)I(!b)nclude. 
      Files which can be used from a library for several projects at the same time, e.g. macro definitions, hyphenation rules, etc.

!item [.de]
      All files with German texts.

!item [.en]
      All files with English texts.

!item [.sv]
      All files with Swedish texts. (If you wonder why we do not
suggest (!code [.se]) for these, here is our explanation: (!code [sv])
is the ISO descriptor for the language Swedish, while (!code [SE]) is
the ISO descriptor for the country Sweden. This is mixed up pretty
often, like e.g. with Czech ((!code [cs])) and Czechia ((!code [CZ])).

!item [.fr_CA]
      Now you got the idea, right? This file extension would define
that the document content of the file is written in Canadian French.
The ISO descriptors for languages and countries can be used that
easily. -- If you don't have to differenciate for French that way, a
simple (!file [.fr]) will be fine, of course.

!end_blist

If you name your files this way, you will simply have to add more (!KW [include]) commands in the (!file [.ui]) files when you add another localization to your documentation. Just copy your e.g. (!file [.en]) files and change the extension of the copied files to the desired language descriptor.

(!EXAMPLE_BEGIN)
!begin_verbatim
# manual.u
# --------
!include praeamble.ui

!begin_document
!include intro.ui
!include ref.ui
!include appendix.ui
!end_document

# intro.ui
# --------
!ifset [de]
!include intro.de
!endif
!ifset [en]
!include intro.en
!endif
!end_verbatim
(!EXAMPLE_END)
     
!end_node

################################################################################

!begin_node Write your own commands
!html_name working_tips_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:

(!EXAMPLE_BEGIN)
!vinclude (!EXAMPLES)fontsize.u
(!EXAMPLE_END)

!end_node

################################################################################

!end_node
