The LibreOffice Help underwent a radical change since verison 6.1 and is now displayed in the system browser.
- 1 Introduction to LibreOffice Help editing
- 2 Documentation for Help editing
- 3 Editing LibreOffice Help Files directly in gerrit
- 4 Editing LibreOffice Help file in your local computer
- 5 Editing the Help
- 6 Understanding LibreOffice Help file structure
- 7 How to verify changes
- 8 How to send it back for approval (via gerrit)
- 9 See also
Introduction to LibreOffice Help editing
LibreOffice Help pages are text pages in XML (Extensive Markup Language). Here is a summary to help you in contributing to the Help project:
|My current skills||Simple tasks (typos, grammar, linguistics)||Medium tasks (update with respect to current version, menus reordering, better formatting)||High volume (new pages on features, add images or multimedia, many files involved...).|
|I have a gerrit account, I know XHP||Edit the XHP file directly in gerrit||Can be hard to edit in gerrit, avoid.||Even more hard, avoid.|
|I cloned the Help submodule, I can test locally, I have development skills and I know XHP||Edit the XHP file locally, make, test and submit a patch||Same as simple task||Same as simple task|
|None of the above, I'm not skilled in development, I have no skills in XML, but I'm good at documenting.||Send mail to documentation list. Add as much info as possible, even better if you add the page to fix.||Open an bug in bugzilla to report defect. Add as much info as possible, even better if you add the page to fix.||Open a bug in bugzilla to report defect/enhancement. Attach files with proposed contents. Add as much info as possible, even better if you add the page to fix.|
Documentation for Help editing
A minimal knowledge on XML or even HTML is necessary. The XML for LibreOffice Help (also known as XHP) is not hard to catch if you know XML basic concepts. It will be useful for small changes until you get more familiar with the do's and don'ts of the LibreOffice Help files.
Documentation for the understanding, authoring and editing of LibreOffice Help can be found in online version. These wiki pages are under revision and enhancement and will follow the development of LibreOffice Help resources.
The most important wiki page for XHP is page 2: XHP Reference.
The original PDF book is available: Understanding, Authoring and Editing OpenOffice.org HELP (PDF). Note that this book is now outdated.
Editing LibreOffice Help Files directly in gerrit
A complete page on the subject is available here
Editing LibreOffice Help file in your local computer
Sources of the LibreOffice Help with git
The sources of the LibreOffice 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 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
How to change it
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).
- Open a Help file in the menu ▸ or by using function from a file manager (for example in KDE, right-click on the file and select in popup menu ▸ ).
- 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 ▸ or Ctrl+F).
- Make the necessary changes (if you are not confident with xml-tags of help files, make sure you have not touched them).
- 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.
Understanding LibreOffice Help file structure
Th LibreOffice Help file is composed of several mandatory parts. Look at this guided example.
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
help/source/index.html . The Help default page opens.
on the URL bar of the browser , add after
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
autogen.sh when you build LibreOffice:
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
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. The exact steps are in the article on submodules.
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:".