Thursday, April 5, 2018

Direct edition of help files in Master repository: A huge improvement

One on the main issues we have when it comes to add documentation in LibreOffice Help files is the amount of work it takes to update a help file.

Currently, the help author or maintainer has to get a full build of LibreOffice, plus the help submodule and go thru all the steps of a build to display a help page. Although the Help submodule can be build individually, it requires a build of LibreOffice to display the result.

Yesterday our friend buovjaga pointed me that gerrit (https://gerrit.libreoffice.org) has an inline editor of files in git.

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-Eglish 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 gerrit inline editor  will not render the page in html or other rich text display. It is pure textual editing. Rich text rendering is still being in the drawing board of the documentation team developers.

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

Update: The complete tutorial on how touse the gerrit editor for libreOffice help pages is in this link: https://wiki.documentfoundation.org/Documentation/GerritEditing

Happy help patching!