Help System Specification: Rationale of help path

[notebook]

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


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

[j***@gmail.com]

Post by notebook
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 would guess it has been influenced by the localedir notably used by
GNU gettext (/usr/share/locale). Or maybe mandir (/usr/share/man),
which also supports localizations according to FHS:

https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s11.html#usrsharemanManualPages

Post by notebook
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.

Note that filesystem hierarchy standard already turns the system into a
big soup. If you want nicer structure look at GoboLinux or Nix.

[notebook]

Thank you for input on this topic!

Note that filesystem hierarchy standard already turns the system into a big soup.
I would guess it has been influenced by the localedir notably used by
it is what it is. It's not worth the effort to change it at this point.
The KDE person suggested that this was easier to implement
as Shaun wrote (all elided), it is probably not worth the effort to change.

Apart from the KDE-guy this sounds like "it's already like this" and "others use it, too". Perhaps I should search for records of that meeting in 2010 - or even dig into the reasoning behind `localedir` (any input welcome).

@"Changing is not worth the effort": Guessing, that the current systems live another 20+ years, I'd say it's worth the effort giving its superiority over the current system. That being commended, I should search for why things are like they are.

If you want nicer structure look at GoboLinux or Nix.

Thank you for the reference!

I am not likely to ever try to
access a help file in other than my native language ((American) English), so
getting into a directory with all the other English help files seems more
natural to me.

Unfortunately this only works, if you are able to enjoy the pleasure of an almost-always supported language.


Regards
Chris

Post by notebook
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 would guess it has been influenced by the localedir notably used by
GNU gettext (/usr/share/locale). Or maybe mandir (/usr/share/man),
https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s11.html#usrsharemanManualPages

Post by notebook
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.

Note that filesystem hierarchy standard already turns the system into a
big soup. If you want nicer structure look at GoboLinux or Nix.

[r***@gmail.com]

Post by notebook

Post by r***@gmail.com
I am not likely to ever try to
access a help file in other than my native language ((American) English),
so getting into a directory with all the other English help files seems
more natural to me.

Unfortunately this only works, if you are able to enjoy the pleasure of an
almost-always supported language.

Ahh, good point, I guess -- I guess it would be nicer if all languages had all
the help files ;-)

[Cornelius Schumacher]

Post by notebook
Apart from the KDE-guy this sounds like "it's already like this" and
"others use it, too". Perhaps I should search for records of that
meeting in 2010 - or even dig into the reasoning behind `localedir`
(any input welcome).

As one of the people involved from the KDE side back then I remember
that there were discussions but I don't think they went particularly
deep because in the end it was a question what was easier to implement
given the already existing code.

In the end it doesn't matter that much and is a pretty arbitrary
decision depending on personal preferences and from what perspective you
look at it.

As a user you most often won't care about the file system and paths
because you will use the UI.

As an application developer you look at one application and translations
to multiple languages of the same documents.

As a translator you look at translations in one language for multiple
applications.

Post by notebook
@"Changing is not worth the effort": Guessing, that the current
systems live another 20+ years, I'd say it's worth the effort giving
its superiority over the current system. That being commended, I
should search for why things are like they are.

I don't think there is a solution which clearly satisfies the needs from
all perspectives better than the current one, so I doubt there is clear
superiority of any choice. As the current system is good enough to
handle everything what is needed, even if that might not be the optimal
solution for certain work flows, but it does work, I also don't see a
need to fundamentally change anything here.

Post by notebook

I am not likely to ever try to access a help file in other than my
native language ((American) English), so getting into a directory
with all the other English help files seems more natural to me.

Unfortunately this only works, if you are able to enjoy the pleasure
of an almost-always supported language.

For users KDE (and I assume most other environments) allows users to
chose a list of languages and they are used in a cascading way depending
on availability of translations. This should cover this use case for the
majority of people and is not dependent on the path details how the data
is stored.

[Shaun McCance]

Post by notebook
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

Post by notebook
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.
     /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.
     /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
https://lists.freedesktop.org/mailman/listinfo/xdg

[r***@gmail.com]

Post by notebook
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
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.
/usr/share/help/en/gedit
/usr/share/help/en/firefox
/usr/share/help/de/gedit

From the peanut gallery, I prefer the above. I am not likely to ever try to
access a help file in other than my native language ((American) English), so
getting into a directory with all the other English help files seems more
natural to me.

That is as a user -- maybe as a developer who might be translating help files
into other languages, it might be better the other way round.

But, as Shaun wrote (all elided), it is probably not worth the effort to
change.

Post by notebook
I personally see more benefit in "sorted" by application name first,
and language second.
/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.