Help System Specification: Rationale of help path

[Shaun McCance]

On Sun, 2021-05-09 at 07:41 +0900, notebook wrote:
> Hello,
> 
> Summary
> ========
> I'd like to know why help files are sorted by language first and then
> by application name, instead of the other way around.
> // I hope this is the right place

I can provide some insight into this, but the details escape me.

Back in 2010, we had a little get together with docs people from GNOME,
KDE, XFCE, and Fedora. We decided to make a shared help system. GNOME's
old help system grouped by document ID first, then by language. KDE's
system did language first, then document ID. The KDE person suggested
that this was easier to implement with the way they did docs thru their
VFS. I don't remember details, but for me as a GNOME developer, it was
no harder, so we went with the KDE way.

In the end, I think only GNOME implemented the spec, so *shrug*, it is
what it is. It's not worth the effort to change it at this point.

--
Shaun

> Details
> =======
> In [1] is specified, that help files are found under
> `$XDG_DATA_DIRS/help/$lang/$path/`. That is, help files are "sorted"
> by language first, and then by application name.
>    Example:
>      /usr/share/help/en/gedit
>      /usr/share/help/en/firefox
>      /usr/share/help/de/gedit
> 
> 
> 
> I personally see more benefit in "sorted" by application name first,
> and language second.
>    Example:
>      /usr/share/help/gedit/en
>      /usr/share/help/gedit/de
>      /usr/share/help/firefox/en
> 
> Apart from easier manual handling, I would say this ordering helps
> keeping applications apart from each other, versus, the current spec
> looks like it turn the whole system into a big soup.
> 
> 
> References
> ==========
> [1] https://www.freedesktop.org/wiki/Specifications/help-system/
> 
> 
> Regards
> DarkTrick
> _______________________________________________
> xdg mailing list
> xdg at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/xdg