Taming the LibreOffice Help System

LibreOffice’s help system needs to evolve and be more effective for users.

LibreOffice’s help system was designed in 2003-2004 and released in 2005. Since then it has not evolved, except for the introduction of an online version hosted in a wiki server (and accessible from LibreOffice when the local help is not installed).

I worked recently to transform our ancient help system into a modern browser-based version. The partial result is available in the (temporary) website at https://helponline.libreoffice.org – please be advised that this is still work in progress.

The XML help pages are transformed into pure, almost static and responsive HTML. This approach has some advantages:

• Works in every browser
• Provides the current functionality of the help system
• Preserves the current development, help authoring, release engineering and translation process as it is
• You can read the help pages in your mobile phone or tablet
• It’s easy to add extra markup for better search engine indexing

The disadvantage is an increase in disk storage on the server.

Transforming XML into HTML for every browser

The help pages were designed when the minimal standard HTML was version 3.2 and, since then, many developments have brought us HTML5 in all major browsers. There is little advantage now to keep the current XML, and all of its designed functionality can be replaced and improved by HTML, CSS and JavaScript, for example, adding better navigation and multimedia contents.

Help system functionalities preserved

By using cascaded style sheets (CSS) and JavaScript, it was possible to emulate and preserve the functionality for the offline help system.

Mobile use

You may question why desktop software needs a help system that fits in a mobile phone or tablet. Actually, the online help pages can not only be opened by LibreOffice in your desktop browser, but also be a LibreOffice reference for other uses – such as simple web surfing and responses to a web search.

Searching from the web

Many of us are familiar with the fact that pages returned by a search mechanism depends on careful configuration of the HTML pages. That domain of search engine optimization (SEO) is an open avenue for improvements in the way we write help content and use the right configuration. Opinions and advises are welcome from the community. As a start,
the online help contains a set of microdata from schema.org under the TechArticle schema.

The road ahead for LibreOffice help

Still, a better solution for the LibreOffice help may be found. The main issue remains in finding a better tool to comfortably edit the XML, and make it easy to add multimedia and other content. Editing XML files is not a fun job for most of us, and is done in text editors or the old Help Authoring extension. Here two approaches are possible to ease the authoring job:

Improve the Help Authoring extension to handle the improvements for LibreOffice help contents (eg multimedia), or progressively move to pure HTML(5), to benefit of the hundreds of WYSIWYG HTML editors available either online and offline…

The Help Authoring extension is installed in LibreOffice to allow page editing in Writer. It has the advantage of performing lots of XML checks, but at the same time it becomes a challenge to modernize its set of BASIC macros, XSLT transformations and styles.

On the other hand, the strategy is to progressively add new pure-HTML tags in the XML DTD (Document Type Definition), slowly and carefully phasing out some of the complex markup of the current XML. As example, the current XML tag

<paragraph id=”hd_id3147331″ role=”heading” level=”1″ xml-lang=”en-US”>

can be replaced by well known HTML

<h1 id=”hd_id3147331″>

tag because we already know that role=”heading” and level=”1” uniquely means <h1> and xml-lang is not used any more. A partial map of XHP tags to HTML5 can be found here.

Conclusion

We want to make our help application more user-friendly, providing modern content and being a reference for LibreOffice on the web. The new online help layout is a step in this direction, but much more is to be done and the LibreOffice community is invited to help us. Get involved today!