Editing help pages directly in gerrit

From The Document Foundation Wiki
Jump to: navigation, search

Help pages can be edited directly in 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 will let help writers a direct access to patching without having to download and build LibreOffice and its help. Although the Help XML knowledge is still need to correctly write a help page, some of our skilled NL leaders and translators can now fix typos directly, without passing by the lengthy process of reporting typos.

The original documentation of gerrit in-line editing is a work of our collaborator David Ostrovsky and the page is https://gerrit-review.googlesource.com/Documentation/user-inline-edit.html

Knowing Help XML

The inline edition of help page 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 (check the DTD) when creating the patch. One common mistake found in help pages is duplication of "id=" attribute in <paragraph> that occurs very often when copy & paste XML lines. All <paragraph> "id=" attribute must be unique in the page. On pasting lines, change the "id=" to a different value.

Getting started with Gerrit

LibreOffice gerrit is located at this address: https://gerrit.libreoffice.org

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. Click on the Projects link in the top left of the screen, then List link below. 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 (it matters to click the project name at the left, not (gitweb) link on the right side). The page below opens. Click on the Create Change button. All other fields are greyed.
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.
Name and description of the change

Identifying the Help file to change from the new Help Online

We give the example where you have noticed a mistake or inaccuracy in one of the new help online pages. The correct XML file is displayed in the browser URL box, as shown below.

Suppose the page you want to edit is displayed at this address: https://help.libreoffice.org/6.1/en-US/text/shared/guide/digitalsign_send.html. 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
New Help Online screen

Identifying the Help file to change from Pootle

We give the example of a change suggested by one of our community translator. The text is displayed in the Pootle screen as below:

Pootle screen
  • The Folder is indicated by shared/guide.po, ans therefore the file path is source/text/shared/guide/
  • The help page file name is digitalsign_send.xhp.

Accessing the file for edition

Now that we know the Help file to edit, we can add it to our patch in gerrit. Click on the Edit button in the Files section and then the Add button and enter the complete file path and name as indicated below. Then click on the Open 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
  • On the top of the browser page, you see the Close and Save buttons for immediate use.
  • After saving your edition and closing the editor, you are brought to the gerrit main patch screen, where your patch is displayed. Click on the Done Editing button to close the editor session.
Done Editing button

Publishing your patch to gerrit for peer review

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

Publish Edit button

What else?

  • We cannot minimize 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.