Request: conform to XDG basedir spec

[jasonkarns]

https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html

Presently, it is writing to ~/.tldrc and is not respecting XDG_CONFIG_HOME or XDG_CACHE_HOME or XDG_DATA_HOME. I'm not sure how much of the directory is config vs cache vs data, so I don't know which xdg directories it should be written to. But none of it should be in ~.

[severen]

If you really care about it, you can use tealdeer, which adheres to the XDG BaseDir spec. Take note that it is written in Rust, so you'll need a Rust compiler installed to build it.

Disclaimer, I'm a contributor to the project.

[waldyrious]

@SShrike and @jasonkarns, this is something we might include in the client spec that is being defined at #1065. Please comment there if you think it should be enforced for all clients, or not.

[sebdanielsson]

My cache files still get written to my home directory on macOS. Any tips?

[marchersimon]

@sebdanielsson do you mean the tldr cache where the pages are stored? If so, you can open an issue about this at your client's repository or use another client.

[sebdanielsson]

Looks like this issue belongs to this repo:
https://github.com/tldr-pages/tldr-c-client.

There's already an issue for it:
tldr-pages/tldr-c-client#49

Sorry for the inconvenience.

[noraj]

About the configuration file

Continuing https://github.com/orgs/tldr-pages/discussions/10796

Note: The standardization about the configuration file location could be applied to the cache or data directory as well.

Before

• Python client no config file but reads some custom environment variables https://github.com/tldr-pages/tldr-python-client?tab=readme-ov-file#configuration
• Node.js client reads a config file .tldrrc in a non-standard location https://github.com/tldr-pages/tldr-node-client?tab=readme-ov-file#configuration
• C client has no global configuration support
• Elixir client has no global configuration support

After

The specification should define a standard file format and location for a user configuration file.

As the official clients are cross-platforms, they should read from the standard configuration folder for each platform:

• Unix / Linux: $XDG_CONFIG_HOME/tldr/
• macOS: ~/Library/Application Support/tldr/
• Windows: %APPDATA%\tldr\

Reference

• discussion
• Apple - File System Overview
• macOS Library Directory Details
• XDG base directory
• XDG user directory
• Windows - Known Folder
• macOs Standard Directories

Examples

Examples of project doing that:

• poetry
• Zim
• Rust

Fire format

Then the file format could be selected among YAML, JSON, TOML depending on what kind of libraries is most robust, natively included, etc. in the different languages of the official clients. (PS: TOML is just some kind of standardized INI).

[niklasmohrin]

I am not sure I am convinced about having a unified configuration file that is detailed in the client spec. Different programming languages tend to use their own file format (Javascript would probably use JSON, Rust programs tend to prefer toml), so there isn't really one format that fits all. Allowing different formats and having clients check multiple files seems overly complicated to me. Additionally, if some clients have more options than others, all clients would have to explicitly ignore options they don't understand, which in turn makes it harder to debug a faulty config (for example a typo language vs langauge, one of which would be ignored).

I think that recommending something like "stick to XDG or similar convention" sounds good, but a unified .config/tldr/tldr.toml does not.

[noraj]

There are 3 different things about the config:

1. Unifying the path/location, I personally think it should be important in the spec
2. Unifying the file format (JSON, YAML, TOML), that may not be enforced, each client could choose it's own, for example to avoid having to include additional external dependencies (for example Ruby has a native JSON and YAML parser bot not a TOML one)
3. Unifying a minimal set of keys, the spec could require a minimal set of keys to mandatory supported by the clients (eg. languages) and tell in the spec explicitly that other clients could support more options and so ignore them. By the way the node under which the official keys and client custom keys are could be different for that purpose. Eg. the spec could ask to put the custom keys under a client node: client.<client_name>.<custom_key> so it would be easy to ignore all client.<client_name> sub-nodes that are not client.<my_client>. A bit like some SSG does for extension where extensions should not modify or add keys under the root of the config file but under a dedicated extensions node.

[niklasmohrin]

Hm, I must say, I don't think I agree with "Unifying a minimal set of keys". Some options have natural derivations from the CLI specification, but I wouldn't force anyone to implement a mapping to a config file in any particular way. I think the most that could be required from clients is to document how CLI args are mapped to configuration file options, for example by recommending that this can be found from my-tldr --help or man my-tldr (or a separate man my-tldr.toml). However, this recommendation then seems somewhat excessive to me, because it's just recommending good practices and I feel the spec should focus on tldr-specific topics.

[noraj]

I understand your point, however if there is not a minimal set of keys supported by all clients and a standard config file location, then it means the clients are not much interoperable and a user need to re-write a specific conf file when he change of tldr flavor.
But that's not specific to config only, the same occurs for the data location (cache folder), for example tealdeer save the data in a custom path so you need to redownload all the pages even if you already have tldr-python. While all spec-compliants tldr clients could all use $XDG_CACHE_HOME and the same file structure.
My point is, if each client has it own config file format, config file location, config file keys name for official options (+ custom options), a different cache location, etc. then clients are not really inter-operable outside being able to use the same pages and having the same CLI option naming.

At least; if those points are not required in the spec, they could be suggested / being optional to nudge developers toward having a homogenous ecosystem without strictly enforcing anything. What do you think?

[sbrl]

The client spec tries to be accepting of all kinds of client, regardless of whether they are CLI-based or not.

Perhaps some wording like it's RECOMMENDED to follow the appropriate per-platform standards for storing any configuration files.

then clients are not really inter-operable outside being able to use the same pages and having the same CLI option naming.

It was never the goal to have clients be interoperable. I would argue that this is out-of-scope. If all clients do exactly the same thing, then why do we have multiple clients?

The point of an ecosystem of clients is to allow every possible platform and combination to be supported. Not just CLI clients, but also Android, web, etc......

---

Ref XDG, does this even make sense on all platforms (e.g. Windows, Android, etc)?

[gutjuri]

I am for closing this issue as not planned. sbrl's arguments convince me. Why should we tell the clients where to store their data? If this is an issue it should be raised in the bug tracker of the respective client