Request for documentation correction/update

The current (v3.0) darktable manual states on p. 150:
“User-designed watermarks are placed into the directory $HOME/.config/darktable/watermarks.”

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 (may not be modified)
• Linux - user-designed watermarks: /home/.config/darktable/watermarks
• Windows 10 - C:/Program Files/darktable/share/darktable/watermarks (all watermarks)
• Mac – (Someone familiar with the Mac OS will have to supply this location)”

Hi,
If possible, it’s better to propose a pull request to integrate that on darktable Github: GitHub - darktable-org/darktable: darktable is an open source photography workflow application and raw developer

Thing is, you have watermarks in system space and user space.

You should not modify these watermarks in system space because they are package dependent. If you remove darktable it could be deleted. If you overwrite one of those in system space, when you upgrade it will be overwritten. You get the idea.

If you add or modify watermarks and store them in user path, they are safe from package upgrading, installing, uninstalling,…

So, if you want to add system paths for completeness, I’d ask you to include a note don’t recommending overwrite or modify them there but in user space.

Added Mac paths and fixed Linux user paths:

Regards

I just wanted to mention that documentation, especially user facing one, shouldn’t bother documenting paths that shoudn’t be user-modifiable, so no point in mentioning darktable install dir based ones IMO.

1 Like

I’m thinking that paths to watermarks should be available so that the user can find, copy and modify them and subsequently place the modified watermarks in the appropriate location for user-designed watermarks. Would you agree?

Thank you Rafa and others for improvements. I’ve re-worded my suggested verbiage.

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/.config/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

There are other sections that refer to home and installation directories as well. We shouldn’t pollute them all with big long lists of alternate locations. Plus all of these locations are entirely at the discretion of the user. For example my working copy of darktable is installed in a directory structure beneath /home/me/bin/darktable-working and my config files are stored in /home/me/.config/darktable-working.

So really we should just say “the watermarks sub-directory within your config directory” or something like that.

With all respect, I’m going to disagree with this comment. I’m of the opinion that file location information would make it easier to get a newbie up to speed on the end product. As an example, coming from a 25-year experience with Windows, I had no idea where to look for watermarks under Linux, and wasted a good bit of time searching for them when I’d much rather have been outside, behind a camera.

I’m not necessarily saying that information shouldn’t be in the manual at all, just that an individual module reference section isn’t the place for it. If we’re going to document all these locations we should do it once and then for the rest of the document either describe them as $INSTALL_DIR and $CONFIG_DIR and/or reference that one section.

Frankly, I’m not interested so much in “what” the file folders are called, but more in “where” the files are located. I agree that consistency is the key, but we all know that the authors of the various operating systems seem to have come up with their own paradigm for folder location names. On the other hand, the developers of darktable have been remarkably consistent in the folder names for watermarks, for example. That said, I would not object to a single section in the manual that contained all the locations used for darktable files within each operating system for which darktable has been written.