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

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

= How OpenOffice.org Help Works =

This chapter gives an overview of the OpenOffice.org 2.0 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 OpenOffice.org help system comprises different help features, which are explained in detail in the following sections.

Extended Tips
Extended Tips are yellow pop-up windows 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, or by pressing.

When the extended tips are enabled by pressing, 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  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
OpenOffice.org 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 or clicking the  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).

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

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

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 OpenOffice.org 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.

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.

Help Agent
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  in the directory. This file is not part of the  CVS project.

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

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 OpenOffice.org.

Each help file has a scope that consists of one or more help sections and includes the corresponding help file archives. These archives contain all help files of a help section. A help section does not correspond to an application of OpenOffice.org.

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

Table 2: OpenOffice.org help modules and scopes

From the table above, it follows that the scope for the Writer help module includes all help files from,   and. Each help module has a set of six files and an   directory associated with it except for Draw and Base, which have no   file.

Help Module Configuration Files
The  configuration files are ASCII files containing   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  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  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  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  in the help file URL (see Application Help Calls on page 16). The data for that table come from the  elements in the help files (see Bookmarks on page 95).

Help Module Extended Tip Files
The files  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  elements in conjunction with the   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  are Berkeley databases that contain the index entries for the help modules.

The data for that table come from the  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  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  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.

The OpenOffice.org 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.

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




 * 1) When F1 or a help button is pressed in an OpenOffice.org 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.
 * 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.
 * 5) The extracted help file is transformed into HTML using the   style sheet and sent to the help viewer for display. The stylesheet   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 :
 * The help archive jar file to use:
 * The help ID to look up, or the name of the file to extract:  or
 * A parameter for the current language:
 * A parameter for the current operating system:
 * A parameter to disable help ID lookup (only for help internal URLs):
 * A parameter to describe the current help context (module):  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:

Table 3: Structure of the Help CVS module

Setting Up A Build Environment
This is described on.

Makefiles For The Help
The  module contains three types of makefiles:

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

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

You find a template for this makefile in. This template is used when the makefiles are created using the  script in. 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  (the directory itself contains the third type of makefile), for example (shortened for clarity):

PRJ = ..$/.. PRJNAME = helpcontent2 TARGET = util_sbasic .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 \ .INCLUDE : target.mk .INCLUDE :  $(PRJ)$/util$/target.pmk
 * 1) edit to match directory level
 * 1) edit to match directory level
 * 1) edit to match directory level
 * 1) same for all makefiles in "helpcontent2"
 * 1) uniqe name (module wide);
 * 2) using a modified forme of package should do here
 * 1) --- Settings
 * 1) --- Targets -

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

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

Help Build Process
The file  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  while in the   directory.


 * 1) The help files from   are compiled and written to the   subdirectory of the platform directory of the output tree. This step produces a set of   files and dependency files  . 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   directory and linked into a zip archive. Other files are added from the   directory to that archive as defined in the makefiles of the subdirectories in  . This results in one zip archive per help module and language in the   subdirectory of the platform directory of the output tree.
 * 3) The   archive is built according to the makefile in.
 * 4) All archive files are delivered according to the   file in

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 ) 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 ) of any module that contains the file.

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  directory that are no longer valid. To be perfectly safe, you can remove the complete output tree for the platform of the  module.

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

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

%GLOBALRES%/helpimg/calcein.png