How LibreOffice Help Works

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

• Wiki Home
• Development
• Design
• QA
• Events
• Documentation
• Website
• Localization
• Accessibility
• Marketing
• Diversity
• Wiki Help

• Documentation Home
• Official Publications
• Other Resources
• FAQ
• HowTo
• Macros
• Docs Development

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

How LibreOffice Help Works

This chapter gives an overview of the LibreOffice help system. It describes the different features of the help system, how it is organized, and how it is built from the source files.

Help Ingredients

The LibreOffice help system comprises different help features, which are explained in detail in the following sections.

Extended Tips

Obsolete The ahelp element is not used to populate extended tips anymore. Do not use them, but please do not remove them from help pages in case their contents haven't been migrated yet. For more information, see the ahelp element's documentation. The information below stays here for legacy purposes.

Extended Tips are popups that appear on the application user interface (UI), and display a short reference text for an element. An extended tip for a particular UI element is triggered by resting the mouse over that element for a short amount of time (approx. 1 second). On moving the mouse, the extended tip disappears.

Display of extended tips is enabled by choosing Tools ▸ Options... ▸ LibreOffice ▸ General ▸ Help ▸ Extended Tips, or by pressing Shift+F1.

When the extended tips are enabled by pressing Shift+F1, the tips are displayed without any delay. This mode is exited when a mouse button is clicked.

Extended tips use Help Ids, which are assigned to UI elements to find the correct text for that UI element. The text itself is defined in the help files inside the ahelp element. For more information about the structure of the help files, please refer to chapter 2: Help File XML format Basic on page 23.

Context-Sensitive Help

LibreOffice Help is context-sensitive, which means that the help viewer displays reference information or instructions for the current application context when the help is called from within the application.

Context-sensitive help is invoked by pressing F1 or clicking the Help button in a dialog.

Help IDs are used to identify the context. A lookup table is used to find the correct anchor inside the help file set (see also Application Help Calls on page 16).

Note: Not all contexts are actually mapped to help topics. In that case, the start page of the corresponding help section is shown.

Hierarchical List Of Contents

There is a hierarchical list of help contents available from the Contents tab page of the help viewer. This should not be considered a complete table of contents, like in a book, but a selection of help topics sorted by different application/document types and task groups (see Fig. 1).

Help topics can appear more than once if they fit into multiple application/task groups. Currently, these contents trees are manually compiled and saved in *.tree files.

In the future, these contents lists will be able to be defined within the help files themselves. The *.tree files will then be created when the help is compiled in the software build cycle.

Note: Note that, although the corresponding elements are included in the help format, these are not yet evaluated by the help compiler. The tree files must still be generated manually.

Index of Keywords

The Index tab page of the help viewer contains a two-level keyword index. These two levels allow for a basic grouping of keywords. The index is displayed per help module (see Fig. 2 on page 12).

After selecting an LibreOffice help module from the dropdown list at the top left of the help viewer, the corresponding list of keywords is loaded.

Typing a search term directly causes a jump to the next suitable first-level entry in the index list.

The keywords are defined inside the help files as bookmarks. See also section Bookmarks.

Fig. 1: List of contents	Fig. 2: Keyword index
Fig. 3: Full text search	Fig. 4: Bookmarks

Full-Text Search

The Find tab page allows you to search through the help content. You can only search through one help module at a time (see Fig. 3).

By default, the search engine searches for case-insensitive substrings that appear anywhere in a help file. You can restrict the search scope by specifying a search for complete words only, and to only search headings in help files.

The results are displayed sorted by search rank, showing the best matches at the top of the list.

Bookmarks

The Bookmarks tab page lists user-defined bookmarks that correspond to help pages. User-defined bookmarks from all help modules can belong to this list. The icon next to a bookmark indicates the help module to which the bookmark belongs (see Fig. 4).

Double-clicking the bookmark takes you back to the corresponding help page.

Bookmarks can be named individually.

Note: Don't confuse these bookmarks with the bookmark element in the help XML format.

Help Agent

OBSOLETE The help agent has been removed in LibreOffice. The information stays here for legacy purposes.

The Help Agent is a small notification window that appears when the user is in a certain context, for example, when the AutoCorrect function has automatically modified the text. Clicking the window opens the help at the location that is assigned to that context.

As with the extended tips and the context sensitive help, the context for the Help Agent is specified using Help IDs. The IDs that trigger the display of the Help Agent are defined in the file SFX.xcu in the directory share/registry/data/org/openoffice/Office. This file is not part of the helpcontent2 CVS project.

Installed Help Files

On installation, a help directory is created as child of the main LibreOffice directory. It contains all global files (currently only main_transform.xsl), and one or more subdirectories with language-dependent files. The language directories are designated by ISO codes, for example, en-US for US-English. The contents of this language directory are as follows:

Directory/File	Description
help/	The main help directory
help/main_transform.xsl	The main transformation style sheet (see The Main Transformation Style Sheet below)
help/{lang}	The language dependent help files
help/{lang}/*.css	The cascading style sheets for displaying the help in the help viewer (see The Cascading Style Sheets below)
help/{lang}/err.html	The error file. This file is called whenever a help page can not be found
help/{lang}/shared.jar	The help file archive for shared help files
help/{lang}/shared.tree	The contents file for shared help files (see Help Module Contents Files (Section Archives))
help/{lang}/schart.jar	The help file archive for help files dealing with charts
help/{lang}/schart.tree	The contents file for help files dealing with charts (see Help Module Contents Files (Section Archives).
help/{lang}/{module}.cfg	The configuration files for a help module (see Help Module Configuration Files)
help/{lang}/{module}.db	The lookup tables for a help module (see Help Module Lookup Tables (Databases))
help/{lang}/{module}.ht	The extended tips for a help module (see Help Module Extended Tip Files)
help/{lang}/{module}.idx/	The full text search index for a help module
help/{lang}/{module}.jar	The help file archive for a help module
help/{lang}/{module}.key	The index file for a help module (see Help Module Index Files)
help/{lang}/{module}.tree	The contents file for a help module (see Help Module Contents Files (Section Archives))

Table 1: Hep files that are installed

Help Modules And Help Sections

The help is divided into different help modules that can be selected using the drop down list at the top left of the help viewer. These correspond to the applications or modules of LibreOffice.

Each help file (*.xhp) has a scope that consists of one or more help sections and includes the corresponding help file archives *.jar. These archives contain all help files of a help section. A help section does not correspond to an application of LibreOffice.

In the help file viewer, the index and the full text search work within this scope only.

Note: The distinction between help module and help section is confusing and will be eradicated in the future. Basically, a help section contains all files that are found inside the text/{section} path of the help source directory (see Structure of the CVS Help Module on page 18 for the structure of the help source module). Each help section produces a *.jar archive containing all help files in that path. A help module takes one or more sections and combines them to form the scope of a module.

Help module	Help Sections (Scope)
BASIC	sbasic + shared
Calc	scalc + shared + schart
Draw	sdraw + simpress + shared + schart
Impress	sdraw + simpress + shared + schart
Math	smath + shared
Writer	swriter + shared + schart
Base	shared/explorer/database

Table 2: LibreOffice help modules and scopes

From the table above, it follows that the scope for the Writer help module includes all help files from swriter.jar, shared.jar and schart.jar. Each help module has a set of six files (cfg, db, ht, jar, key, tree) and an *.idx directory associated with it except for Draw and Base, which have no *.tree file .

Help Module Configuration Files

The *.cfg configuration files are ASCII files containing parameter=value pairs with configuration information. They are created and maintained manually:

Title=%PRODUCTNAME Writer
Copyright=Copyright 2004, Sun Microsystems, Inc. Language=en-US
Order=2
Start=text%2Fswriter%2Fmain0000.xhp
Heading=headingheading
Program=WRITER 
07.07.04 00:00:00

• Title specifies the help module title as displayed in the drop down list at the top left of the help viewer.
• Copyright is a copyright string.
• Language specifies the help language for the help module.
• Order was used in an earlier implementation and is deprecated.
• Start defines the start page for a help module. The slashes in the path name are encoded as %2F. The start page must be contained in the archive that has the same name as the configuration file (swriter.jar for swriter.cfg)
• Heading defines an internal value that is used by the full text search engine.
• Program specifies the application name that will be used for switching content (see Switching Content on page 99)
• The last line contains the creation date. Use of this is deprecated. It is not evaluated anywhere.

Help Module Contents Files (Section Archives)

The *.jar contents files contain the help topic files for a help section (see Help Modules and Help Sections). It is an archive file with a subdirectory structure that contains all help xhp files. There is one archive per help section (sbasic, shared, sdraw, simpress, scalc, schart, swriter, smath). Each help module comprises more than one help section (see Help Modules and Help Sections).

Help Module Lookup Tables (Databases)

The lookup tables *.db are Berkeley databases that contain a lookup table used by the help application to find a help page to display for a given help ID. The tables are used for referencing context sensitive help pages when help is called from the application. They are not used for calling help files from within other help files. This is designated by the parameter UseDB=no in the help file URL (see Application Help Calls on page 16). The data for that table come from the bookmark elements in the help files (see Bookmarks on page 95).

Help Module Extended Tip Files

The files *.ht are Berkeley databases that contain the extended help tip text for all Help IDs. The application uses these files to fetch the text for an extended tip for a given Help ID.

The data for that table come from the bookmark elements in conjunction with the ahelp elements in the help files (see Bookmarks on page 95). It is extracted from the help files at compile time.

Help Module Index Files

The files *.key are Berkeley databases that contain the index entries for the help modules.

The data for that table come from the bookmark elements in the help files (see Bookmarks on page 95). It is extracted from the help files at compile time.

The Main Transformation Style Sheet

The file main_transform.xsl is global for all languages and help files and is used for final transformation of the xhp help file to yield an html file that is displayed by the help viewer component.

This style sheet is responsible for converting XML help elements and classes into HTML elements and classes. The overall layout of the help file is specified using this style sheet. The graphical appearance is controlled by the cascading style sheets (see The Cascading Style Sheets).

The Cascading Style Sheets

The cascading style sheets *.css describe the formatting style for the help page. Since different locales require different fonts and font effects, the cascading style sheets are language dependent. There is one set of style sheets per language.

OBSOLETE Help Formatting is not available in LibreOffice anymore. The information stays here for legacy purposes.

The LibreOffice help viewer only recognizes some basic CSS2 commands. There are five style sheets available, four of which account for special accessibility issues. They are selected in the application using Tools ▸ Options... ▸ OpenOffice.org ▸ General ▸ Help ▸ Help formatting.

Application Help Calls

This section briefly describes what happens when a help file is called from the application or from within the help itself (links or embeddings).

Figure 1: Help calls

1. When F1 or a help button is pressed in an LibreOffice application, a help request is sent as an URL to the help content provider.
2. The help ID is resolved to a help file using the help lookup table for the application ($module.db).
3. When a help file is called from within the help, the URL sent to the help content provider contains the file path. There is no need for resolving the ID.
4. The help file is extracted from the corresponding help file archive ($module.jar).
5. The extracted help file is transformed into HTML using the main_transform.xsl style sheet and sent to the help viewer for display. The stylesheet main_transform.xsl controls all conversion from xhp to html, and must be adjusted whenever new elements, attributes, or attribute values must be taken into account.

The URLs sent to the help content provider have two forms:

URLs from the application

vnd.sun.star.help://swriter/12345?Language=en-US&System=UNIX

URLs send within the help:

vnd.sun.star.help://swriter/text/swriter/main0100.xhp?Language=en-US&System=UNIX&UseDB=no&DbPAR=swriter

• The protocol identifier vnd.sun.star.help:
• The help archive jar file to use: swriter
• The help ID to look up, or the name of the file to extract: 12345 or swriter/text/swriter/main0100.xhp
• A parameter for the current language: Language=en-US
• A parameter for the current operating system: System=UNIX
• A parameter to disable help ID lookup (only for help internal URLs): UseDB=no
• A parameter to describe the current help context (module): DbPAR=swriter This can differ from the help archive jar file used (see also Help Modules and Help Sections on page 13).

Structure of the CVS Help Module

The help source files and all helper files are located in the CVS module helpcontent2. The directory layout is as follows:

Directory	Content
helpcontent2/	The module's main directory
helpcontent2/helpers	Files that are not used by the help content itself, like the DTD for the XML help format.
helpcontent2/helpers/helpauthoring	The help authoring environment for LibreOffice, see Authoring Help with LibreOffice on page 75.
helpcontent2/source	The help source files that are used to build the help.
helpcontent2/source/auxiliary	Auxiliary files that do not contain help content but are still needed for building the help, style sheets, configuration files (see Auxiliary Files on page 31)
helpcontent2/source/text	The help content source files, the makefiles for the help compiler, and the localized content. Every subdirectory contains its own makefile and a file with all localized content.
helpcontent2/source/text/sbasic	Help files specific to BASIC (and the IDE).
helpcontent2/source/text/scalc	Help files specific to the Calc module.
helpcontent2/source/text/schart	Help files specific to charts.
helpcontent2/source/text/sdraw	Help files specific to the Draw module.
helpcontent2/source/text/shared	Help files common to two or more modules.
helpcontent2/source/text/simpress	Help files specific to the Impress module.
helpcontent2/source/text/smath	Help files specific to the Math module.
helpcontent2/source/text/swriter	Help files specific to the Writer module.
helpcontent2/prj	The build lists.
helpcontent2/util	The makefiles for the help linker (see Makefiles for linking the compiled files on page 20).

Table 3: Structure of the Help CVS module

Note: Note that the help images are no longer part of the CVS module. Starting with OpenOffice.org 2.0, application icons are directly taken from the images.zip repository in the share/config directory.

Note: Images specific to the help need to be added to the CVS default_images module in the helpimg subdirectory. These will then also be included in the images.zip archive.

Building the Help Set

OBSOLETE This information is obsolete and is not valid anymore for LibreOffice. The information stays here for legacy purposes.

Setting Up a Build Environment

This is described on tools.openoffice.org.

Makefiles for the Help

The helpcontent2 module contains three types of makefiles:

Makefiles for compiling the help source files

These makefiles are found in the helpcontent2/source/text directories. Every subdirectory that contains help files to be compiled has a corresponding makefile, for example (shortened for clarity):

#***************************************************************
#***************************************************************
# edit to match directory level PRJ = ..$/..$/..$/..
# same for all makefiles in "helpcontent2" 
PRJNAME = helpcontent2 
# edit to match the current package 
PACKAGE = text/sbasic/guide 
# uniqe name (module wide); 
# using a modified forme of package should do here 
TARGET = text_sbasic_guide 
# edit to match the current module 
MODULE = sbasic 
# --- Settings ------------------------------------------------ 
.INCLUDE : settings.mk  
.INCLUDE : $(PRJ)$/settings.pmk
# this list matches the *.xhp files to process 
HZIPFILES = \ 
control_properties.hzip \ 
create_dialog.hzip \ 
insert_control.hzip \ 
sample_code.hzip \ 
show_dialog.hzip 
#--- Targets ------------------------------------------------- 
.INCLUDE :  target.mk
.INCLUDE : $(PRJ)$/makefile.pmk

You find a template for this makefile in helpcontent2/helpers. This template is used when the makefiles are created using the createmakefile.pl script in helpcontent2/helpers. Use this script for makefile creation and don't modify the makefiles manually.

Makefiles for linking the compiled files

These makefiles are found in the subdirectories of helpcontent2/util (the directory itself contains the third type of makefile), for example (shortened for clarity):

#**************************************************************
#**************************************************************
# edit to match directory level 
PRJ = ..$/..
# same for all makefiles in "helpcontent2" 
PRJNAME = helpcontent2 
# uniqe name (module wide); 
# using a modified forme of package should do here 
TARGET = util_sbasic 
# --- Settings ------------------------------------------------ 
.INCLUDE : settings.mk
.INCLUDE : $(PRJ)$/settings.pmk
.IF "$(SOLAR_JAVA)"!="" 
common_build_zip:= 
zip1generatedlangs=TRUE 
zip1langdirs=$(aux_alllangiso) 
ZIP1TARGET=xhp_sbasic 
ZIP1FLAGS= -u -r 
ZIP1DIR=$(MISC)$/$(LANGDIR)
ZIP1LIST=$(LANGDIR)$/text$/sbasic$/* -x "*.dphh*" \
-x "*.hzip" -x "*.created"
.ENDIF         # "$(SOLAR_JAVA)"!=""
LINKNAME=sbasic LINKADDEDFILES= \
   -add sbasic.cfg
$(PRJ)$/source$/auxiliary$/LANGUAGE$/sbasic.cfg \
   -add sbasic.tree $(PRJ)$/source$/auxiliary$/LANGUAGE$/sbasic.tree \
   -add sbasic.jar  $(BIN)$/xhp_sbasic_LANGUAGE.zip
LINKADDEDDEPS= \ 
$(PRJ)$/source$/auxiliary$/LANGUAGE$/sbasic.cfg \ 
$(PRJ)$/source$/auxiliary$/LANGUAGE$/sbasic.tree \ 
$(BIN)$/xhp_sbasic_LANGUAGE.zip
LINKLINKFILES= \ 
text$/sbasic$/guide$/control_properties.hzip \ 
text$/sbasic$/guide$/create_dialog.hzip \ 
text$/sbasic$/guide$/insert_control.hzip \ text$/sbasic$/guide$/sample_code.hzip \ 
text$/sbasic$/guide$/show_dialog.hzip \
# --- Targets -------------------------------------------------
.INCLUDE :  target.mk
.INCLUDE :  $(PRJ)$/util$/target.pmk

You find a template for this makefile in helpcontent2/helpers. This template is used when the makefiles are created using the createmakefile.pl script in helpcontent2/helpers. Use this script for makefile creation and not to modify the makefiles manually.

A makefile for creating the stylesheet archive in helpcontent2/util (shortened for clarity)

#**************************************************************
#**************************************************************
# edit to match directory level 
PRJ = ..
# same for all makefiles in "helpcontent2" 
PRJNAME = helpcontent2 
# uniqe name (module wide); 
# using a modified forme of package should do here 
TARGET = plain_util 
#
# --- Settings ------------------------------------------------ #
.INCLUDE : settings.mk
.INCLUDE : $(PRJ)$/settings.pmk
ZIP1TARGET=helpxsl 
ZIP1FLAGS= -u -r
ZIP1DIR=$(PRJ)$/source$/auxiliary 
ZIP1LIST=main_transform*.xsl
# --- Targets -------------------------------------------------
.INCLUDE :  target.mk
ALLTAR : $(COMMONBIN)$/helpimg.ilst
$(COMMONBIN)$/helpimg.ilst: helpimg.ilst 
     $(COPY) $< $@

Help Build Process

The file helpconten2/prj/build.lst defines which directories are built using a directory's makefile. Dependencies (which directories need to be built first) are also defined here.

Initiate a help build by issuing the command build while in the helpcontent2 directory.

1. The help files from helpcontent2/source/text are compiled and written to the misc subdirectory of the platform directory of the output tree. This step produces a set of *.hzip files and dependency files *.dphh. These files are the particles that are used to create the help modules in the next – the linking – step.
2. The compiled help files are taken from the misc directory and linked into a zip archive. Other files are added from the helpcontent2/source/auxiliary directory to that archive as defined in the makefiles of the subdirectories in helpcontent2/util. This results in one zip archive per help module and language in the bin subdirectory of the platform directory of the output tree.
3. The helpxsl.zip archive is built according to the makefile in helpcontent2/util.
4. All archive files are delivered according to the d.lst file in helpcontent2/prj

Adding A Help File To Or Removing A Help File From The Set Of Help Files

The makefiles need to be adjusted to reflect the changes you made to the set of files. If you added a new file, add this to the makefile of its directory and to the link makefile (in helpcontent2/util/*) of any module that will contain the file. If you deleted a help file, remove it from the makefile of its directory and from the link makefile (in helpcontent2/util/*) of any module that contains the file.

Note: The safest way is to run the create_makefiles.pl script from helpcontent2/helpers to update the makefiles.

If you rebuild the help after help files have been deleted, or after dependencies (references) between the files have been changed, you need to remove all dependency files from the misc directory that are no longer valid. To be perfectly safe, you can remove the complete output tree for the platform of the helpcontent2 module.

Help Images

Images that are used inside the help are stored in different modules and accessed by the help viewer using the images.zip archive on runtime. Therefore, you need to add help images, such as screenshots, to the helpimg directory of the default_images module. Including the help images to the images.zip repository is controlled by the helpimg.ilst file that is found in the util directory of helpcontent2.

The helpimg.ilst file contains all image files to be included for helpcontent2, one file per line. The variable %GLOBALRES% is used to designate the default image directory:

%GLOBALRES%/helpimg/calcein.png

Note: Don't forget the localized files in the subdirectories.