This page will describe the steps to create new articles or modify existing ones in the offline help of LibreOffice.
Help files are in .xhp file format, they are xml files which, inside LibreOffice, are transformed in HTML file format. Therefore they will contain all the information necessary to this transformation. LibreOffice is not a xml editor, styles and other elements are used to match the xml tags. These elements are added via Basic macros.
- 1 Environment
- 2 Retrieve the help files
- 3 Editing the files
- 4 Unused/Ignored Tags and Attributes
- 5 Make Images Appear
- 6 Test Changes in LibreOffice Help Viewer
- 7 See also
You will need to install an extension, a template and two more files to be able to work on the help files.
See the Detailed instructions how to download and install the extension.
Download the extension named HelpAuthoring.oxt. Install it using the Extension Manager:
- click on Add at the bottom of the dialog
- navigate to the extension on your computer
- click on Open.
The extension will add a menu namedin Writer and the template named xmlhelptemplate, which can be found in the Help category of the Template Manager window : ▸ ▸ (or press Ctrl+⇧ Shift+N).
To be able to locate easily the files to modify or to create, there are two files to install, the first one will create an index of the help files, the second one will display help tags hidden in the files.
- download the maintransform.xml file and replace the existing one in install_directory/libreoffice4.x/help
- download the allfiles.tree file and copy it in install_directory/libreoffice4.0/help/en. This file doesn't yet exist, you need to add it.
Retrieve the help files
Help files are on LibreOffice GIT repository. Therefore you need to have a git environment installed on your computer. You can copy the help files anywhere on your computer, the extension will create a helpauthoring.cfg file in the user directory which will keep the path.
Command to retrieve the files
git clone http://anongit.freedesktop.org/git/libreoffice/help.git my_directory
The files you will need in a first time are located in the source/text directory
Editing the files
There is a full documentation about the help structure and how to edit it, but here are some basic instructions to begin. The full documentation needs first to be updated before made available online.
- To open a help file, in the Help Authoring menu, choose or select the 'help' file type in the file picker under ▸ and navigate to the .xhp file you want to work on.
- The document opens in Writer. Some information are not displayed like the par_id but are noted with a small yellow mark. It is mandatory to use the styles provided by the template, any other style will be ignore when the file will be parsed.
- When, saving the document, a check of the file is run. It doesn't check the syntax extensively, but make sure that there is no empty paragraph or that id are added.
Menu Help Authoring
- : creates a new .xhp file based on the template. If the template is not found, the file can't be created and an error message is displayed.
- : displays the version number of the extension
- : selects the document as root file
- : gives a title to the help file or leaves a comment. The Indexing button includes or ignores the file when running a search
- : runs some checks on the xml structure of the file
- : sets the localize attribute on false:
localize="false" - which appears as par_id0202201317491162_NOL10N in the document
- : adds an ID identifier to the paragraph
- : adds a comment in the file
<COMMENT>my comment here</COMMENT>
- : inserts a table in the document
- : inserts a link to another file
- : inserts a bookmark branch tag of the type
<BOOKMARK branch="hid/1234567" id="bm_id0202201317594049" localize="false"/>
- : inserts tags marking an index entry
- : insert tags marking extended tips. The dialog box asks whether they are hidden. If you answer by YES, it will appear in the UI but not in the help.
- : inserts a section named How To Get
- : inserts a link to a picture
- : inserts a section which name is the name of the section
- : inserts a variable, the dialog box names it
- : incorporates another existing paragraph
- : inserts a 'Related Topics' section that links to other help articles. Usually placed at the end of the page.
Unused/Ignored Tags and Attributes
If you are editing the .xhp help files in a text editor, the following tags and attributes are ignored.
- The <history> tag found in the <meta> tag
- The l10n and oldref attributes of the <paragraph> tag.
- The <alt> tag within the <image> tag
- The width and height attributes of the <image> tag.
- The status attribute of the <topic> tag.
Make Images Appear
Images shown in Help are found within LibreOffice's icon theme files and in order to get them to appear within the authoring tool, you would need to create a symbolic link between the helpauthoring tool's assumed location of images (i.e. [help repo base path]/../default_images) and a folder that contains the galaxy icon theme. The galaxy icon theme folder can either be through having a copy of the LibreOffice core git repo (found in icon-themes/galaxy/) or alternatively by grabbing the galaxy icon theme zip file that comes with an installation of LibreOffice (e.g. /opt/libreoffice/share/config/images_galaxy.zip, C:\Program Files\LibreOffice\share\config\images_galaxy.zip) and extracting it into a folder.
Here is the Linux command to create the symbolic link with the core git repo if the help repo was located at ~/help
ln -s ~/core/icon-themes/galaxy ~/default_images
If the help repo is located in the helpcontent2 folder of the LibreOffice core repo, then use this command to create the symbolic link if the core repo is located at ~/core
ln -s ~/core/icon-themes/galaxy ~/core/default_images
Test Changes in LibreOffice Help Viewer
It is possible to view the changes you make to the xhp help files within LibreOffice help viewer's, which is accessible by pressing F11 or▸ .
Without the LibreOffice Core Repo
On Linux, open the script found at
helpers/zip_help.sh and modify the last line to point to the folder in your LibreOffice installation that contains the help files (it normally ends in
help/en-US/). Once modified, execute the script in the terminal and it will create the necessary packaged .jar help files and move them into the defined folder. If the script isnt modified, the .jar files will be left in the
source/ folder and you can manually copy them to the LibreOffice help folder.
With the LibreOffice Core Repo
If you have the LibreOffice core repo, it has a blank helpcontent2 folder which you should put the LibreOffice help repo in, and with the help repo in that folder, you can run the
make command and it will build the help files in
core/instdir/help/en-US/, so that you can test them within your built version of LibreOffice.