Re: XDG Base Directory Specification ignores installation directories

[Patrice Dumas]

I already have done an implementation, but I can easily modify it:

https://git.savannah.gnu.org/cgit/texinfo.git/commit/?id=7ba51006395793fe6bdfdd2fc195cba27c6f758b

On Wed, Aug 28, 2024 at 09:26:55PM +0100, Gavin Smith wrote:
> On Wed, Aug 28, 2024 at 01:34:23PM +0200, Patrice Dumas wrote:
> > Hello,
> > 
> > Using the XDG Base Directory Specification is not as straightforward as
> > what I thought.  I have changed my mind compared to my previous
> > proposition, because interaction between defaults if $XDG_DATA_DIRS is
> > not set and $datadir installation directory are not really considered by
> > the specification (I'd say rightly as it is out of scope for the
> > specification) but we need to make decisions about all that.
> 
> I'm a bit confused as I thought it was configuration files which we
> were discussing, which would be XDG_CONFIG_DIRS, not XDG_DATA_DIRS.
> 
> I see that htmlxref.cnf is installed under $datadir, e.g. as
> "/usr/local/share/texinfo/htmlxref.cnf".  I suppose there is a question
> of whether this file counts as "data" or "configuration".  We should
> decide which one each file we are talking about is, otherwise this issue
> is more confusing.

To me data vs configuration is, in general, not about the nature of the
information, but about the intent on how a resource is modifiable and by
whom.  If the resource is considered to be a non-changeable asset, it is
data, but the exact same file could be configuration in another place
where it is editable.  It is the established practice, in sysconfdir the
installed or searched files are supposed to be edited, while the files
installed in datadir are not supposed to be edited, and could be mounted
read-only.  The XDG Base Directory Specification allows this
interpretation by not defining precisely what data and configuration is.

> > Here is my current proposal:
> > 
> > - replace ~/.texinfo by the XDG specification, with $XDG_CONFIG_HOME.
> >   In my opinion, it is an improvement compared to using ~/.texinfo directly
> >   in HOME. The specification is unclear on what should be in $XDG_DATA_HOME
> >   or $XDG_CONFIG_HOME but my feeling is that $XDG_CONFIG_HOME is better. 
> >   Still find files in ~/.texinfo/ after specification locations for some
> >   time, with a deprecation message if found in that directory.
> 
> I added similar logic for the "info" program, in infomap.c.  XDG_CONFIG_HOME
> is checked first (both as an environment variable and in the default
> "$HOME/.config" location).  If the file is found there, then the old
> location ("$HOME/infokey") is not checked.
> 
> The case of htmlxref.cnf (I assume that's the file we're talking about)

It is about both htmlxref.cnf and init files lookup.

> is more complicated as more than one file can be loaded.  I would say
> to check under XDG_CONFIG_HOME first, and if found, do *not* check under
> the old location ("$HOME/.texinfo/").  This would allow setting
> XDG_CONFIG_HOME to override all configuration in the user's home
> directory.

It is about what I did.  If XDG_CONFIG_HOME is set, do not check under
the old location nor .config/texinfo.  If XDG_CONFIG_HOME is not set,
check under .config/texinfo and then the old location, and issue a
deprecation message if a file is found in the old location.

> Check under XDG_CONFIG_DIRS in any case for htmlxref.cnf files (with
> any files there having a lower priority).
> 
> There is no rush to add a deprecation message.

I did it.  It can easily be removed.

> > - to replace the former search in $datadir/texinfo:
> >   if $XDG_DATA_DIRS is set, search in those directories.  Then search
> >   in $datadir (if not already in $XDG_DATA_DIRS).  Last search in
> >   /usr/local/share and /usr/share (if not already done), which are
> >   the default for $XDG_DATA_DIRS that have to be used if $XDG_DATA_DIRS
> >   is not set.  In what I propose, they are used even if $XDG_DATA_DIRS
> >   is set.
> 
> If we consider htmlxref.cnf a "config" file rather than a "data" file,
> then the copy of htmlxref.cnf under $datadir (e.g. /usr/local/share/texinfo)
> would not be covered as a "config" file by the XDG specification.
> Therefore setting XDG_DATA_DIRS should have no effect on whether this
> file is read or not.

I do not think that this is the right way to look at this.  To me the
logic is that we search both in "config" locations, as it is where the
system/user may place an htmlxref.cnf files, and we search there first,
and in "data", which is where the default from texi2any is installed.

I proposed and implemented an extension to that logic, by proposing
a third type of location, with both configuration and data variants,
which would correspond to runtime and buildtime configuration
independent locations available for defaults independent of the
implementation and of any configuration.  I choosed /usr/share and
/usr/local/share for these locations (it only changes the lookup if
$datadir is not already /usr/share nor /usr/local/share).

I had the idea to add the fixed path by looking at discussions on XDG
lists where people argued that truely shared/common information must be
in hard-coded directories, and I agree.  Otherwise there is always the
"risk" that the shared/common location is not found.

> However, if htmlxref.cnf is a "data" file, then here's an attempt at
> laying out what is checked:

To me it htmlxref.cnf is both "configuration", as a locally modified
version is relevant, found in sysconfdir, and "data" as an immutable
default file considered as data and installed by GNU Texinfo is also to
be considered.  That's what we did before and I think that it is right.

In what I implemented, I proposed to add other "config" and "data"
locations that would not depend on any setting, as I said above.  to
have places always set that distributors or administrators can use for
implementation and configuration independent resources.

>   * First check "." and "./.texinfo" (cwd and relative to source file
>   location), as is currently done.  This is not really under the purview
>   of the XDG spec as it is a project-specific configuration file.
> 
>   * Regardless of whether anything was found in the previous step, check
>   XDG_DATA_HOME, then in the "old location" ($HOME/.texinfo) *but only*
>   if nothing was found in XDG_DATA_HOME.  Accumulate the data from any
>   htmlxref.cnf file found with that in the previous step.
> 
>   * Regardless of whether anything was found in the previous steps, then
>   we should check XDG_DATA_DIRS.  Only if the XDG_DATA_DIRS variable
>   is unset, then use $datadir as the default.  We ignore this part of
>   the spec:
> 
>     "If $XDG_DATA_DIRS is either not set or empty, a value equal to
>     /usr/local/share/:/usr/share/ should be used.
> 
>   as it seems wrong to hardcode these paths when we already have $datadir.
>   Accumulate the data from any htmlxref.cnf file found with those in
>   the previous two steps.

I always added /usr/local/share/ and /usr/share/, for the reason I said
above, not as defaults for $XDG_DATA_DIRS.  I used the same directories,
but it could actually be others.  Those directories are a good choice
because they are the XDG defaults, and also because, in normal settings
(when the Filesystem Hierarchy Standard is used), they are the system and
locally compiled directories.  For sysconfdir I used the XDG_CONFIG_DIRS
default because I had no other ideas.

> We don't need to change all the uses of $datadir (from autoconf/automake)
> in Texinfo with XDG_DATA_DIRS, I believe.  This change is just for user
> configuration files such as they might have in their home directory, not
> for installed parts of Texinfo (like Common.pm, etc.).  (I don't think
> we were discussing this but I'm saying it just in case.)

Agreed.  It is to find init files (and not init files we directly use in
texi2any, that are in ext/) and htmlxref.cnf.  Not necessarily only
user configuration files, but only for resources for which it makes
sense to supplement the installed data (or there is no installed data).
(As a side note, for code there are other ways, Perl -I or
LD_LIBRARY_PATH, PATH and similar).

> > - do the same for $sysconfdir/texinfo as for $datadir/texinfo.
> 
> Which files would this affect?

The same files, it is for init files or htmlxref.cnf as set locally,
considered as configuration, in contrast with what we ship, which is
more like data.

-- 
Pat