LibreOffice Help pages can now download example files

Following the introduction of You Tube videos in our help pages, I have enabled the capability of storing OpenDocument files in the help system.

Help authors can now add <object> elements with type="application/vnd.oasis.opendocument.*" where the "*" means "text", "spreadsheet", "drawing", "presentation", "math" and "database".

Since our help pages are mostly textual, it is not the best way to show how a given feature works. By having a real opendocument file available to download directly from the Help is a step to see a real example working.

The implementation of a opendocument object is simple. Just insert an <object> tag specifying the file location in the data attribute, the right type as a valid opendocument MIME type and an id that is a random string.

<object data="media/files/scalc/imtrigon.ods"

id="ods_id61521568603544" 

type="application/vnd.oasis.opendocument.spreadsheet" /> 

The result in the rendered page is an icon with a link to donwload the page:

https://help.libreoffice.org/6.1/en-US/text/scalc/01/func_imsin.html

just click on the icon to donwload and open the file. If your browser has the right MIME type settings, it can open the file directly in LibreOffice. The file in this example (imtrigon.ods) is a simple Calc file that can be updated easily with LibreOffice.

The intent of adding multimedia and other objects files is complimentary to the precise but often cumbersome textual description. Both are important in a help page. The textual description is a way to describe how a feature does work and the object file is the implementation of the description. When there is a discrepancy, then either the software has a bug, or the page needs a description update.

The OpenDocuments inserted in the help system work in either offline and online version of the new Help pages.

Happy open documenting!

Adding multimedia to the Help pages of LibreOffice

I have patched some pages of LibreOffice Help with a new feature: You Tube videos.

Now help content authors can create a video on the subject and insert in the page. The video can he hosted in an external server such as You Tube (tested) or any other  (not tested).

The implementation was done enabling the <object> tag in the stylesheet transform. In the old and offline the <object> tag was ignored:

<!-- OBJECT (UNUSED) -->
<xsl:template match="object" />


So now I enabled it in online_transform.xsl with

<!-- OBJECT -->
<xsl:template match="object"><xsl:call-template name="insertobject"/></xsl:template>

<xsl:template match="object" mode="embedded"><xsl:call-template name="insertobject"/></xsl:template>

and I handle the <object> in the insertobject template. The template can select what to do with each object type.You can see an example in the following page:

https://help.libreoffice.org/6.1/en-US/text/simpress/main0000.html

The video is added as a companion resource of the hep page, it does not intend to replace the correct writing of the hep pages.

The implications are significant. Not only a video can support the contents of the help page, but also other kind of objects can be  acesssed in the helppages.

For example, a help page on autofilter that has a table with data serving as example, can have an object of type spreadsheet inside the page and the user can click on it to open the example spreadsheet and see the live example.

The implementation of other kind of object is not finished but can be easy. In the case of objects like spreadsheets or text documents, the files can be placed in the media/ folder of the help.

Another implication when adding such richness in our help pages is the maintenance of the multimedia, given the fast improvements of the software.  Special care is needed not to add multimedia that depends on a specific release. Instead, the multimedia in the help should focus more generic use of the modules. For example, a tutorial on how to create a pivot table or to create a table of contents in a text document.

Happy multimedia.

Changing the target path for offline new help

This weekend I worked on a patch to build the new LibreOffice help where the offline version does not have the version number in its location and the online version does.

So I had to define a new param to the XSLTs to distiguish the offline and online paths. This affects the main transformation (online_transform.xsl) but also the get_tree.xsl and get_bookmark.xsl transforms.

Some tweaks on the makefiles, hacking existing ones. Module /sfx2/ had to be adapted to detect the right help available.

With the new patch, the version upgrade of the offline help will overwrite the current version, as it is wiith the old help. We keep the version in the path for the online help because we need to serve more than one version, so the server will have 6.0, 6.1, 6.2 ...

I still  look at the main stylesheet transform (online_transform.xsl) and want to refactor it by removing a lot of cruft from the old help ages.

Happy hacking.

Resuming blogging on my activities.

Last Friday I patched the new help of LibreOffice to fix a bug about the correct detection of the operating system passes as &System= in the URL.

It affects the usage of <switch> and <switchinline> with consequences on <case> and <caseinline> as well as the <default> and <defaultinline> inside the help pages (the xhp files).

I had to change the default / defaultinline to an new entity named DEFAULTSYS, shown every time the OS is not specified.

The logic is that is there is a specific usage of &System=, then the page must display the options of the parameter specified by &System=. It must also hide all option of DEFAULTSYS in the page.

If the page has option for <case select='sys'> but the OS passed is not an option of <case>/<caseiniline> then the DEFAULTSYS options must be shown.

For example, the URL pass &System=WIN and the options are for UNIX, then the contents displyed must be DEFAULTSYS.

Patch is: https://cgit.freedesktop.org/libreoffice/help/commit/?id=13098ccef163c813ae3e196511f44a16a6e73fdd