Proposed XHP extensions

ohallot · October 22, 2018, 10:55am

Hello everyone concerned on writing Help pages

After significant amount of time spent writing and fixing Help pages
(XHP), I came to conclusion that the 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

so it can replace
<paragraph role="tip" id="123456" xml-lang="en-US" localize="true">

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 dont's, thumbs up or thumbs down.

regards

ohallot · October 22, 2018, 1:01pm

HI Noel

Thanks for the comments.

Hi

Seems like a nice idea in general.

Just a couple of notes:

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

Should localize=true not just be the default? so it only needs to be
specified for the occasional chunk of text that is lanuage-neutral?

Correct. localize="true" is currently the default and was mentioned for
completeness.

Similarly, should xml-lang="en-US" not just be specified in some tag
near the root of the document, and everything else inherits that setting?

This attribute is not used in the current Help. It defines the source
language for translation, string-wise. But since we stick to English
here it is not effective and is left for legacy.

https://wiki.documentfoundation.org/Documentation/Understanding,_Authoring_and_Editing_Openoffice.org_Help/3#xml-lang

We can define it in the root of the document, but I'll refrain to do a
massive change unless we can do it silently to prevent triggering
re-translations.

Perhaps these are already in place, and I just didn't see it - either
way, keep up the good work!

Thanks for the comments and kind words.

Regards

daveb · October 22, 2018, 2:24pm

Hi Olivier,

Yes, this would be a step forward in making things easier for people to
contribute to the help files, which is not an easy task even for those
of us who have some knowledge of XML.

If my reading of your answer to Noel is correct, you propose to set the
DTD to localize="true". It's unclear to me why xml-lang CDATA #REQUIRED
is set, otherwise your example could be reduced to <tip id="123456">, or
am I missing something?

Anyway thanks for your continuing efforts to to improve this function.

Best Regards
Dave

ohallot · November 28, 2018, 3:18pm

Hi all concerned in writing Help pages!

I patched the LibreOffice Help submodule code with the following
extensions to XHP

Class Paragraph-like

Class Character-like

All these extensions above are documented in the XHP reference page in

https://wiki.documentfoundation.org/Documentation/Understanding,_Authoring_and_Editing_Openoffice.org_Help/3

Patch is

https://gerrit.libreoffice.org/#/c/63954/

IMPORTANT

In any case these extensions break the existing markup and contents.

Please do not change existing contents based on these extensions, it
will force a useless re-translation.

However, it is OK when updating contents, and use the opportunity to
also apply the extended markup.

Kind regards

Olivier

daveb · November 29, 2018, 9:34am

Another suggested edit to the wiki page would be to remove the reference
and link to the HelpAuthoring extension.
Even though the text below the first note on that page says:
"/(Deprecated) You need OpenOffice.org 1.1.x to use the help authoring
environment. The authoring environment also is not yet compatible with
OpenOffice.org 2.0./" The note itself implies that extension works in
LibreOffice.

The related wiki page
https://wiki.documentfoundation.org/Documentation/Help displays a clear
warning:
"/The HelpAuthoring Extension is now considered DEPRECATED. Avoid using
it to edit help pages as it can break the Help XML./"

Regards
Dave