How LibreOffice Help Works

    From The Document Foundation Wiki


    Heckert GNU white.svg

    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 pin.svg

    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

    Warning.svg

    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 pin.svg

    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 pin.svg

    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 pin.svg

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

    Help Agent

    Warning.svg

    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[1]
    help/{lang}/schart.tree The contents file for help files dealing with charts (see Help Module Contents Files (Section Archives).[1]
    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 pin.svg

    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[2] 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 [3].

    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.

    Warning.svg

    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).[4]
    helpcontent2/source/text/scalc Help files specific to the Calc module.[4]
    helpcontent2/source/text/schart Help files specific to charts.[4]
    helpcontent2/source/text/sdraw Help files specific to the Draw module.[4]
    helpcontent2/source/text/shared Help files common to two or more modules.[4]
    helpcontent2/source/text/simpress Help files specific to the Impress module.[4]
    helpcontent2/source/text/smath Help files specific to the Math module.[4]
    helpcontent2/source/text/swriter Help files specific to the Writer module.[4]
    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 pin.svg

    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 pin.svg

    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

    Warning.svg

    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[5].

    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[5]

    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 pin.svg

    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 pin.svg

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


    References

    1. 1.0 1.1 This is a legacy remainder of an older StarOffice help structure (Installed Help Files on page 13)
    2. 2This help section was introduced for version 2.0. For legacy reasons, all of its help files reside inside the shared directory tree.
    3. For historical reasons, the contents for Draw are included in the simpress.tree file and the contents for Base (database) are included in the shared.tree file.
    4. 4.0 4.1 4.2 4.3 4.4 4.5 4.6 4.7 The subdirectorystructure of this directory has historical reasons.
    5. 5.0 5.1 More information about the build process for OpenOffice.org in general can be found on http://tools.openoffice.org/, http://ooo.ximian.com/hackers-guide.html, or on http://go-oo.org/wiki/index.php/Main_Page (archived version)