Editing help pages directly in gerrit
TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate
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
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 Gitiles view of the source/text directory and navigate to the file you want to change. You may also edit the Gitiles URL to directly jump to the desired file per the earlier advice on identifying the source XHP file.
- While viewing the XHP file, you should see an [edit] link at the top. Clicking this link will immediately create a new change in Gerrit with the file added. You will only see this link, if you are browsing the file at a branch, usually master. So the URL must include refs/heads/master
- Click on the EDIT button
- You may add more files to the same patch by clicking on the ADD/OPEN/UPLOAD button and entering 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
- Either after clicking the name of the first file or after adding a new file, the Gerrit text editor opens. It is a simple but handy editor for most purposes of XML text editing.
- 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.)
- 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.
Publishing your patch to gerrit for peer review
Once you are done with editing the files and making sure you have an informative commit message, 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.
Later, you can do as many further edits to your patch as needed before it is merged. After it is merged, you may not edit it as it has become a part of the commit history. Any changes after that require the creation of a new patch.
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.