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

This page will describe the steps to create new articles or modify existing ones in the offline and online help of LibreOffice, in its new presentation mode, with a modern browser.

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.

Environment

Warning:
DO NOT INSTALL OR USE the HelpAuthoring Extension. It will break the improvements done in New Help.

Retrieve the help files

Help files are on LibreOffice git repository. Therefore you need to have a git environment installed on your computer.

Command to retrieve the files

git clone http://anongit.freedesktop.org/git/libreoffice/help.git 
cd help

The files you will need in a first time are located in the source/text directory

Editing the files

Use your preferred text editor with support for UTF-8.

For Linux systems: Gedit, vim, Kate, Visual Studio Code, etc...
For Windows systems: Notepad++, Visual Studio Code

TODO: Review / fix below

Opening/Saving

Opening: To open a help file, in the Help Authoring menu, choose Open or select the 'help' file type in the file picker under File ▸ Open 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.
Saving: 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.

Help Authoring menu

Menu Help Authoring

Create help file: 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.
About: displays the version number of the extension
Set Document Root: selects the document as root file
Edit meta data: gives a title to the help file or leaves a comment. The Indexing button includes or ignores the file when running a search
Validate this help file: runs some checks on the xml structure of the file
Toggle l10n: sets the localize attribute on false:

localize="false" - which appears as par_id0202201317491162_NOL10N in the document

Assign ID: adds an ID identifier to the paragraph
Insert Comment: adds a comment in the file

<COMMENT>my comment here</COMMENT>

Insert Table: inserts a table in the document
Insert Link: inserts a link to another file
Insert Help ID: inserts a bookmark branch tag of the type

<BOOKMARK branch="hid/1234567" id="bm_id0202201317594049" localize="false"/>

Insert Index Entry: inserts tags marking an index entry

<BOOKMARKVALUE>Insert;Name</BOOKMARKVALUE>

Insert Extendid tip: 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.
Insert How to Get section: inserts a section named How To Get
Insert Image: inserts a link to a picture
Insert Section: inserts a section which name is the name of the section
Insert variable: inserts a variable, the dialog box names it

 <VAR ID="newvariable">

Transclude: incorporates another existing paragraph
Related topics section: 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 Help ▸ LibreOffice Help.

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.

Documentation/New Help Content