Reworking Special Tables in New Help.

Continuing the enhancement of the new help pages, I made some changes in the XSL transformation and CSS file to remove some special tables and sections. In this case I used CSS properties available in HTML5, such as display:flex; .

Many tables were used to position elements in the page. Depending on the CSS class of the table, the purpose of the table changes. Here are the predefined roles worked so far:

onecell: As the name says, the xml table has only one cell. The html table was replaced by a div and proper css, followed by a line break.

icontable: this type of table type is constructed when the first tablecell contains an image. The html table replacement is rendered row by row by a wrapping div with display: flex; attribute and internal divs for the remaining cells in the row.

howtoget: The section "How to get" has now a wrapping div with display: flex;  and flex-direction: columns; to stack the heading and contents divs.

Notes, Tips and Warnings: The special paragraphs were mapped into tables and now are mapped in divs with display:flex;

All divs are also associated with named classes, and therefore the CSS can be tweaked independently.

The remaining tables are left as is but will also undergo some cleanup in the near future.

Happy CSS tweaking!

Fixing the switchinline transform for Help

Last week I spend quite amount of time chasing a bug on the new Help XSL transformation (XSLT) to implement the <switchinline> tag of the Help.

The initial idea was to map the <switchinline> into a javascript <switch> which is a straightforward to implement, but since the devil is in the details, I had hard times to realize that I set the output of a XSL transform as html, and when it comes to javascript, assigning a string to the output of the transform brings many issues.

Specifically, I had the issue when approaching an output like

<![CDATA[case "MAC" : text = "]]>\

<xsl:apply-templates/>\

<![CDATA[");]]>

with the output of the <xsl:apply-templates/> call resulting in strings with carriage return, apostrophes and quotes, which can't be put inside a javascript string unless adding a post processing to remove at least the LF and CR characters. So I implemented the <switchinline> inside a outer wrapping <span> and each each <case> content output into an inner <span> tag.

<span hidden="true" id="{$auxID}">\

<xsl:apply-templates/>\

</span>

Then I played with the "hidden" attribute, emulating the javascript "case" with logic inside the wrapping <span>.

New LibreOffice Help is also an UNO Extension Package

Today I finished a patch for LibreOffice 6.1 that displays the new Help when it is installed as a UNO extension package.

The patch consider the extension valid when the extension is installed (from  XPackageInformationProvider service) and the extension version matches the product version. When both situations are true, LibreOffice opens the HTML help pages from the extension in your default browser.

The fall-back logic implemented for LibreOffice help activation is now:

1. The extension help (this one). If not,
2. The new help in distribution package format (when it becomes available). If not,
3. The old, ancient local help. If not,
4. The new online Help.

The extension identifier is a critical parameter and is formed with the <locale> of the user interface. No big deal, the identifier will take the shape of <locale>.help.libreoffice.org.

The extension can be assembled from the offline build of the new help. Pass the param --with-help=html to your autogen.input and build the help. Then zip the files needed for your locale.

Preliminary tests  indicates that the extension will be of size above 12MB per language. It contains all necessary files for autonomous navigation, that means, all internal links are reachable within the pages of the extension. Media files were added too.

For the next LibreOffice 6.1, you can test master build only and download a temporary Help package from
https://helponline.libreoffice.org/Help_en-US_6.1.oxt

Enjoy!

Doubling your notebook clock when compiling LibreOffice

I bought a $15 "BMW"

The "BMW" let me switch the "turbo" mode of my LibreOffice compilation. Normally my Dell Vostro i7 takes 5 or 6 hours compiling LibreOffice with the internal cooling system, too weak to push the heat out of the notebook case.


From a trottled 1,2GHZ in all 4 cores to 2,9 GHz. Now my compilations takes around 2 to 3 hours.

A cheap overclock indeed.

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!