Exporting LibreOffice Guides to XHTML (Part II)

In the previous blog post I explained the reasons and some issues on exporting LibreOffice Guides to the xHTML format. Now it is time to give more technical details. 

I choose to use the extension writer2xhtml available in the Extension website, because the produced HTML5 look less cluttered than the native XHTML export. Nevertheless there it will be necessary to add some extra HTML5 lines, to load the CSS and a Javascript file.

Invisible changes in chapter files that can go upstream

There are some changes that should go upstream, because it does not change the resulting PDF or ODT book layout.

Each image must be anchored “as character” in the document. The image becomes a character and must be single in the paragraph. The paragraph must be centered in the page, using a style that aligns in the center, for example, the “Figure” paragraph style. The image caption paragraph must have style “Caption”. The wrapping frame that holds the image and the caption must also be anchored “as character” in a paragraph with style “Figure” as well. This arrangement is transparent when producing ODT, PDF and HTML5 documents.

Tips, Notes and Cautions headings use graphics as bullet. Many of these paragraphs have the bullet enabled by direct formatting and this is invisible to the user in LibreOffice, but will show when exporting to HTML5 with an ugly black circle.

Recommended changes that should go upstream

Create a table style, or copy it from the table in the copyright section. Name the style as you want, custom table styles are stored in your user profile. Apply this style to all tables in the chapter. Open the table properties of each table and set alignment to “Centered”, and table width in 90%.

Remove cross references to pages. For example, “See figure 12 on page 30”. At best, use the “above” or “below” in the reference.

Add the sections described in 2,3 and 4 below.

Changes in the working copy of the chapter file.

The original chapter file is optimized for a book format, we need to prepare it for exporting to HTML5 where pagination is different, mostly by smooth scrolling. This involves steps but will not change the chapter contents, only the layout and some formatting

1. With the images anchored as explained above – a step that may require manual work – move the caption above the image. This can be quickly done by placing the cursor in the caption text and pressing Ctrl+Alt+Up Arrow, to swap the caption paragraph with the image paragraph. Some chapter have dozens of images so it will be nice to have a script to bulk execute this swap.

2. Wrap the top LibreOffice logo in a Section named “SEC_LOGO”.

3. Wrap the Guide name in a section named “SEC_GUIDE”.

4. Wrap the chapter title in a section named “SEC_TITLE”.

5. Delete the existing table of Contents.

6. Select the text from the copyright heading to the end of the chapter and wrap in a section named “SEC_DISPLAYAREA”. Ensure you leave some empty paragraphs after the end of the section.

7. On the bottom of the chapter, after the SEC_DISPLAYAREA section, add 6 new empty sections: SEC_TOC, SEC_BOOK_TOC, SEC_SEARCH, SEC_IMPRINT, SEC_DONATION, SEC_NAV. You can create these 6 sections in an empty document and load it as Autotext, so all section can be inserted in a single command using Autotext (Ctrl+F3).

8. Insert the chapter table of contents in the SEC_TOC section.

9. Change the template of the chapter to the provided template odf2htmlv2.ott.

10. Review the ordered and unordered lists in the chapter. The new template may highlight the spurious bullet and numbering inserted by direct format, and as explained above, is very hard to detect in the original ODT file. Some of these list direct formatting may also be detected in the HTML5 output.

Save your working copy.

Exporting to HTML5

The extension writer2xhtml adds a toolbar for exporting on a click. The extension allows some customization, not used here. The export used “original format” style and 115% font size.

The export is very fast and gives no choice to change the export name, so the exported file has same file name and html as file extension, overwriting existing files with same name and extension.

By default the exported file name opens in the system browser for inspection. The result is not yet what we want, we must apply specific CSS and Javascript for rearranging the layout of the sections. The se files are added in the HTML5 output juste before the </head> closing tag.

<link href="guideposition.css" rel="Stylesheet" type="text/css">
<link href="guideformats.css" rel="Stylesheet" type="text/css">
<script type="text/javascript" src="GS70.js" defer></script>

The CSS files

Two extra CSS files were created, one is guideposition.css and manages the sections position in the page, and has provision for handling other screen sizes such as in tablets. The second CSS file is guideformats.css that contains rules to override some attributes such as lists, fonts, font-size, colors, margins, padding and more of the sections.

The Javascript file

This file fills the empty sections we added at the end of the chapter. Contents for donation, guide table of contents (jump between chapters), a legal imprint, a search form (to be implemented) and more. The javascript file is common to all chapter and is custom to the guide.

Conclusion

Exporting the LibreOffice Guides to HTML is another way to offer a rich contents to the public. Guides in HTML format can be installed in servers of schools, libraries, colleges and corporations alongside with a PDF copy, to support a migration project.

The rich set of features of Writer, while allowing the creation of wonderful documents, is also source of concern not only when exporting to formats that are less flexible that ODF, but also to manage the excess of freedom. The changes recommended and the detection of hidden direct formatting in lists are examples. It becomes clear that a set of sanitizing scripts can help to remove spurious formatting, unused legacy styles, detect unwated extra styles and adjust the objects in the documents.

When handling the full set of guides it is easy to dream of an office suite that can execute some "wishes" like "anchor all images as characters and center in line", "change position of caption  in all frames to top", "format all tables with style 'guides' and align to center"... but that is for an office suite of the next generation!!!.

Partial results of all this work can be visualized below. 

The getting started guide in HTML format.

The javascript file

The css files: css1 and css2

The odf2xhtml.ott template

The writer2xhtml extension

 Happy documenting!!!!

 

 

Exporting LibreOffice Guides to HTML (Part I)

LibreOffice is an open source office suite full of tricky secrets. One of my favorites is the possibility to export a text document to XHTML or HTML5, both are W3C standards supported by most modern web browsers.

But you, the reader, will certainly ask: If I have the Guides in ODT and PDF file format why do I need another format? Why spend energy adding another medium for the LibreOffice Guides? 

There are advantages and drawbacks for the endeavor. On the thumbs up side, the community get a way to read the guides without actually downloading the PDF or ODT file and contents can be accessed with the browser's navigation tools (including bookmarking and more). One example is the current ODF Standard files exported to XHTML, available at the OASIS website.

A second advantage is that (X)HTML pages can be crawled and indexed by search engines robots and the LibreOffice Guides can be found on the search results pages of Bing, Google, DuckDuckGo and others.

Another exciting possibility for distributing the guides in (X)HTML format is that they could be installed on the intranets of schools, colleges and universities, public libraries, also community, public administration and private company websites. The files are static and don't need a server side scripting languages such as php or asp. Distributing the rich contents of the LibreOffice Guides in a browser readable format will add value to every LibreOffice migration project.

One critical factor in the success of a LibreOffice migration project is how quickly users can transition to the new software and having readily available, easily accessible documentation in different forms should not be underestimated.

How difficult is to convert the Guides to an (X)HTML format?

My experience is that there are some work to do in the ODT side, and some work on the exported (X)HTML. The nice part is that these changes are small and can be partially automated.

LibreOffice has an interesting XHTML export filter. The developers did their best to preserve formatting and document fidelity between different rich text output formats. A second tool I tried is the nice extension writer2xhtml, which also have interesting features.

However reading contents in a browser (or even a tablet and a mobile phone) requires scrolling instead of the usual page turning, as in a printed book.

The layout of the document's content must be adapted to the browser's navigation actions. This requires the layout to be adjusted for on-screen viewing. Besides, it is interesting to also adapt the contents to tablets and perhaps mobile phones.

Luckily, all elements for navigation exist in the ODT file, they are just in the wrong position when exported to XHTML. The approach is to wrap these elements in sections with specific names. After being exported to XHTML these sections are mapped in <div id="name">...</div> and can be accessed by both a CSS and Javascript for pagination and layout.

Here is one layout among many alternatives, for a simple export of our Guides to a browser page layout.

Besides the existing sections in the chapter, we can add other blocks with content of interest, for example a donation section a search form for either an external or internal search, such as Xapian and Omindex.

In the next post, I'll describe the changes needed in the Guide templates and discuss some of the alternate approaches for the task.

Stay tuned!

A better LibreOffice than LibreOffice

Turning LibreOffice users into happy LibreOffice users.

 
After readings and advises from other IT directors, one of my customers and strong supporter of LibreOffice, noticed that just switching programs and teaching user to avoid pitfalls in interoperability is not enough for a smooth migration, and something more than following the migration best practices has to be done for a successful switch. He then asked me to deliver a better LibreOffice than LibreOffice.

Challenge accepted. Together we started to investigate the needs of his organization, a civil company with strong military ties and with significant part of the workforce serving the military. We discovered a set of employees with repetitive tasks, usually performed by reusing old documents and updating them. The straightforward solution was to define a set of document templates and deploy it in the user computers.

But that was not enough. LibreOffice templates are accessed by a bunch of clicks with dialogs navigation, a sequence that needs to be memorized. Besides, templates dialog covers all kind of documents types and more clicks to narrow the selection. There had to be some easier way to get a brand new document from a corporate controlled template. Also, my customer also wanted to let a fingerprint in the solution and he wanted the solution to bear the company logo when user access it, including the high ranked military.

The solution was to create an extension that added a new menu to LibreOffice, specially crafted to address the needs of the workforce and help them do their job as quickly as possible.

So we packed the templates, a Basic macro needed for their document handling in an extension. The Basic macro was used to create a simplified template dialog, allowing a 2-click selection and other internal document handling macros. All new features are accessed from the top menu and a specific toolbar, with icons representing the company brand.

Thanks to the extension mechanism, the “better LibreOffice than LibreOffice” became a reality. The extension used all nice features of versioning, updating, as well as easy of deployment and maintenance. A few days after the news were spread, other departments such as engineering, legal, contracts, human resources and others asked to include their templates into the solution, turning more and more users happy to use LibreOffice.

Happy extensioning!

New Help: Copy BASIC and PYTHON code to Clipboard on a Click

The next release for LibreOffice will have a small but handy improvement for every macro developer, either experienced or beginner.

Hover the mouse on BASIC and Python code in the new Help pages and a tip shows that when you click your mouse, the code exerpt is copied in the system clipboard. You can paste in the BASIC IDE (Integrated Development environment) or any other text application in your system.

With this little feature, you save time of typing the exerpt to test in your IDE or document. Another alternative was to use a collateral file, however, collateral files with embedded macros is likely to trigger security warnings in most LibreOffice installations. Just copying the fragment is easier.

Happy Basic macro programming!
Happy Python macro programming!

Report on the New LIbreOffice Help Pages Online Editor

The Online Help Editor is getting a shape

I have improved and fixed a bit the XHP editor, and changed the page address:

https://newdesign.libreoffice.org/help_editor/index.html

 The editor is still work in progress, but starts to become interesting for creating and editing Help pages.

What's new

• Mike Saunders implementation of the autocompletion of XHP tags for Codemirror editor.
• The left and right panes are now fixed in browser screen and scrollable,
• The right pane uses 99% of the current Help transformation rendering, plus
• some visual debug information left intentionally to help Author in adjusting <embed>s, <image>s and <link>s . 
• You can now open a Help page directly from the interface. 

• The help page is normally source/text/AAA/BBB/myHelpPage.xhp  
• Type /AAA/BBB/myHelpPage.xhp in the text box and click Open File to load in the editor. 
• Press Render page to see it on the right. 

• A set of buttons with XHP snippets to shorten editing workload: 

• For <paragraph>s, <note>s, <heading>s, <emph>s, <menuitem>s, etc... select the raw text or contents and click the corresponding button. The raw text will be wrapped with the opening and closing tag. For paragraph-like contents, an unique id will be created automatically, a feture required for translations. 
• Other snippets builds fragments of XHP tags, such as <table>s, <tablerow>, <list>s, <section>s, and more.
• Just play with and do not forget to render the page on the right. 

Restrictions

• The editor works with Firefox only. Issues with Chrome and Edge. Other browsers not yet tested.
• Saving files not implemented. However you can copy the editor contents and finish the patch in you preferred editor
• More XHP checking are under development, specially id's unicity and DTD checking
• If you get a blank page on the right, this is because you hit a bug in the browser transformation. Unfortunately debugging the browser transformation is very hard, support is almost none.

Invitation for developers and testers

• You are invited to test the editor, report bugs and suggest improvements.  
• The user interface is simple HTML and Javascript. If you have skills in these technologies you are a potential developer for the editor, but we know that PHP will be the right tech choice in near future.  
• The source code is in the dev-tool repository. 
• To clone the dev-tool repository : 
•  git clone https://gerrit.libreoffice.org/dev-tools dev-tools 
• The editor is in dev-tools/help3/html/ 
• If you have a web server working in your computer (Apache, Nginx, etc...) you can run the editor locally: create a link between the web server root and the editor. For example, under Debian-like Linux: 
• sudo cd /var/www/html 
• sudo ln -s help-editor /dev-tools/help3/html 
• and point your browser to http://localhost/help-editor 

Seeking Help and discussion on the editor

Please use the documentation list, the developer list and our IRC channels to get in touch with the development of the editor. 

Ackowledgements

The Javascript editor used is CodeMirror and was carefully selected by Mike Saunders who also set the initial confguration for working with XML and our XML dialect XHP, as well as configured the autocompletion features.

The XHP snippets were originally designed for the KDE Kate editor and ported to the online editor.
 

Proposed XHP Extensions

After significant amount of time spent writing and fixing LibreOffice Help pages (XHP), I came to conclusion that the LibreOffice Help XML (XHP) is a powerful markup but a bit too hard to master for newcomers and easy to have errors and mistakes slipped in files. Some of its complexity are not absolutely required so I wrote a wiki page suggesting the implementation of XHP extensions, aiming to make life simpler for adding and reading XHP contents textually (markup).

Please note that in any case the current markup is affected, so it will preserve the legacy contents as well as the current translations. For example, the new markup for 'tip' paragraph should be

<tip id="123456" localize="true" xml-lang="en-US"></tip>

So it can replace

<paragraph id="123456" localize="true" role="tip" xml-lang="en-US"></paragraph>

Yes, it is a trivial change but I hope it will make reading easier for all.

Handling of the XHP extensions will be in the XSLT transformation and it will be patched accordingly, as well as the DTD, wiki documentation on XHP, and string extractors for Pootle.

The wiki page is

https://wiki.documentfoundation.org/Documentation/Proposed_Extensions_for_XHP

And comments are welcome, do's and dont's, thumbs up or thumbs down.

Happy help writing.

Hovering icons in Help pages

Last week I implemented a feature in our help pages using a modern CSS (Cascade Style Sheets) technique when hovering the mouse pointer on icons displayed in the page: the hovered icon is enlarged twice its size.

Almost every icon in the help pages are sized 0.22 in x 0.22in (~0,5cm x 0,5cm) which is sometimes a bit too small, especially with minimalistic designed icons such as the Colibre icon family. Enlarging the icons helps user to visualize and since it was implemented in CSS, there was no need to change the icons dimensions in the source help pages.

To see it working, please check this page and hover the mouse on icons.

Normal size

Enlarged on hover

Comments and suggestions are welcome.

Happy icon hovering!

Compress Images

I just submitted a patch for LibreOffice Help to document the Compress Image feature.

The Compress Image feature is active when an image is selected and you want to change the data size of the image, at the expense of a optional and controllable loss of quality set in a dialog box.

The Compress Image dialog

Compressing is useful if you insert a high resolution image in a document. For example a 4000x4000 pixel image in bitmap format (BMP) is approximately of  48MB size, which can turn you document edition hard in constrained-resources computers. By compressing the image with the right format and quality index you can reduce the size of the picture with no loss of visual quality and have the document file much lighter to edit.

Enjoy!

When nothing else works...

Few things in life makes me unhappy than a unoptimal or broken system. When my machine does not work at its best I start to suffer itches and bad mood.

Like many other nerds, I can't avoid to update my laptop operating system with the latest developments. No exceptions with Kubuntu 18.04, where I innocently thought it will fix some nasty bugs of 17.10 I was enduring, notably, a very slow desktop login. I took the radical approach, let's format the root partition and install from scratch.

All backups done, machine reinstalled and bingo! now I can't get a second user session, without disconnecting the first. To put in perspective, what is an operating system, especially linux, that can't get more than one user session active at the time?

As usual, Google here, Google there, countless web pages of irrelevant content... and nothing. Greping the syslog, and the culprit was sddm, the login service of Kubuntu. On Github, a report on the issue, but no further indication that the bug will be fixed someday.

Then a hint on the bug report, and it was related to the dual hybrid graphics architecture of the laptop. In my case, I have an Intel and a Radeon dual graphic laptop. The suggestion was to disable the Radeon chip and work only with the Intel, which is no big deal for me. I was happy to finally fix it.

Too easy huh? Not at all. The laptop began to warm too much, even with no CPU load. It was uncomfortable even to rest the hand on the keyboard.

Another set of Google searches and a page in Ubuntu on hybrid graphics. Joining the two solutions, I enabled back the radeon driver, and enabled the switch to let the kernel manage the second graphic chip, so sddm know about it, even if I don't use it.

Second session working, and laptop in normal temperature.

The Styles Menu and UI Customization

Yesterday I was reviewing a nice feature implemented by the User Experience Team of LibreOffice about the Style menu in WRITER. Like all help pages I review, I must test and explore the feature, looking to get the benefits but also to note the possible pitfalls.

What caught my attention was a nice combination of LibreOffice UI and menu customization. LibreOffice allows documents to carry the customized user interface menus, toolbars and much more. If you have a document that requires a specific set of commands you can customize the user interface in Tools - Customize and store the user interface in your document. When opening the document in another machine with LibreOffice, the user interface carried by the document is displayed. I used this feature professionally when I had to convert some old Excel macros to LibreOffice and the macros had hundreds of lines just to modify the user interface. I drop these lines, did the changes in UI once and stored in the document.

So I applied the same strategy to the Styles menu. I was glad to see that you can format your document with little amount click or by activating the style menu with the keyboard. All my custom style were in the menu.

Then closed my document and opened a new document. I wanted to apply my custom styles as before but hey... it does not work. The custom styles were just doing nothing.

The trick is to customize the Styles menu with your preferred styles and add them to your document instead of the LibreOffice Writer interface (the default). This detail slipped under my nose.

Lessons learned: If you want a document with custom styles in the Styles menu, create a template with your custom styles and custom user interface and each new document based on the template will have everything set up.

Happy Text Styling !

LibreOffice Basic well hidden secrets

Last week I wrote a quite long help page on a poorly known feature of LibreOffice aimed to Basic macro programmers.

LibreOffice - since it was named OpenOffice.org long time ago - carried a set of Basic libraries with no documentation (that I was able to find). The libraries were created to support some important features such as Euro conversion or WikiEditor, but also had a set of modules and macro very handy for the ad-hoc or professional Basic programmer of LibreOffice.

The library is distributed in the LibreOffice installers and can be opened in the LibreOffice Macros container, accessible when opening the Basic IDE.

I got fond of the TOOLS library because it has many handy macros that otherwise requires quite a lot of hard code writing and LibreOffice API knowledge even for simple operations.

Things like getting the last used row in a spreadsheet, get the value of a cell, get the filename out of a long URI are the kind of Function's and Sub's we don't want to write again but use GetLastUsedRow, GetValueofCellbyName or FileNameoutofPath for the task.

To use the LibreOffice Tools library , add the statement

GlobalScope.BasicLibraries.LoadLibrary("Tools")

before the first macro of your module. The help page is already online in 

https://help.libreoffice.org/6.1/en-US/text/sbasic/shared/03/lib_tools.html

Note that not every library is described in details in the set of Help pages but if you feel motivated to peek in the code and write a simple description of the remaining modules and macros, join our documentation team!

Happy macro programming!

Bringing Localization to New Help UI

As usual, we have a clear vision of the goal we want to achieve and we know it fits perfectly in the framework available, but sometimes we don't get the smart idea the first time you look at the issue.

It was easy to do the proof of concept for the new help and the style sheet transformations, but in the hurry to get the concept, I used a pair of clutches, or plain bad solution, hoping to be able to come back later.

So time has come to fix the localization of the new Help strings, and to work to use the translation infrastructure of The Document Foundation.

The trick was under my eyes for long time. It is called  document() function in XSLT. With the document() function, I can open an external document, and process it while transforming a XML file.

So why not call an auxiliary help file, with all User Interface strings translated, and use the results inside your main transformation? That is what I did in my latest patch, where I created a help file (browserhelp.xhp) with all terms of my User  Interface.

So here is an excerpt of the document() function usage in the XSLT:

<!-- Strings for the help UI page -->
<xsl:variable name="tmp_href_ui"><xsl:value-of select="concat($urlpre,'text/shared/help/browserhelp.xhp')"/></xsl:variable>

<xsl:variable name="tmp_doc_ui" select="document($tmp_href_ui)"/>
 
<xsl:variable name ="ui_contents"><xsl:apply-templates select="$tmp_doc_ui//variable[@id='contents']"/></xsl:variable>

where I get the right location in tmp_href_ui and the document in tmp_doc_ui, and just after I get the string which identifier is 'contents'.

Later, I used the string 'contents' in the page like

<xsl:value-of select="$ui_contents"/>

 Voilà. And while we are refactoring, I drop most the the other XSLT I was using as clutch (localized.xsl) and exercised some synapses in using the <xsl:for-each> statement to traverse the list of entries in the languages drop-down selector.

Happy translating!

Screenshots in LibreOffice Help

An image worth a thousands words.

Indeed, a textual description of a software feature is too often hard to read, but a simple picture tells much about.

So I patched the LibreOffice Math help pages with screenshots taken by the ScreenShot_Test helper designed by bubli and added them to the help pages. To avoid handling images in too many scattered help files, I collected the in a new help file named screenshots.xhp under /06/ folder of the module. This way,  the images are embedded at the right page and if the screenshot has to be modifies, it is enough to edit the screenshot.xhp file instead of the target help file, which by the way can be multiple.

The Math module has only 8 screenshots under the module/ folder so it makes it easy to evaluate the impact on the size of the data. For all the supported languages (--with-lang=ALL) it adds 19M bytes of images.

While I was addressing this patch I also had to fix a folder naming issue with the helper, which bubli was so kind to approve and also a fix in the XSLT to handle the special case of the default language, en-US.

See it at work: https://help.libreoffice.org/6.1/en-US/text/smath/01/05030000.html?&DbPAR=MATH&System=UNIX

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!

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.