Support for <?xml-stylesheet to use Mallard in XHP?

[mario1]

So, I went on this ditzy sidequest of writing some help pages for an UNO
plugin. Like most extension authors, I didn't feel enticed by XHP
initially; and went with Mallard here.
Now I'm wondering if the LO helpviewer can be made to recognize an
embedded stylesheet reference:

  <?xml-stylesheet href="./mallard2xhp.xsl" type="text/xsl"?>

Haven't really looked this up, but I'd assume it strips out any such PIs
in favour of main_transform.xsl. Or libxslt discards it by itself when
fed an override?
Or is it just due to the relative path? (Is %origin%/… supposed to work
in this context?)

Else, couldn't the helpviewer support more than one file type? As in
preconvert *.page files itself? The formats are close enough for some
crude mapping:
  http://fossil.include-once.org/pagetranslate/artifact/4597b7ac
Fully converting <link> to <bookmark> absolute path references would
be a bit more involving, of course. But doesn't seem totally infeasible.
(Crossposting to @projectmallard, to lure some feedback.)

Presumably there's zero demand to migrate the Open/LibreOffice help
system at large. But you know, the documentation prevalence among
extensions is a bit lower. Not sure if it's just me, or if any such
effort would be warranted there.

[ohallot]

Hi Mario

We are now using the system browser to display the Help pages. We don't
use the native Help module (writer-web) anymore, it is deprecated.

The system browser displays html pages transformed at build time from
XHP. The transformation is online_transform.xsl.

We also have extended XHP to handle more simple tags. The extended xhp
is not backward compatible with LO release before 6.0

We developed an editor for xhp at the following address

https://newdesign.libreoffice.org/xhpeditor/index.php

please be indulgent, it is work in progress, but it can speed-up a lot
of the editing, the text editor is Codemirror. Instructions are in the page

https://wiki.documentfoundation.org/DocumentationHelpEditor

I was not aware of Mallard. It seems to address the same objetive. I
have not seen in Mallard: how to address translations and if there is a
WYSIWYG editor.

regards
Olivier

[ilmari]

I've briefly mentioned Mallard at some point in the doc chat. It is one candidate for XHP replacement, but in general, it is very difficult to find a doc markup solution that has a good balance of power and human-readability.

For example, Asciidoc and ReStructuredText are two big ones, but it could be said they fail the balancing test and thus provide nothing of value over XHP's XML.

A recent candidate is MyST, which extends Markdown's CommonMark spec: https://myst-parser.readthedocs.io/en/latest/using/syntax.html
It is work-in-progress at the moment. It is possible that it would hit a sweet spot regarding the balance.

I've been following NixOS's effort to decide what they should move to from DocBook: https://github.com/NixOS/rfcs/pull/64
Their conclusion is rather depressing: "There is no good solution. All the options kind-of suck."

In any case, it would be a massive investment on all fronts to move from XHP to something else, so they benefits really need to be clear. Personally I would like us to move to something better, but we can't do that, if nothing better exists

Ilmari

Olivier Hallot kirjoitti 12.6.2020 klo 0.39: