TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate

Content on this page is licensed under the Public Documentation License (PDL).

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

Note:
Original document stored at Apache OpenOffice Website

Help File XML format Basics

Basic Document Structure

The basic structure of a valid help file for LibreOffice consists of a helpdocument root element with one meta and one body sub-element containing the content (body) and meta information (meta). The minimum information is a topic title and the filename inside the elements

/helpdocument/meta/topic/title and
/helpdocument/meta/topic/filename

<?xml version="1.0" encoding="UTF-8"?> <helpdocument version="1.0">
<meta>
<topic id="someid" indexer="include" status="PUBLISH"> <title xml-lang="en-US" id="tit">Topic Title</title> <filename>text/swriter/01/012345.xhp</filename>
</topic>
</meta>
<body>
</body>
</helpdocument>

Note:
The help file extension is 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. You must never use the literal name of the product but instead one of the following variables^[1]:

%PRODUCTNAME designates the name of the product, for example

LibreOffice.

%PRODUCTVERSION designates the current version of the product, for example

7.6.

Both variables are replaced by the main transformation style sheet main_transform.xsl (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 paragraph. There is no heading element, instead all headings are treated as paragraphs with a heading role. The role attribute defines the role of a paragraph with the paragraph role being the standard. The values for the role attribute are not defined in the DTD.

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

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

Role	Description	Converts to...
paragraph	A standard paragraph	...
heading	A heading If this role is assigned to a paragraph, the heading level has to be specified using the level attribute of the paragraph element.	<h1>...</h1> to <h6>...</h6>
note	A note	<p class="note">...</p>
warning	A warning	<p class="warning">...</p>
tip	A tip	<p class="tip">...</p>
code	A code fragment	<p class="code">...</p>
example	An example	<p class="example"> ...</p>
tablehead	A table head (first rows)	<p class="tablehead">...</p>
tablecontent	Table contents	<p class="tablecontent">...</p>

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 Index tab, the Contents tab and for context-sensitive help.

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

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

Note:
The only child element that is allowed inside the bookmark_value is embedvar to allow embedding of commonly used titles for content nodes or index entries. For examples of using embedded fragments inside bookmark values, refer to the next sections.

Contents Branch

Content entries are displayed on the Content tab page of the help viewer. The branch attribute takes the value contents. 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.

Note:
Note that currently the contents branch is not implemented in the help build process.

Example

<bookmark branch="contents" xml-lang="en-US" id="bm1">
<bookmark_value> Text Documents/
Objects in Text Documents/ 
Positioning Objects
</bookmark_value>
</bookmark>

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:

<variable id="textdocs">Text Documents</variable>
<variable id="objtextdocs">Objects in Text Documents</variable>

and embedded as text fragments:

<bookmark_value>
<embedvar href="/text/shared/00/variables.xhp#textdocs"/>/ 
<embedvar href="/text/shared/00/variables.xhp#objtextdocs"/>/
...
</bookmark>

Index Branch

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

Example

<bookmark branch="index" id="bm1" xml-lang="en-US">
<bookmark_value> 
editor;contour editor
</bookmark_value>
</bookmark>

As with content entries, the bookmark values for index entries can contain embedded text fragments by using the embedvar 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 LibreOffice. The branch attribute takes the value hid and in addition contains the help ID associated with the bookmark.

<bookmark id="bm_9876" xml-lang="en-US" 
branch="hid/HID_SOME_HELP_ID"/>

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 F1 key or the Help button.

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

Symbolic names, like SID_FM_CONVERTTO_IMAGECONTROL
UNO command names, like .uno:InsertCtrl

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 switch and switchinline element to specify the switching context:

Value	Switching context	Example/Comment
sys	Operating System	Switching content for Unix, Windows, or Mac platforms.
appl	Application	Switching content for different LibreOffice applications (Writer, Calc,...) in files that are common to multiple applications.
distrib	Distribution^[3]	Switching content for different distributions, like OpenOffice.org and StarOffice, which contains extra commercial features.

Table 5: Paragraph Switching Contexts

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

Switching Context	Values
Operating System (sys)	WIN UNIX MAC
Application (appl)	WRITER CALC DRAW IMPRESS MATH BASIC CHART

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 switch element can be used to accomplish this distinction:

<switch select="sys"> <case select="UNIX">
<paragraph>Mount the cd rom drive.</paragraph> </case>
</switch>

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 LibreOffice could be something like C:\Program Files\LibreOffice, it could be /usr/local/bin/libreoffice7.6 on a Unix system, making it necessary to distinguish between the operating environments when talking about these paths. The switchinline element can be used to accomplish the distinction:

<paragraph>The software will be installed in the <switchinline select="sys">
<caseinline select="UNIX"> /usr/local/bin/libreoffice7.6
</caseinline>
<caseinline select="WIN">
C:\Program Files\LibreOffice </caseinline>
<defaultinline> operating system's default installation
</defaultinline>
</switchinline>
directory.</paragraph>

In the code example above, there is also a default value defined by using the optional defaultinline element, which is shown if neitherUNIX nor WINis 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 file#id. If, for instance, the section with the ID 12345 from the file text/writer/01/012345.xhp is to be embedded, the URL would be text/swriter/01/012345.xhp#12345. The file name refers to the path and name that is stored in the jar files.

Complete sections can be embedded using the embed element. The section to be embedded is referenced using the attribute ID, 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: original.xhp):

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

Referenced location:

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

This results in the following:

Starting LibreOffice

Log on to your computer using your user name and your password.
Start LibreOffice

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 file#id. If, for instance, the variable with the ID 12345 from the file text/swriter/01/012345.xhp is to be embedded, the URL would be text/writer/01/012345.xhp#12345. The file name refers to the path + name that is stored in the jar files.

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

Original location (filename: original.xhp):

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

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:

A preview can be shown using the Print Preview button.

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:

A preview can be shown using the Print Preview button.

Images and Icons

All images must be placed inside paragraphs. The image element contains information about the image source in the src element and must be assigned a unique ID. Every image element must also contain a child element alt 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 alt element, there is also an optional caption 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 images.zip, which is available in the share/config directory of the LibreOffice installation. This archive contains all images that LibreOffice uses, separated by modules. The LibreOffice 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 images.zip archive contains a customized set of images.

The help itself also has a subdirectory inside the images.zip 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 res/helpimg in the archive.

Localization Information

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

Note:
Note that the help does not as yet support the pseudo-language x-comment as value for xml-lang to designate comments.

All paragraphs contain an l10n 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 *.xhp to build the help set. These are found in the source/auxiliary directory of the helpcontent2 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 makefile.mk, there are a number of XSL stylesheets used for help compilation:

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

Main Transformation Stylesheet

The main transformation stylesheet main_transform.xsl 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:

Database – this parameter identifies the help module context (see also Help Modules and Help Sections on page 13). It can have one of the values swriter, scalc, sdraw, simpress, schart, sbasic, smath. This value is used to evaluate application switches (see [[#page27|]]Switching Content on page 27).
System – this parameter identifies the operating system/platform. This value is used to evaluate system switches (see Switching Content on page 27).
productname and productversion – these parameters contain the name and version string of the product (e.g. "LibreOffice" "7.6", or "StarOffice" "8"). These are used to replace the variables %PRODUCTNAME and %PRODUCTVERSION in the help content (see Using Variables on page 23).
imgrepos – this parameter contains the physical path to the image repository images.zip used for requesting the images in the help files.
Id – this parameter contains the help ID called. It is displayed in the error message when the corresponding help file cannot be found.
Language – this parameter contains the current locale of the program.

Contents Definition Files *.tree

A number of *.tree 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 tree_view encapsulates one or more help_sections that contain one or more nodes with one or more topics (or further subnodes). The help_sections 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.

References

↑ In addition to these variables, the following two variables are still used in the help files for legacy reasons but deprecated: $[officename] and $[officeversion].
↑ Be advised that the help viewer component does not support all of CSS2.
↑ Note, that this switch is currently not evaluated in the main transformation step, since the help content provider does not provide the necessary information. Currently, the main transformation style sheet uses the value of the product name to distinguish between open source and commercial distributions, but this is only implemented for StarOffice and OpenOffice.org.

[ftn0-1] In addition to these variables, the following two variables are still used in the help files for legacy reasons but deprecated: $[officename] and $[officeversion].

[ftn1-2] Be advised that the help viewer component does not support all of CSS2.

[ftn2-3] Note, that this switch is currently not evaluated in the main transformation step, since the help content provider does not provide the necessary information. Currently, the main transformation style sheet uses the value of the product name to distinguish between open source and commercial distributions, but this is only implemented for StarOffice and OpenOffice.org.

[1]

[2]

[3]