Document OS-specific differences in file locations

[Graycard]

The issue: The current (v4.6) darktable manual states on p. 184 under section 8.2.76, watermark: “User-designed watermarks should be placed into the directory $HOME/.config/darktable/watermarks.”

The problem: The above quoted text is incorrect, leaving out an important folder name.

Suggested corrections/updates: I would suggest the following re-wording to bring the text to current configuration: “Watermarks are placed in the file folders appropriate to the user’s operating system as follows: • Linux - standard watermarks: /usr/share/darktable/watermarks (It is recommended that watermarks in this location not be modified or deleted.) • Linux - user-designed watermarks: $HOME/username/.config/darktable/watermarks • Linux Mint - user-designed watermarks: var/lib/flatpak/app/org.darktable.Darktable/x86_64/stable/[long-ass-number]/files/share/darktable/watermarks • Windows 10 - C:/Program Files/darktable/share/darktable/watermarks (All watermarks are available to be modified, deleted or added to.) • Mac - standard watermarks: /Applications/darktable.app/Contents/Resources/share/darktable/watermarks (It is recommended that watermarks in this location not be modified or deleted.) • Mac - user-designed watermarks: $HOME/.config/darktable/watermarks”Is your feature request related to a problem? Please describe.

[ralfbrown]

Under Linux, $HOME includes the username unless you've done something weird to your environment variables, e.g. on my PC it is set to /home/ralf. The directory shown in the current manual is correct, but we should add the others for different systems.

[elstoc]

This sort of thing has come up before. Unfortunately what you're asking is for us to document the idiosyncrasies of the various operating systems / packages and how they have chosen to adjust the darktable application to suit their packaging. I'm not sure that should necessarily be our responsibility, since some of it is not under our control.

To take some of your examples explicitly:

standard watermarks

Given your recommendation (with which I concur) not to modify the contents I'm not sure there's any benefit in the user knowing where these are located.

Linux - user-designed watermarks

This location we give in the documentation is correct for Linux (and Mac) since Linux is our primary platform and other Operating Systems have somewhat patchy support. On Linux $HOME already includes the user name of the currently-logged in user ($HOME usually points to /home/username) so no modification is needed here.

Linux Mint

These locations are specific to flatpak and not unique to Mint. Again these are packaging idiosyncrasies and not under our control.

Mac

This is the same as Linux so again the manual is already correct.

Windows 10

Again I strongly suspect this depends on how the app is packaged, though as I understand it darktable does provide packaged Windows installations.

Having said all that, I don't object to some documentation for other Operating Systems but I'd much rather make it generic and put it in a single location in the user manual - the watermarks module is certainly not the only place this can be an issue and we'd be in danger of repeating ourselves (a lot) otherwise.

In general we quote $HOME in order to make this as OS-agnostic as possible but it might be worth adding a link to another page whenever we quote locations like this, perhaps even one outside of the manual (maybe in the github wiki so it can be amended by packagers more easily).

[kmilos]

One way would be to use a generic placeholder like <CONFIGDIR> everywhere in the manual, and in one place define it as $HOME/.config/darktable for *nix, and %USERPROFILE%\AppData\Local\darktable (or simply %LOCALAPPDATA%\darktable) for Windows as default locations, if not set by the --configdir command line option (or otherwise special for some non-standard distros/ways of delivery).

[github-actions[bot]]

This issue has not had any activity in the past 60 days and will be closed in 365 days if not updated.