Documentation/Help Content

From The Document Foundation Wiki
Jump to: navigation, search

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.

Environment

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.

Extension installation

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 named Help Authoring in Writer and the template named xmlhelptemplate, which can be found in the Help category of the Template Manager window : File ▸ Create ▸ Template (or press Ctrl+⇧ Shift+N).

Additional files

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.

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.

See also