Documentation/Help

From The Document Foundation Wiki
Jump to: navigation, search

The easiest way to edit the LibreOffice Help is to use the HelpAuthoring extension. The extension adds new commands to Writer specific to the help page format.

Setup for the LibreOffice Help editing

Documentation for help editing

Documentation for the understanding, authoring and editing of help can be found in Understanding, Authoring and Editing OpenOffice.org HELP (PDF).

An online version is available.

HelpAuthoring extension

To install the extension, follow these steps:

Now when you open Writer, you should see a new Help Authoring menu and a Help Authoring toolbar

HelpAuthoringToolbar.png

When you use the Help Authoring for the first time, you need to set the Document Root (using Help Authoring ▸ Set Document Root...). The Document Root is the source/ subdirectory in your clone of the help git repository. You have to set it only once, later it is remembered in the configuration. Also, HelpAuthoring-3.1.1.oxt and later warn about empty Document Root, and force you to set it.

Im-jabber.svg

Note:
When using LibreOffice with the Help Authoring extension, set your locale to English (USA) to avoid interference of locale-dependent settings (spell-checking, autotexts, currency, numbering, etc...). To change the locale go to Tools ▸ Options ▸ Language Settings ▸ Language and set the Locale Setting to English (USA) in the listbox.

Sources of the Help with git

The sources of the Help are in git. If you have gerrit already configured, then you can do:

git clone ssh://logerrit/help

Or alternatively you need to do:

git clone git://gerrit.libreoffice.org/help

once. From then on, you work with the git repository the normal way:

  • To get the newest strings, do git pull -r
  • To send your changes for approval, push to gerrit. Please see later in this page how to do it.

Read How to setup gerrit the first time, and How to send a patch for review. If you have trouble setting up, please contact the developers at #libreoffice-dev connect via webchat channel on freenode, they will be glad to help you! th

Sources of the Help as packed archive

Admittedly, git is the safest way to have the latest help source code. But if git is not a solution for you, you can download the Help source file as a tarball and uncompress it in your working directory.

To download the latest help source code look for the latest version in this page

http://download.documentfoundation.org/libreoffice/src/X.Y.Z/ where X, Y and Z must be replaced by the most recent version. For example, as of today (May 24th, 2017) X.Y.Z is 5.4.0 .

Editing the Help

A short manual describing how to author the help content is available here.

How to find the file to work on

When you have the sources of the help, and string you want to change (like to change the "wide variety of options" on https://help.libreoffice.org/Writer/Writer_Features#Designing_and_Structuring), do:

cd help
git grep "wide variety of options"

This will return you:

source/text/swriter/main0503.xhp:<paragraph role="paragraph" id="par_id3147239" xml-lang="en-US" l10n="U" oldref="10">$[officename] offers ...

which means this text is in source/text/swriter/main0503.xhp .

How to change it

Using the extension Help Authoring

Choose in the menu Help Authoring ▸ Open Help File, navigate to source/text/swriter/main0503.xhp, and choose Open. The help file will open in a new window.

Now do the changes you need, like a change "options" to "possibilities", and choose Save from the toolbar. Choose Use Help (xhp) Format when you are asked about the format to use - you'll be notified that "Validation finished.", and then it will be saved.

Main0503xhp.png

Using the ordinary text-based editor

Practically any text editor is able to open the file .xhp (for example, it is Kate in KDE, gedit in Gnome, or Notepad2 in Windows. You may want to use vim or any professional xml-editor).

Gnome-dialog-warning.svg

Warning:
The text-based editor must support files in UTF-8.


  1. Open a Help file in the menu File ▸ Open or by using Open with... function from a file manager (for example in KDE, right-click on the file and select in popup menu Open with... ▸ Kate).
  2. For the reason that files may be very big and have a large number of xml-tags, you can use the find by file (usually Edit ▸ Find... or Ctrl+F).
  3. Make the necessary changes (if you are not confident with xml-tags of help files, make sure you have not touched them).
  4. Save the file.

This method is good when we need to make minor changes without touching the xml-tags, for example, to correct a typing error.

How to verify changes

The easy way

You can use Firefox or Chrome browsers to render your Help page, with some limitations.

Open the page File ▸ Open file... and navigate to help/source/index.html . The Help default page opens.

on the URL bar of the browser , add after index.html ?page=smodule/path/to/page.xhp

Example: file:///home/olivier/tmp/help/source/index.html?page=swriter/main0000.xhp

The help page main0000.xhp is displayed


The hard way: build LibreOffice

If you make changes or create a new page for Help, it is good idea to check how it will look in the interface. You must build the Help of LibreOffice.

For the first time you need to build LibreOffice. In the future, this can be done from time to time to update the version. More information about the build of LibreOffice can be found on these pages: for Linux, for Windows, and for macOS.

Use the option --with-help for autogen.sh when you build LibreOffice:

./autogen.sh --with-help

It will download and build files into the folder helpcontent2. In the future, to check Help file changes, they can be placed (following the relative paths) into helpcontent2 and built with help command make in it. Files for run can be found in source_folder_of_Libreoffice/instdir/program/ folder. Open LibreOffice by running the file soffice or swriter and press F1 for open Help.

Note: The LibreOffice build takes 3 to 8 hours, depending on the capacity of your computer. Help build takes about a minute.

How to send it back for approval (via gerrit)

Gerrit is a tool that allows easy review of changes that go into LibreOffice. Follow the instructions on How to send a patch for review, the Help uses the same workflow.

If you aren't able to get gerrit working and are getting an error

fatal: remote error: access denied or repository not exported: /help

use the following command

git config remote.origin.pushurl ssh://logerrit/help

if you then get a gerrit error about not having a Change-ID, then run this command in the help root folder

cd .git/hooks && ln -s ../../.git-hooks/* ./

If that command does not help, follow the advice in the error "Hint: To automatically insert Change-Id, install the hook:".

See also