Help Content Modernization
- 1 Meta bug: TDF#97629
- 2 Introduction
- 3 Preserve translation
- 4 Display in local system browser
- 5 On-line help content
- 6 Multimedia and rich content ( TDF#97628)
- 7 CSS for branding
- 8 Adjust HelpAuthoring tool
- 9 Issues to watch
- 10 What this project is NOT
- 11 Related information
Meta bug: TDF#97629
Since the birth of OpenOffice.org, the help content has relied in a set of tools developed internally. In particular, the display of the help pages is done by a XSLT transform of XML files in Wrter/Web with very few graphic, multimedia and rendering resources and standardizes in HTML 3.2, according to this source
The objective of this project is to replace the local help application into a modern browser with the 2016's web technology. The advantages are many:
- Use modern system's browser to display the help content.
- Add modern resources such as multimedia, MathML, SVG, GIFs into the local help content for better user experience.
- Build bridges to make the help content available to on-line servers, with the same capabilities of the local help.
- Ease the access of the community in contributing to help content.
The execution of this project can be through bugzilla tasks connected to one main bugzilla metabug. Each task can be transformed into an GSOC project, or in many cases, as easy hacks.
Whatever technology is used, the contents and its translations of the current help system must be preserved. This is a sine qua non condition
Display in local system browser
This task will make the help content display in a modern browser such as MS Edge, Firefox, Google or Safari and their associated derivatives. Once the help button is pressed, LibreOffice will call the browser passing an URL with the file or service necessary to display the current help content. The current help content is in XML files. These XMLs will be transformed into HTML or HTML5, with the necessary enhanced CSS to be rendered in the browser either in a new window or in a new tab. The navigation of the help content shall be initially the same as the primitive internal browser.
Search text in help
To be addressed
Some ideas in Regina Henschel dashboard: https://wiki.documentfoundation.org/User:Regina/HelpAuthoringDashboard#Future:_TOC_and_Index
Build / packaging strategy
- Keep XHP files in JAR containers and create wrappers and XSLT transforms to display in the system's browser at usage time (smaller storage footprint, but higher processor time)
- Transform all XHP help pages in HTML(5) at build time and pass the help URL to the browser as parameter (larger storage footprint, less processor time, instantaneous upload in a server)
It seems that 2 is more efficient (IAND).
On-line help content
A direct rendering of the XHP files is available at
Some interesting properties of displaying the XHP files in a modern browser (Firefox, Chrome, Safari, MS Edge, Opera):
- Use of browser navigation buttons for backward and forward navigation.
- Use of the same cascading style sheet for identical look-and-feel as the local help.
- Use the interal browser seach mechanism to locate a string in the page and in the index.
- Use Ctrl+U to display the XHP source file.
- Use Shift+F5 to display the rendered html in the browser console
- Use browser bookmark mechanism for page bookmarking
- Direct access to XHP pages: to display smath/01/03060000.xhp call http://vm173.documentfoundation.org/text/smath/01/03060000.xhp
- Pages displayed are the master branch of helpconten2/ submodule.
- Index is per module
Multimedia and rich content ( TDF#97628)
Since the display will be in a modern browser, this task will lay out the infrastructure for adding rich content to the XHP help files. The list below is a non exhausting set of to-dos
- Create a multimedia folder in helpcontent2/ git sub-project, with name multimedia/
- In the multimedia/ folder, create L10n folders (because multimedia may need localization)
- Define a fall-back L10N folder.
- Adjust existing Makefiles for builds.
- Multimedia content will be packed inside language help packs.
- Handle display of the icon set.
- Videos (standard set of open standards video technology), screencasts.
- Images (PNG, JPEG, GIF, SVG, etc...).
- MathML (Calc functions, Math examples, etc…)
- Example files: In some cases a link to a ODF file with the example is more effective that a full textual description of the subject. For example, some Calc functions pages could open a Calc spreadsheet with the example inside.
- Other rich resources compatible with modern browsers
CSS for branding
This easy hack will enhance or define new CSS entries to achieve a visual effect that is aligned with TDF branding of LibreOffice or to other LibreOffice derived products.
Note: the CSS for the internal browser is set according to L10N.
Adjust HelpAuthoring tool
In order to deal with the new rich features, the HelpAuthoring too will need to be touched as well, but is a later phase.
Issues to watch
The project shall not touch help page contents, unless absolutely necessary. All changes in help page contents (XHP files) shall preserve the settings of the translation workflow, preventing rework of strings translation (fuzzy state).
What this project is NOT
The project does not deal with the content of the help pages.
The project does not handle the Help Authoring tool. Regina Henschel has a lot of good ideas on the Help Authoring tool: https://wiki.documentfoundation.org/User:Regina/HelpAuthoringDashboard
Links in the bottom of Regina's page are very useful to rescue history of the help content.