Editing help pages directly in gerrit

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

• Wiki Home
• Development
• Design
• QA
• Events
• Documentation
• Website
• Localization
• Accessibility
• Marketing
• Diversity
• Wiki Help

• Documentation Home
• Official Publications
• Other Resources
• FAQ
• HowTo
• Macros
• Docs Development

Help pages can be edited directly in our code review tool gerrit.

This means that edition of textual XML is possible with automatic generation of a patch submitted to gerrit. Therefore, help files can be edited or corrected directly in master and with security and peer review provided by TDF security infra.

Such capacity will be extremely handy for ad-hoc correction of typos and linguistic mistakes we often do in English, as the LibreOffice project is developed by many non-English native speakers.

This capacity gives help writers a direct access to patching without having to download and build LibreOffice and its help. Although some Help XML knowledge is still needed to correctly write a help page, some of our skilled Native Language leaders and translators can now fix typos directly, without going through the lengthy process of reporting typos.

The original documentation of gerrit in-line editing is a work of our collaborator David Ostrovsky.

Knowing Help XML

The inline edition of help pages is textual and a knowledge on the Help XML (XHP) is mandatory for larger chunk of page edition. Please refer to the XHP references pages for more information.

Gerrit does not verify the XHP consistency when creating the patch (so please check the Document Type Definition). One common mistake found in help pages is duplication of id= attribute in <paragraph> that occurs very often when copying and pasting XML lines. All <paragraph> id= attribute must be unique in the page. On pasting lines, change the id= to a different value.

Identifying the Help file to change from online help

In case you have noticed a mistake or inaccuracy in one of the online help pages, you can start by identifying the correct XML file that needs fixing. The file name can be inferred from the address displayed in the browser URL bar.

Suppose the page you want to edit is displayed at this address: https://help.libreoffice.org/7.4/en-US/text/shared/guide/digitalsign_send.html (note that everything from the question mark was removed). The correct file can be extracted from the URL:

'source/' + 'text/shared/guide/digitalsign_send' + '.xhp'
which is:
source/text/shared/guide/digitalsign_send.xhp

Useful part of the URL on the online help website is highlighted

Getting started with Gerrit

Gerrit is a service to manage patches in LibreOffice source code. To get access to gerrit and to be able to submit patches, you must get a gerrit login. Please refer to this page on getting a gerrit account.

Inline Editing of Help pages

Follow the steps below

• Open the gerrit page and login with your credentials.
• Choose Browse > Repositories top menu. A long list of projects is displayed. Enter help in the filter box to display only the Help project.

Filtered list of LibreOffice projects

• Click on the Help project link to select it (or use this shortcut). The page below opens. Click on the Create Change button.

Click on the Create Change button.

1. Enter the branch name for the change. In most cases it will be master.
2. Enter the description of the change you are doing. This description will show in the patch and will tell the reviewer information about the patch. Click the CREATE button

Branch (master) and description of the change

Accessing the file for edition

• Click on the EDIT button

Click on the EDIT button.

• Click on the ADD/OPEN/UPLOAD button and enter the complete file path and name as indicated below (note that the field suggests existing file names as you type). Then click on the CONFIRM button

Click on the ADD/OPEN/UPLOAD button.

Add the file to the patch

• The gerrit text editor opens. It is a simple but handy editor for most purposes of XML text edition.

Help file opened in text editor

• At the top right of the editor, you see the CANCEL, SAVE and SAVE & PUBLISH buttons. Click SAVE. (Alternatively, if this is the only change you need to make, you can click SAVE & PUBLISH to skip the next steps and directly publish your patch for review.)

Text editor top-right buttons

• After saving your edit, you are brought back to the gerrit main patch screen, where your patch is displayed. You can edit the file further if needed, by clicking on its name in the list, or you can edit other files if they are all related to the same change. Once done, click on the STOP EDITING button to close the editor session.

STOP EDITING button

Publishing your patch to gerrit for peer review

Once you are done with editing the files, you must publish your change. Click the Publish Edit button to generate the patch. Initially, the patch is created as a "Work in Progress", i.e., not published to be reviewable by others. To submit it for peer review in gerrit, click another Mark as Active button that appears after you clicked Publish Edit.

Publish Edit button

XML validation

• Upon submission, your files are validated through a CI Jenkins job against xmlhelp.dtd
• If something is wrong, you'll receive a *-1* review from Jenkins asking you to fix it.
• We cannot understate the importance of a correct understanding of the Help XML syntax and semantics. A mistake in the XML will break the help build. The full description of the Help XML is available in these wiki pages. Do not hesitate to look into the XHP references pages to get the right XML syntax.