Manuals, Subversion, UDO

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

(Geen Nederlandse informatie gevonden.)

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.

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.

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:

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.)

Example:
!begin_node New Chapter

I'm a quite normal text. Two line ends at the end of this text section inform UDO that this paragraph ends here.

I am a paragraph which has (!nl)
been spiced with new line (!nl)
commands.

!hline

# Note: Text missing here.

!end_node
Result:

New Chapter

I'm a quite normal text. Two line ends at the end of this text section inform UDO that this paragraph ends here.

I am a paragraph which has
been spiced with new line
commands.


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.)

Example:
!begin_itemize
!item I'm a list item.
!item Me too.
!item So am I.
!end_itemize

!begin_enumerate
!item I am the (!B)first(!b) item in this list.
!item I am the (!I)following(!i) item in this list.
!item I am the (!U)last(!u) item in this list.
!end_enumerate

!begin_description
!item [List Item]
A descriptive list formats the term bold which is enclosed in square brackets. The description of this term is placed below.
!end_description
Result:
  • I'm a list item.
  • Me too.
  • So am I.
  1. I am the first item in this list.
  2. I am the following item in this list.
  3. I am the last item in this list.
List Item
A descriptive list formats the term bold which is enclosed in square brackets. The description of this term is placed below.

(Als u fouten in de Nederlandse vertalingen en teksten vindt, wilt u ons dan – Hartelijk bedankt!)

Startpagina | iCalamus | Download | Kopen | Support | Nieuws | Contact · Gegevensbescherming
© 2006-2017 · [1134912]