Orca’s documentation was already super outdated. The complete redo of Orca’s preferences window in v50 made that even worse. So I’m going to rewrite it.
Given that this is essentially a fresh start, and not just some string changes, I was wondering if Orca’s docs could be written in markdown instead of mallard and still be properly translated. If not, what are my alternatives?
On the other hand, if I can write Orca’s docs in markdown, what do I need to do to turn the localized docs into a format gnome-help supports?
Loupe, Warp, and Pika Backup are using ducktype. That’s kinda similar to markdown. Sadly, the documentation and distribution situation for our help stack is pretty bad right now.
We are converting the files to the old XML format and commit that into git to keep things like translation working.
At the risk of asking a silly question, is the reason we can’t use markdown the fact that gnome-help doesn’t support it? Or is it that the translation team’s tools don’t support it?
My quick search showed a couple of gettext markdown tools. Not sure how good they are tho. I have a lil crisis rn, but i could look into that later, out of curiosity.
Both. On top of that, our help system needs more markup than markdown offers. See for example `$guiseq`, `$cmd` or `$code`.
I do have vague ideas of replacing everything in the help system with a markdown dialect. But it’s not clear if this is the right way forward and if I will have time for that during my fellowship.
More silly questions I’m afraid. While I get that there’s richer markup when we use mallard, what is our help system doing with it now that it wouldn’t be able to do without it?
My goal is to have accurate and understandable documentation for Orca’s features, and my target audience is end users of Orca. So from my uninformed perspective, that richer markup is a nice-to-have. Not a must-have. But given your comment about our help system, I bet I’m missing something.
It’s highlighting a bunch of these things in different ways optically, and it also supports linking between docs of different apps in the Help app and our help pages. There are probably more features that I’m not aware of.
There is no way for the Help app or the help website to render markdown. So it’s impossible to use markdown.