darktable-org / dtdocs Goto Github PK

@wpferguson is looking into this.

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.

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.

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.

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.

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

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.

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.

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.

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?

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.

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.

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.

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.

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.

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

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".

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

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.

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.

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.

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

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.

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

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.

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

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.

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?

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.

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.

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

For details see:

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

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.

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).

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.

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. :-)

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.

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.

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

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.

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?

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

darktable-org/darktable#6079

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.

@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.

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.

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

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.

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

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.