Documentation/Understanding, Authoring and Editing Openoffice.org Help/2

Author: Frank Peters, Sun Microsystems (fpe@openoffice.org) Version: 2.0_16 Date: Feb 3, 2006

Public Documentation License Notice The contents of this Documentation are subject to the Public Documentation License Version 1.0 (the "License"); you may only use this Documentation if you comply with the terms of this License. A copy of the License is available at https://www.openoffice.org/licenses/PDL.html. The Initial Writer of the Original Documentation is Sun Microsystems Inc. Copyright (C) 2005. All Rights Reserved. (Initial Writer contact(s): fpe@sun.com). Contributor(s): ______________________________________.

=Help File XML format Basics=

Basic Document Structure
The basic structure of a valid help file for OpenOffice.org consists of a  element with one   and one   sub-element containing the content  and meta information. The minimum information is a topic title and the filename inside the elements


 * and

   Topic Title text/swriter/01/012345.xhp

Using Variables
In the help files the following variables are used to designate the name and the version of the product. This is to allow for correct branding of the product (for example, OpenOffice.org vs. StarOffice). You must never use the literal name of the product but instead one of the following variables :


 * designates the name of the product, for example

OpenOffice.org.


 * designates the current version of the product, for example

2.0.

Both variables are replaced by the main transformation style sheet  (see page 16) when the help is displayed. The corresponding information is taken from the application's configuration information and passed to the style sheet (see The Main Transformation Style Sheet on page 16).

Paragraph Roles
The main element for help content is a. There is no heading element, instead all headings are treated as paragraphs with a heading role. The  attribute defines the role of a paragraph with the   role being the standard. The values for the role attribute are not defined in the DTD.

During the conversion process (XML→HTML) the  attribute is mapped to a   attribute of the corresponding HTML element allowing to influence the layout of the corresponding paragraph using cascading style sheets.

The following roles are currently suggested and defined in the help authoring template. More roles can be defined as required (see also Paragraph Formatting on page 86):

Table 4: Paragraph Roles

If you use other roles, you must ensure that they are taken into account by the CSS files that define the help file display format.

Defining Index, Contents, and Context Sensitivity
The help uses one unified bookmarking system to set anchors inside the help files which are used by the  tab, the   tab and for context-sensitive help.

The main element is the  element. A bookmark has a  attribute representing the purpose of the bookmark. Currently there are three branches defined:,  , and.

To define an anchor for a bookmark inside a help document, the element  has to be positioned at the place the bookmark will point to. The  attribute specifies the type of bookmark to be defined (a content entry, an index entry, or a help ID), while the sub-element   contains the visible bookmark text, if applicable.

Contents Branch
Content entries are displayed on the Content tab page of the help viewer. The  attribute takes the value. The bookmark value can contain any number of levels separated by slashes, with the last part of the bookmark value serving as the entry and the other parts serving as nodes.

Example

  Text Documents/ Objects in Text Documents/ Positioning Objects 

A bookmark value can also contain embedded fragments for node titles. This reduces redundancy, maintenance effort, and the risk of introducing errors through typos. This can be avoided if the top level entries for the content tree are defined separately:

Text Documents Objects in Text Documents

and embedded as text fragments:

 / / ...

Index Branch
Index Entries are displayed on the Index tab page of the help viewer. The branch attribute takes the value  Currently, index entries can contain two levels separated by a semicolon.

Example

  editor;contour editor 

As with content entries, the bookmark values for index entries can contain embedded text fragments by using the  element, which can be useful if names of UI elements are used that are subject to change.

"hid" Branch
Help IDs are never displayed but instead trigger context-sensitive help inside OpenOffice.org. The  attribute takes the value   and in addition contains the help ID associated with the bookmark.



A bookmark for a given help ID can only be used once inside the help files since the bookmark defines the entry point for the help viewer when context-sensitive help is triggered from the UI either through the use of the  key or the   button.

There are two types of help IDs currently used in the help files:


 * Symbolic names, like
 * UNO command names, like

For details on determining the help ID for a UI element, see Determining A Help ID on page 98.

Switching Content
In some cases it is necessary to distinguish between different platforms or applications when displaying the help. For example, on one platform a key stroke to achieve a certain action can differ from the key stroke used on other platforms. To avoid duplicating large amounts of text and to reduce redundancy, switching elements are available, which are used to select the correct portion of the content at runtime.

The help content provider sends additional information along with a help request that states the current platform, language and application context. This information can be evaluated using the switch constructs to display the corresponding information.

There are two types of content switching:


 * Switching complete paragraphs or sections
 * Switching text fragments inside paragraphs

Currently, the following values are used for the select attribute of a  and  element to specify the switching context:

Table 5: Paragraph Switching Contexts

The following values are used for the select attribute of a  and   element within a given switching context:

Table 6: Inline Switching Contexts

Switching Complete Paragraphs Or Sections
This type is used, for example, if contents of a paragraph differ considerably on different platforms or for different applications, or if a certain paragraph or section is only applicable to a certain platform or application.

For example, while mounting a CD-ROM drive can be a necessary step on a Unix system, it is usually not applicable on Windows computers. The  element can be used to accomplish this distinction:

 Mount the cd rom drive.

Switching Text Fragments Inside Paragraphs
This type is used if only small text fragments differ on different platforms or applications. A typical case is the use of shortcuts on different systems, or the notation of file paths on different platforms.

For example, while on Windows the standard installation path for OpenOffice.org could be something like, it could be

on a Unix system, making it necessary to distinguish between the operating environments when talking about these paths. The  element can be used to accomplish the distinction:

The software will be installed in the  ~/OpenOffice.org-2.0 <caseinline select="WIN"> C:\Program Files\OpenOffice.org-2.0 home directory.

In the code example above, there is also a default value defined by using the optional element, which is shown if neither  nor  is set as the platform value when calling the help.

Embedding Content
You can also reduce redundant content by defining reusable text fragments and blocks, which can be referenced from other places. The references are resolved at runtime when the help is displayed, and are temporarily resolved at compile time when the full text search index is generated.

There are two ways of reusing content by means of embedding:


 * Embedding complete sections
 * Embedding text fragments

Embedding Complete Sections
Single or multiple paragraphs can apply to more than one help file. For example, standard steps inside procedures can be written once and embedded in multiple places, reducing maintenance and translation effort.

The URL for the reference takes the form. If, for instance, the section with the ID  from the file   is to be embedded, the URL would be. The file name refers to the path and name that is stored in the jar files.

Complete sections can be embedded using the  element. The section to be embedded is referenced using the attribute, which must be unique within the file.

If, for example, multiple processes described in the help involve logging on to a computer, this particular step can be written once and embedded wherever required:

Example

Original location (filename: ):

<paragraph id="par_id12345" role="paragraph" xml-lang="en-US"> Log on to your computer using your user name and password.

Referenced location:

<paragraph id="par_id9876" role="heading" level="1" xml-lang="en-US"> Starting %PRODUCTNAME <embed href="original.xhp#logon"/> <paragraph id="par_id9877" role="paragraph" xml-lang="en-US"> Start %PRODUCTNAME

This results in the following:


 * 1) Log on to your computer using your user name and your password.
 * 2) Start OpenOffice.org

Embedding Text Fragments
Text fragments can, for example, represent commonly used phrases or names of UI elements. These can be specified once and used in multiple places, reducing maintenance and localization effort.

The URL for the reference takes the form. If, for instance, the  with the ID   from the file   is to be embedded, the URL would be. The file name refers to the path + name that is stored in the jar files.

These fragments can be embedded using the  element if they are previously defined as being  s, so that they can be referenced. The text fragment to be embedded is placed inside a  element and assigned a unique ID using the element's   attribute:

Original location (filename: ):

<paragraph id="par_id1234">Press the <variable id="btn_prnprev"> Print Preview button.

The fragment can then be referenced in other locations using the embedvar element:

Referenced location:

<paragraph id="par_id9876">A preview can be shown using the <embedvar href="original.xhp#btn_prnprev"/> button.

Result:

If, for example, the name of the button changes from "Print Preview" to "Show Preview" you only need to update one location to make the change available in all referenced locations.

You can also embed the content of paragraphs by referring to the paragraph ID. Note that only the contents of the paragraph are embedded. The paragraph formatting information is disregarded:

Referenced location

<paragraph id="par_id433122"><embedvar id="referenced.xhp#par_id9876"/>

Result:

Images and Icons
All images must be placed inside s. The   element contains information about the image source in the   element and must be assigned a unique. Every  element must also contain a child element   that contains a short description of the image used if the visual content is not displayed or cannot be accessed by visually impaired users.

In addition to the  element, there is also an optional   element that can take a long description as an image caption.

Starting with OpenOffice.org 2.0, the help retrieves all images from the central image repository  which is available in the   directory of the OpenOffice.org installation. This archive contains all images that OpenOffice.org uses, separated by modules. The OpenOffice.org Help fetches any icons displayed in the help files from here. Since this also is the place where the application fetched the icons to display in the user interface, the icons in the help will always be in sync with the application, even if the  archive contains a customized set of images.

The help itself also has a subdirectory inside the  archive that contains all images that are specific to the help and only used by it, for instance screen captures. These images are stored under  in the archive.

Localization Information
Content that is to be localized is found inside elements with the  attribute that contains the elements language code. Elements can be excluded from localization by specifying the  attribute and setting it to. Any such element and all of its child elements will be excluded from the localization process.

All paragraphs contain an  attribute, which is used to specify the localization status of the paragraph. This attribute was only used in the migration phase and is not evaluated. It can be used to store a paragraph authoring status to implement basic content management functionality.

Auxiliary Files
Some auxiliary files are necessary, apart from the help files  to build the help set. These are found in the  directory of the   module. Some of them are just used for building the help, and some are included in the helpset.

Files Used For Building The Help
Apart from the makefile for this directory, there are a number of XSL stylesheets used for help compilation:


 * is used for resolving embedded sections in help files during compile time to correctly process embedded sections when creating keyword and fulltext search index
 * is used by the corresponding JAVA routine for creating the full text search index
 * is used by the corresponding JAVA routine for creating the full text search index

Main Transformation Stylesheet
The main transformation stylesheet  controls the last transformation step of the XML files to HTML before they are displayed in the help viewer. The file contains instructions on how to transform elements of the XML files to HTML elements to be displayed. It also takes care of some formatting issues, and is responsible for replacing variables used in the help files.

The help content provider passes some parameters to the stylesheet that are used for file processing:


 * – this parameter identifies the help module context (see also Help Modules and Help Sections on page 13). It can have one of the values,  ,  ,  ,  ,  ,  . This value is used to evaluate application switches (see Switching Content on page 27).
 * – this parameter identifies the operating system/platform. This value is used to evaluate system switches (see Switching Content on page 27).
 * and – these parameters contain the name and version string of the product (e.g. "OpenOffice.org" "2.0", or "StarOffice" "8"). These are used to replace the variables  and  in the help content (see Using Variables on page 23).
 * – this parameter contains the physical path to the image repository used for requesting the images in the help files.
 * – this parameter contains the help ID called. It is displayed in the error message when the corresponding help file cannot be found.
 * – this parameter contains the current locale of the program.

Contents Definition Files *.tree
A number of  files contain the information used to display the table of contents on the contents tab of the help viewer. These are XML files based on the following simple DTD:

<!ELEMENT tree_view (help_section)+> <!ATTLIST tree_view version CDATA #REQUIRED > <!ELEMENT help_section (node|topic)*> <!ATTLIST help_section application CDATA #REQUIRED id CDATA #REQUIRED title CDATA #REQUIRED > <!ELEMENT node (topic)*> <!ATTLIST node id CDATA #REQUIRED title CDATA #REQUIRED > <!ELEMENT topic (#PCDATA)> <!ATTLIST topic id CDATA #REQUIRED >

The main element  encapsulates one or more  s that contain one or more  s with one or more  s (or further  ). The s are the top-most element in the table of contents as displayed by the help viewer. Below that, there are nodes, represented by "book" icons in the help viewer and, finally, topics that can be selected. A node can have sub-nodes.