Broken assumptions about menu structure in help content

Currently most of the help content referring to menus is incorrect and has been for years. One reason for this sad situation is that due to ancient structural decisions, it is outrageously difficult to adapt the content to changes.

Here is the story in a nutshell:

1. The help system is architected. Repetition in content related to menu items is avoided by clever structuring (hooray! the savings!)
2. Content is added, references to menus spread far and wide
3. Menu item locations are changed in a massive redesign operation, making the help content obsolete

The pain is mostly caused by assumptions that certain menus of certain modules are identical. Impress and Draw are the most problematic in this regard.

Then we have the "how to access" pages with increasingly mixed content. Consider the one for Edit menu, which now contains wonderful entries like "Choose Edit - ImageMap in Writer and Calc or Tools - ImageMap in Impress and Draw" or entries referring to a completely different menu like "Choose Tools - Bibliography Database" and "Choose View - Navigator".
https://helponline.libreoffice.org/6.3/en-US/text/shared/00/edit_menu.html

We need a system, where the help content concerning the location of menu items is automatically generated from the menu bar definition files. If shared information on menus is desired, it needs to be produced automatically.

The reason I add l10n list in Cc is that I want to raise awareness of the current situation. Having incorrect information translated into nearly 200 languages just multiplies the number of negative experiences. Translators cannot fix this on the level of strings, it needs to be dealt with structurally. It would be great, if members from the stronger translation teams (de, fr, id...) would participate in the current manual effort on fixing the menu help information.

Here are a few patches from me that show, how the changes can be done:
https://gerrit.libreoffice.org/#/c/68830/
https://gerrit.libreoffice.org/#/c/71436/
https://gerrit.libreoffice.org/#/c/71703/

If people get interested, I can offer assistance.

Ilmari

Hello Ilmari

Thanks for raising the issue. Indeed the menus are not fully reflected
in the Help pages and updating them is hard.

Currently most of the help content referring to menus is incorrect and
has been for years. One reason for this sad situation is that due to
ancient structural decisions, it is outrageously difficult to adapt the
content to changes.

Here is the story in a nutshell:

1. The help system is architected. Repetition in content related to menu
items is avoided by clever structuring (hooray! the savings!)
2. Content is added, references to menus spread far and wide
3. Menu item locations are changed in a massive redesign operation,
making the help content obsolete

The pain is mostly caused by assumptions that certain menus of certain
modules are identical. Impress and Draw are the most problematic in this
regard.

Sad but true.

Then we have the "how to access" pages with increasingly mixed content.
Consider the one for Edit menu, which now contains wonderful entries
like "Choose Edit - ImageMap in Writer and Calc or Tools - ImageMap in
Impress and Draw"

In this specific case we can use <switchinline select="appl"><caseinline
select="WRITER">...</caseinline><caseinline select="DRAW">...

But yes, some "how to access" entries are not the best.

or entries referring to a completely different menu

like "Choose Tools - Bibliography Database" and "Choose View - Navigator".
https://helponline.libreoffice.org/6.3/en-US/text/shared/00/edit_menu.html

We need a system, where the help content concerning the location of menu
items is automatically generated from the menu bar definition files. If
shared information on menus is desired, it needs to be produced
automatically.

Menus and toolbars are described by XML files (XCD). This can be read
and converted into fragments of help files to be embedded in the help
pages that describes the menu/toolbar command, either by a python script
or by a XSL transformation, run at each new major release.

We need a invariant ID which content can be updates but the reference
stays. Suggestion is to define the invariant as the full UNO command
name, plus some extra attribute to differentiate if a menu entry, a
toolbar icon or whatever, used to call the same UNO command. Today,
these ID's are written in German for the most part (<section
id="ein_wort_auf_deutsch">).

The reason I add l10n list in Cc is that I want to raise awareness of
the current situation. Having incorrect information translated into
nearly 200 languages just multiplies the number of negative experiences.
Translators cannot fix this on the level of strings, it needs to be
dealt with structurally. It would be great, if members from the stronger
translation teams (de, fr, id...) would participate in the current
manual effort on fixing the menu help information.

While saving translation work is nice, we always have English as our
reference, and translation memory to reduce workload. Doing a post
translation work such as updating translated Help pages is a bit too
early to address at this stage.

When converting XCD to XHP it will be prefereable to define a paragraph
ID scheme that can be stable when running the tranformation on the same
menu entry (and thus not triggering retranslation).

Here are a few patches from me that show, how the changes can be done:
https://gerrit.libreoffice.org/#/c/68830/
https://gerrit.libreoffice.org/#/c/71436/
https://gerrit.libreoffice.org/#/c/71703/

If people get interested, I can offer assistance.

I am! I want!

Hello Ilmari, *,

I would be happy to help too, but I'm afraid, I have no much time even
in the next 2 weeks at least.

But it would be great to see one of my pet bugs goes before 6.3 freeze
arrives:

https://bugs.documentfoundation.org/show_bug.cgi?id=92825

What can I do (even with little time for now) for achieving this?

BTW: How is your work with the shell script ongoing?

With a limited time budget, I would say focus on any module expect Impress & Draw. Some tasks are easier than others. Try to pick something that requires the least amount of structural churn. Maybe only update text content that has direct mentions to menu paths and skip the embeddable "how to get" definitions etc.

There are also changes in context menus. Perhaps some items have simply been removed - thus very easy to update.

My script for checking fileopen & filesave regressions was merged to dev-tools: https://gerrit.libreoffice.org/#/c/71069/
It is found inside the /qa directory, if you clone the project from https://gerrit.libreoffice.org/#/admin/projects/dev-tools

Ilmari

Sophia Schröder kirjoitti 16.5.2019 klo 17.51: