Handböcker, Subversion, UDO

This page describes how we handle our manual sources with Subversion and UDO.

(Hittade ingen svensk information.)

Nothing's Older Than Your Manual Printout From Yesterday.

Manuals always have to keep up with the ongoing development of applications. Therefore it is recommended to put your manual sources on a shared server, to give all manual authors and localizers direct access to the data. We believe that Subversion is the perfect tool for this job.

Subversion Manages Data For Concurrent Editing

Thanks to Subversion (hereinafter called SVN) we can give our manual authors and localizers direct access to our manual sources and ensure that noone can damage the sources, multiple authors can work on files at the same time and all files will always have a unique state.

As a manual author, you don't have to understand SVN completely, just this much:

1. Repository
   The data of a manual are stored in a 'repository' on our SVN server. The repository always represents the current state of these data for all authors.
2. Checkout
   If you download data from the SVN server to your computer (checkout), you create a ''Working Copy' on your hard drive, which you can edit as you like to.
3. Commit
   Wenn you send back your changes to the SVN server (commit), they will be taken and from this moment they are available to all other authors.

Closed Society!

Only our developers, manual authors and localizers get access to our SVN server. The SVN server serves and manages various repositories but each repository has its own access rules. We believe: Too much freedom can trouble you. If you want to get access to a certain repository on our SVN server, you need an SVN account and an SVN password. Both are available from us on request.

How Do I Get The Data?

OS X

If you work with Apple's developer tool Xcode, you don't have to install other tools as Xcode supports SVN automatically. You just have to activate it. Consult the Xcode manual how to.

Otherwise Subversion and a graphical user interface (GUI) for SVN are required, to make Checkout and Commit more fun than from the command line.

• Subversion
• SVN GUI: SmartSVN
• optional SVN GUI: svnX

Windows

Subversion and a graphical user interface (GUI) for SVN are required, to make Checkout and Commit more fun than from the command line. We recomment the GUI tool TortoiseSVN.

• Subversion
• SVN GUI: TortoiseSVN

How Do The Manual Sources Look Like?

We write our manuals in UDO format, a universal document format with an easy approach. The repositories are basically organized like the following example (which refers to OS X applications):

/cs.lproj/
/cs.lproj/<Help Book name>/
/da.lproj/
/da.lproj/<Help Book name>/
/de.lproj/
/de.lproj/<Help Book name>/
/en.lproj/
/en.lproj/<Help Book name>/
/fr.lproj/
/fr.lproj/<Help Book name>/
/it.lproj/
/it.lproj/<Help Book name>/
/nl.lproj/
/nl.lproj/<Help Book name>/
/UDoSource/
/UDoSource/_INCLUDE/
/UDoSource/<various folders>
/UDoSource/<ProjectName>_main_cs.u
/UDoSource/<ProjectName>_main_da.u
/UDoSource/<ProjectName>_main_de.u
/UDoSource/<ProjectName>_main_en.u
/UDoSource/<ProjectName>_main_fr.u
/UDoSource/<ProjectName>_main_it.u
/UDoSource/<ProjectName>_main_nl.u

The *.lproj folder structure as shown above is a copy of the language dependent project folders for the application. They contain Apple Help Book folders which can be copied directly to the application sources.

The folder UDoSource contains all data which have to be localized. We have defined our own nomenclature for file extension usage, like this:

• .cs = Czech text files
• .da = Danish text files
• .de = German text files
• .en = English text files
• .fr = French text files
• .it = Italian text files
• .nl = Dutch text files

• .u = UDO command files
• .ui = UDO include files
• .uli = UDO library include files

Of course the repositories don't have to contain exactly these mentioned folders and languages.

UDO Format, What Is This Now?

UDO uses a very simple syntax to structurize text, add text attributes, include images, links etc. The highlight in UDO is it's really easy approach, although it offers very many commands. We try to avoid 'feature overkill' in our manuals and use just a few UDO syntax elements. Here are some examples:

Structurizing Text

!begin_node starts a new chapter.
!end_node ends a chapter.
# at the line start advices UDO to ignore the whole line (comment line).
!hline shows a horizontal line.
(!nl) forces a line break. (Basically UDO closes a text paragraph when it recognizes two line ends.)

Text Attributes

(!B) and (!b) switch bold font on/off.
(!I) and (!i) switch italic font on/off.
(!U) and (!u) switch underline on/off.

(There are many other attribute commands; we ignore most of them.)

Lists

!begin_itemize and !end_itemize span the area of an unsorted list.
!begin_enumerate and !end_enumerate span the area of a numbered list.
!begin_description and !end_description span the area of a descriptive list.
!item starts a list item.

(There are much more layout commands; we ignore most of them.)