darktable-org / dtdocs

darktable user manual

darktable Documentation

This is the user documentation for darktable. The content is authored in markdown and rendered to HTML using Hugo as well as to PDF and ePub.

This repository tracks the current darktable development version. The auto-built website for the development user manual can be found at https://darktable-org.github.io/dtdocs/.

The user manual for the current stable release of darktable can be found at darktable.org.

Contributing

Please see https://darktable-org.github.io/dtdocs/en/special-topics/contributing/ for information about contributing content

For a complete list of the outstanding work please see the issues in this repository and a list of undocumented pull requests in the darktable repository.

Obtaining and Building

Cloning

The themes for the site and PDF use hugo-darktable-docs-theme and hugo-darktable-docs-pdf-theme as git submodules. In order to clone these submodules along with the site you just need to add the flag --recurse-submodules to the clone command:

git clone --recurse-submodules https://github.com/darktable-org/dtdocs.git

If you already have the site cloned, but haven't included the submodules before:

git submodule update --init --recursive

Hugo

This site is built with the static site generator Hugo (extended). Currently v0.75.1 extended:

$ ./hugo version
Hugo Static Site Generator v0.73.0/extended windows/amd64 BuildDate: unknown

SASS

If cloning the repo fresh, remember to build the bootstrap assets locally:

$ cd ./themes/hugo-darktable-docs-theme/assets/
$ yarn install (or alternatively `npm install`)
$ cd ../../hugo-darktable-docs-pdf-theme/assets/
$ yarn install

Updating

If you have the repo cloned but need to update things, it helps to make sure everything is up to date (since we are also using a submodule for the base theme).

As normal, from the project root directory, update things like normal:

git pull

Double check that the submodule is being updated as well:

git submodule update --init --recursive

And finally make sure the assets are built:

cd themes/hugo-darktable-docs-theme/assets/
yarn install (or alternatively `npm install`).

This should get things up and running.

Building

You can build the HTML website locally, the production site to deploy to hosting, or the PDF.

Local Website

Building the site to test locally can be done from the root of the repo.

$ hugo server -D --disableFastRender

The site should then be available at http://localhost:1313/usermanual/development/ (you can see the URL in the output of the hugo server command).

Production Website

Run the hugo command:

hugo

The static files are now available to deploy to a webhost in the public directory. This is currently performed automatically when new changes are pushed to the master branch, via github Actions.

PDF

Ensure you have the weasyprint application installed; this will transform the generated HTML to PDF.

mkdir -p public
hugo server --disableFastRender --config config-pdf.yaml
weasyprint http://localhost:1313/dtdocs/index.html public/darktable_user_manual.pdf
pkill hugo

The PDF is available in the public directory.

dtdocs's Issues

Publish dtdocs v3.4 on darktable.org

v3.4 of dtdocs should be published on darktable.org in time for the release of darktable 3.4 in December

Make all menu headers clickable

In the left-hand menu pane, some section headers are clickable and some are not (generally depending on whether there is written content in that section). However, this makes for a sometimes odd looking menu (mixture of links and headers) and means that you have to click on the + to get to a viewable page (which is quite a small target) and isn't consistent with the breadcrumbs (and some section links) which do allow you to access those header pages.

Please make the entire menu navigable by clicking on the section names as well as the + signs. When clicking on a section that doesn't contain any content, it should load the same page as if you clicked on the breadcrumb link to that page.

pdf image handling

Image styles used in the website are not applied to the pdf. This means that, for example, many icons are too large in the pdf.

more modules has been removed from code

dtdocs still has a section on "more modules" (module reference->utility modules->darkroom->more modules), but in fact this was removed from the code in PR#5683 iop layouts. I didn't notice this, because I don't always clear out my install directory, and I still had an old .so file for "more modules" on my system that was being picked up and displayed in the gui. With a clean installation directory however, you can see this module no longer exists.

FR: Embed search in top toolbar

Add a text entry search box in place of the existing search button, with matches appearing in a menu below, rather than the user having to go to a separate page.

create epub workflow

Create a workflow for producing an epub, presumably using a similar method to the pdf version.

pdf CI build errors

The Github Action workflow shows the following errors when trying to build the pdf

INFO: Step 1 - Fetching and parsing HTML - http://localhost:1313/dtdocs/index.html
INFO: Step 2 - Fetching and parsing CSS - http://localhost:1313/dtdocs/style.min.7bcca80def1a71a2261ca3a756f7e1d44cb95e62a9ca8bce59b7e2a957522b45.css
INFO: Step 3 - Applying CSS
INFO: Step 4 - Creating formatting structure
ERROR: Failed to load image at "http://localhost:1313/dtdocs/module-reference/processing-modules/crop-rotate/keystone-set.png#w25#inline" (HTTPError: HTTP Error 404: Not Found)
ERROR: Failed to load image at "http://localhost:1313/dtdocs/module-reference/processing-modules/crop-rotate/keystone-applied.png#w25#inline" (HTTPError: HTTP Error 404: Not Found)
ERROR: Failed to load image at "http://localhost:1313/dtdocs/special-topics/contributing/squirrel.png#w25#inline" (HTTPError: HTTP Error 404: Not Found)

Presumably it can't handle the #inline part.

Mark deprecated and renamed modules

Add an indication to module titles and content pages explaining where modules have been deprecated and suggest alternatives.

Also rename modules that have been renamed in the gui

Feedback on negadoctor

From pixls.us, on the negadoctor entry in dtdocs:

I think it’s a great first draft. But I have a suggestion for improvement:

It would be helpful if explicit instructions were included for the parts of the image to sample when using the eye droppers. It is already clear for the colour of the film base, D-max, shadows color cast, and paper black sliders. It is not so clear for the scan exposure bias, highlights white balance and print exposure adjustment sliders.

For the scan exposure bias slider, it currently says “Again, you can use the eye dropper to allow Negadoctor to automatically calculate any needed offset.” Are we to assume we should be sampling the whole image minus the unexposed part?
For the highlights white balance slider, it currently says “For highlight color casts, select the eye dropper and click and drag a rectangle across the brightest area of your image.” Does it matter if the brightest part of the image has a colour cast? Should we be aiming for a neutral white, or just any bright part (bearing in mind that the brightest part could be green, blue, yellow, etc.)?
For the print exposure adjustment slider, there is currently no guidance for how to use the eye dropper. Do we assume we should be sampling the whole image minus the unexposed part?

The only other issue I have is that I don’t fully understand the real-world differences between paper black, scan exposure bias, paper grade and print exposure adjustment. The manual does a fairly decent job of explaining what their purpose is and what they are trying to achieve, but when actually using the tool, it appears as though they are all applying slightly different tone curves and that there’s some duplication. I often find that after going through the last tab, the image looks hardly any different from after completing the first two tabs. Not sure if that’s really something the manual can expand upon.

Tidy up project README & new "contributing" page

Perhaps also move the style guide to a separate document.

It might be an idea to actually include the style guide as a new "contributing" content page so that people can see both the sample markdown and how it is rendered.

navigating to a new page shows brief expansion of nav menu

When clicking on a link to a new page, the left-hand navigation pane looks like it briefly expands before contracting again. This is distracting and looks like a glitch.

I can mitigate the issue to some extent by changing hugo-darktable-docs-theme/layouts/_default/baseof.html to make the opacity of the nav tag 0:

<nav class="navigation col-sm-12 order-sm-12 col-md-3 order-md-1" style="opacity: 0">

and then changing hugo-darktable-docs-theme/layouts/partials/javascript.html to put the opacity back to 1 once all the correct elements have been shown/hidden.

 $(document).ready(function(){
     $('.toggle').on('click', function (e) {
	 e.stopPropagation();
	 $(this).siblings('ul').slideToggle();

	 if($(this).hasClass("fa-plus-square")) {
	     $(this).addClass("fa-minus-square-o");
	     $(this).removeClass("fa-plus-square");
	 }
	 else {
	     $(this).addClass("fa-plus-square");
	     $(this).removeClass("fa-minus-square-o");
	 }
     });

     $('.parent ul').hide();
     $('.active').parents('ul').show();
     $('.active').siblings('ul').show();
     $('.navigation').css('opacity', '1.0');
     $('.active').children('i.toggle').removeClass("fa-plus-squre").addClass("fa-minus-square-o");
     $('.active').parents('li').children('.toggle').removeClass("fa-plus-square").addClass("fa-minus-square-o");
 });

The navigation pane still flickers briefly but it just looks like a page reload (which it is) rather than a UI issue.

[FR] Future idea for autodeploys and versioning

I had a thought recently when looking at old darktable manuals and other manuals - the problem of versions. This is just to start discussion but here's my thought:

Currently dtdocs is just "master" but I believe in future it'll have more versions. My idea is that master should always follow darktable master and there should be specific version-branches to have some kind of rewording/spelling etc open instead of fixed tags.
On autodeployed site the pages should be versioned and the "default" route should direct to latest stable version.
Last part: help items inside darktable and their generation: darktable knows which version it is (like for example db backups) so calling help items in form of dtdocs/[VERSION]/page. Any "unknown" version could be interpreted as "master" or anything like that.

Obvously the last part requires buy-in from darktable side, but it's imo worth pursuing

Translation workflow

Devise a translation workflow using as much of the pre-existing manual translation as possible.

Write an introduction to the user manual

The user manual needs some introductory message/preamble explaining what darktable is for, which can be shown in the right hand panel when entering the user manual from the top level.

color-zones: inconsistent images with small fonts

Problem:
In the color zones module documentation the first images are inconsistent with the last one. Also, the font size of the first images looks too small because they were taken from a wide panel (to increase their resolution).

Resolution:
Either reduce the panel size or increase the font size and re-do the images.

Include detail from header tooltips in module reference

Processing module headers in darktable now contain a brief summary of the module along with details of the purpose, input, output and working color spaces.

Consider including this in the dtdocs module reference sections. Some of it is already included but not yet visible.

Should we use the yaml metadata to include this detail or include it as separate content?

Allow previous/next links to move between sections as well as within them

Previous/next links on the bottom of pages currently start and end in the current section. For example overview/sidecar-files/sidecar should (but doesn't) contain a 'previous' link to the section header overview/sidecar-files and overview/sidecar-files/local-copies should (but doesn't) contain a 'next' link to overview/workflow.

I think @paperdigits and @patdavid are already working on a solution for this.

filmic-rgb: orange clipping indicators not clearly explained

There was a discussion on pixls.us about filmic orange clipping indicators:
https://discuss.pixls.us/t/filmic-differences-in-curves-3-2-1-vs-3-3-0-dev-and-out-of-the-box-curve-in-3-3-0-dev/20713/11

This topic should be better treated in the usermanual.

Auto-build pdf with github-actions

I'm not sure if the current method of building the pdf will work well with gh-actions.

Transfer lua API manual to markdown

@wpferguson is looking into this.

better explain blend modes

Amend darkroom/masking-and-blending/blend-modes.md to include explanations of all available blend modes, including those introduced with the scene-referred RGB blending changes.

Changes to module groups UI, presets and preferences

Update to include recent change to the preset manager, newly-created presets and movement of the search bar/module groups preference into the preset manager.

Update docs with new scene-referred blending modes

For details see:

• darktable-org/darktable#6931
• darktable-org/darktable#4688

Use transparent icons

I would suggest to use transparent inline-icons after the text instead of default-dark-background, because:

• it is much clearer to see
• it is independent of themes
• it follows the idea of using images only for explanation but not to illustrate how it looks like in dt

If there is a decision I will do the job of changing all existing icons.

Searching for partial words fails

If I search for "demo" on the search page, it says "Found 9 matches:" but does not display them. If I type a bit more ("demosa") the matches suddenly appear.

agree and formalise shortcut style standards

Style standards for keyboard and mouse actions aren't entirely consistent at the moment.

For example, keyboard shortcuts are generally defined using fixed width with letters in capitals (e.g. Ctrl+R) but mouse clicks aren't very consistently referenced. My opinion is that standalone mouse actions should all be plain text because they often form a part of sentences and things like "Click on the button to..." at the start of a sentence seem odd. Similarly when using "right click" or "middle click" or "scroll". When using keyboard and mouse combinations it might be better to put the whole thing in fixed-width, so "Ctrl+click" rather than "Ctrl+click".

color-calibration: improve explanation of workflow options and warnings

The description of what the CAT workflow options do is not quite accurate, and doesn't cover the warning introduced in darktable-org/darktable#6836

This topic seems a little unstable, so maybe wait for it to settle down a bit and then update the descriptions.

Better distinguish between heading levels

Heading levels 1, 2 and 3 are barely distinguishable from one another on the website, which makes it difficult to easily see the structure of more complicated pages. It should be clear from font size and/or weight which are major and minor headings.

Can't display site running locally

Cloned from git.
Did git submodule update --init --recursive.
Built bootstrap modules with yarn.
Started server with hugo -D --disableFastRender

Opened http://localhost:1313/dtdocs/ in my browser (Firefox).
Blank page displays. No errors in browser or console.
Rebuilt bootstrap with npm.
Still have blank pages.

Did I miss something?

Tried chrome with no luck either

Also tried http://localhost:1313/dtdocs/index.xml and just got raw xml.

Include link in documentation to this github repo

Including the link would encourage users to report issues, such as inaccurate or hard-to-understand sections.

[Workflow] Edit photos with dt, having strong, clipped light source in the frame, like suns set or sunrise

Expose to the right (ETTR) should be well known and obeyed, at least most of the time.

However, either as a photographic working style or as the 'nature of the beast' seriously clipped highlights may occur. For example having the sun in the frame of your picture, it is impossible to avoid sensor clipping.

This workflow is not meant to "repair" accidentally blown shots, even the procedure is similar, just in highlight reconstruction you may want to behave differently.

As I often do shoot towards light sources (is this a diction?), here is my workflow, how I deal with it in darktable 3.4 (currently using 3.3.0, the developers version).

I assume you have a little bit more than basic understanding of the methods in darktable, as I do not describe in detail, how to use e.g. contrast equalizer, color balance or filmic in its full technical depth.

Module highlight reconstruction

• Typically I switch in this scenario to "reconstruct in LCH" from the beginning.
• It might be also helpful to try "reconstruct in color".

In some cases it might even be better to switch of the highlight reconstruction module completely. In that case a more excessive attenuation of scene and reconstruction tab of filmic is needed (not recommended for this workflow)

Exposure

• Decide acc. to your taste and the occasion, whether or not you deactivate "compensate camera exposure"
• Avoid to attenuate exposure lower than +0.5EV, definitely not below 0.0EV
• Usually in this case I leave exposure module untouched

White balance
At first set your white balance. Ideally neutral, without using it artistically for color casting.

• Either you use the classical module white balance,
• or you have already switched in preferences/processing/auto-aply chromatic adaptation defaults to modern and use the new color calibration module

Module filmic rgb

In any case avoid clipping in fimic's graph (orange indicators).

[scene] tab

• Move the slider "white relative exposure" to the right, means increase the values
  • Be careful, not to over cook, as this may wash out your picture
• Adjust black relative exposure to your taste (find your best trade-off)
  • To the left, decreasing the value, preserves the shadows, reduces the (perception of) contrast
  • To the right, increasing the value, provides more (perception of) contrast but losing details in the shadows

[look] tab

Provided you want to have as less desaturation in highlights as possible for your sun set or sun rise, you can try two things acc. to your taste:

• Either use shadows/highlights balance and move it to the left, decrease the value

  • Do not overcook, it can also cause unnatural saturation
    or
  • move the latidue to the right, increasing the value or a combination of both

• Contrast slider may be adjusted to taste, I prefer e.g. color balance or other tools as a separate instance

[reconstruct] tab

• Toggle the raw over exposed indicator e.g. by pressing shift+o (the character, not number)
• Activate the "display highlight reconstruction mask" (picture becomes black
• Pull down the transition slider to the minimum on the left
• Slowly decrease the "Threshold slider (to the left) until the masked area becomes visible, slightly more than your raw over exposed indicator
  
• Reset transition slider (double click on the slider)
• Toggle raw exposure indicator again (shift+o) and unset display highlight reconstruction mask (picture becomes colored again)
• Attenuate transition to your liking (usually +3.0 is quite fine)
  (in some cases, this can be too much, e.g. for "golden October sun", in that case reduce the threshold slightly and keep attenuating transition)
• further more, the slider "structure/bloom" can kindo of optimize the results. So attenuate to your liking and be prepared to counter it partially with the [look] tab, as described above.

[options] tab

• You may try to increase the iterations of high-quality reconstruction.
• Also you may play around with "preserve chrominance" (max RGB might look promising, quite depends on taste and picture)

tone equalizer

• Adjust the mask, with mask exposure/contrast compensation, so that the mask-histogram nicely spread between ~-1EV and ~-7EV
  
• Hover your mouse over the light source and gently decrease
• Increase shadows to your taste

Final touch
For the final look and feel,

• Local contrast, contrast equalizer and color balance can be used.
• At color balance I like to
  • give a slight touch of orange to the hightlights and use the color picker for hue in offset (shadows) on something black
• Finally, due to lifting shadows

Here you are...

---

@codingdave and @johnny-bit would you mind, give this a try and kick my ass if it is unclear? If it fails for the result, kick your own ass :-)

@matt-maguire: as discussed on IRC, if this gets your appreciation and no fat complaints from the guinea pigs, would you then merge it to the workfow-section of dt-docs?

Recommendations for improvements are welcome.

filmic RGB needs clarification around ETTR

Received some feedback from @paka on IRC that the wording around ETTR is a bit confusing.

• it is not mandatory to shoot ETTR, but it helps to optimise usage of sensor's DR (eg. for fast action may not have time to play with exposure settings)
• specular highlights can be clipped, this is a choice/tradeoff that has to be decided
• there was mention about the preview being dark, which was a confusing comment, because dark preview would suggest underexposure, whereas ETTR is the opposite. need to clarify what is meant here (tradeoff of highlights vs shadows with wide DR)
• ETTR refers to histogram in camera, not in darktable itself

If its causing confusion, needs to be cleaned up.

retouch module

Seems there could be a wrong description of the "merge" slider description for the retouch module:
https://discuss.pixls.us/t/error-in-section-retouch-module-in-darktables-manual-3-0-draft-3-4/20784

Need to take a closer look at this.

Document module grouping feature

@AlicVB has proposed an update the the usermanual concerning the new module grouping feature in PR darktable-org/darktable#6576

This needs to be proof-read and converted to markdown.

more distinct fixed-width font

The difference between the normal and fixed-width fonts is not very obvious. I've made some attempts to make it stand out more (bold, light grey color, light grey background) and I'm not sure what is the best option. Perhaps a different colour?

Suggestions?

where to document adjustable height modules

PR6408 talks about being able to adjust the hiehgt of certain utility modules that contain lists of things by hovering the mouse over the list, then using Ctrl-scroll to change the maximum number of items to show in the list at one time.

This applies to modules on both lighttable and darkroom, and currently there is common area in the usermanual where to include such a description of module interaction. So, where to document it?

Make a style and provide the tooling to make numbered callouts to annotate images

Make a style and provide the tooling to make numbered callouts to annotate images

Black-on-Gray hard to read

I find the current color scheme hard to read because of the low contrast provided by the darkish gray background.

Online contrast checkers seem to disagree with my vision on this one. Also, for having the docs open next to darktable, the color scheme might be ideal.

Add Windows/macOS file locations to the manual

In page 15, in the pdf, or in the basic workflow ->editing an image: scene-referred workflow, in the vibrance part it says this:

"vibrance

Tends to darken colors. Consider using using color zones with a saturation parametric mask to give more control."

The word using is repeated there.

Also, I noticed that in the manual it only mentions the location of the local copies, profiles etc of Linux systems. It would be nice if the Windows and macOS file locations where there too.

Navigate from Lighttable's file manager section has the wrong shortcuts.

On the navigate part of lighttables file manager section says that pressing G scrolls to the top of the collection and Shift + G scrolls to the end of the collection. Pressing them does nothing, it does work with Home and End keys.

clicking a section header should expand the toc

When clicking on a section header on the left hand pane, this currently opens up the appropriate section page but leaves the ToC on the left hand pane unexpanded (even though the "+" beside the header changes to a "-").

Please make clicking on a section header work the same as clicking on the "+", but in this case also opening the relevant page as well.

document export scaling PR #6079

darktable-org/darktable#6079

Working colour space

As mentioned at https://elstoc.github.io/dtdocs/module-reference/processing-modules/input-color-profile/, 'By default darktable will use “linear Rec2020 RGB”' for the working profile.
https://elstoc.github.io/dtdocs/guides-tutorials/monochrome/ claims that 'The channel mixer module comes after the input color profile module in the pixelpipe, and the channel mixer presets assume that a linear Rec709 RGB working profile has been applied'

This inconsistency seems rather strange (why ship presets that use some other working profile than the default). Are you sure about this?
Change is here: darktable-org/darktable@442f3d9

Tone EQ

module-reference/processing-modules/tone-equalizer/

This controls how much of the surrounding image to take into account when calculating the mask’s blur at a particular point. By default it takes 25% of the surrounding into account.

'25% of the surrounding(s)' doesn't really mean anything. Checking the code, the blurring radius is defined in terms of image dimensions (d->blending is the value entered on the UI as 'smoothing diameter'), even though the exact calculation is not that important from a user's point of view:

  const int max_size = (piece->iwidth > piece->iheight) ? piece->iwidth : piece->iheight;
  const float diameter = d->blending * max_size * roi_in->scale;
  const int radius = (int)((diameter - 1.0f) / ( 2.0f));

So, it could perhaps be worded as 'This controls how much of the surrounding image to take into account when calculating the mask’s blur at a particular point, in relation to the image dimensions. The default value is 25% of the longest side.'
Maybe including the values Aurélien considered typical would make sense: 'Typical blurring radii are around 1-5% [for EIGF], while the original GF is better between 10-25%' (https://discuss.pixls.us/t/a-tone-equalizer-in-darktable/10678/10).

Can file and directory names have section numbers prepended for better sorting?

I haven't had a chance to look into Hugo etc yet, so I don't really know what all the practical considerations are concerning the large number of files containing small amounts of text, but... if this is going to be the case, is there any possibility of the files and directories being named in such a way that they sort alphanumerically into something resembling the document structure? It seems like this would be in line with the goal of making editing as painless as possible. :-)

tone-equalizer-cursor.png is not English

The file module-reference/processing-modules/tone-equalizer/tone-equalizer-cursor.png looks like it's from a translated (French?) version of darktable and needs to be re-done in an English version, preferably with a more neutral background colour.

website needs to support multiple manuals

As identified in #86, need to push usermanual down a level to allow room for the LUA API manual beside it. Need to be able to generate separate PDFs for usermanual and LUA API guide.

Update Map view, including locations utility module

The locations utility module needs to be documented, along the lines of darktable-org/darktable#6932
See also darktable-org/darktable#6995 for changes

odd load and refresh behaviour

When loading a new page, it loads slightly scrolled-down and each time I refresh the page it scrolls down a little more.

On Firefox browser, latest version.

Make pages printable with content only

Amend dtdocs pages so that, when printing, only the content page is visible - hide the sidebar, header bar, breadcrumbs and previous/next links.