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:
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
Em 11/06/2020 15:42, mario escreveu:
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:
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 to 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.
--
To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org
Problems? https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette
List archive: https://listarchives.libreoffice.org/global/documentation/
Privacy Policy: https://www.documentfoundation.org/privacy
