Help Content Modernization

From The Document Foundation Wiki
Jump to: navigation, search

Meta bug: TDF#97629

Introduction

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:

  1. Use modern system's browser to display the help content.
  2. Add modern resources such as multimedia, MathML, SVG, GIFs into the local help content for better user experience.
  3. Build bridges to make the help content available to on-line servers, with the same capabilities of the local help.
  4. 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.

Preserve translation

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

Two possibilities:

  1. 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)
  2. 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

http://vm173.documentfoundation.org

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

  1. Create a multimedia folder in helpcontent2/ git sub-project, with name multimedia/
  2. In the multimedia/ folder, create L10n folders (because multimedia may need localization)
  3. Define a fall-back L10N folder.
  4. Adjust existing Makefiles for builds.
  5. Multimedia content will be packed inside language help packs.
  6. Handle display of the icon set.

Rich content

  • 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

Related information

Links in the bottom of Regina's page are very useful to rescue history of the help content.