RawPedia style

[Beep6581]

Capitalization and Quotation

There are essentially 3 things to consider when referring to interface elements, their use in:

1. A normal sentence.
2. A breadcrumb-style reference.
3. Titles.

In RawTherapee, all tool names and frame titles use title case (first word capitalized), everything else uses sentence case. Note: not all tools adhere to this style - that is to be handled by #5664

Example name of interface element:

Avoid color shift

Example in normal sentence:

The "Avoid color shift" checkbox in the "Chromatic Aberration Correction" tool in the "Raw" tab applies Munsell correction.

Example in breadcrumb-style reference:

Use Raw tab > Sensor with Bayer Matrix > Chromatic Aberration Correction > Avoid color shift to prevent discoloration.

I always append the word "tab" when referring to a tab, to discern it from a tool (e.g. the "Exposure" tool in the "Exposure" tab). However, since "tab" is not part of the name, and since "Avoid color shift" uses sentence case, it's not clear to a new user which part of that sentence is the name of a tool and which is the rest of the sentence.

Possible solutions to that problem:

Use Raw tab > Sensor with Bayer Matrix > Chromatic Aberration Correction > "Avoid color shift" to prevent discoloration. Use "Raw tab > Sensor with Bayer Matrix > Chromatic Aberration Correction > Avoid color shift" to prevent discoloration. Use "Raw" tab > "Sensor with Bayer Matrix" > "Chromatic Aberration Correction" > "Avoid color shift" to prevent discoloration.

In the beginning, before RawPedia was a MediaWiki, I surrounded all interface element names in double-quotes, e.g.:

The "Avoid color shift" checkbox in the "Chromatic Aberration Correction" tool in the "Raw" tab applies Munsell correction.

In some cases the quotes made the sentence messy, so once RawPedia moved to MediaWiki, instead of quotes I turned the interface element names into links, since each tool should have its own section in RawPedia and links show up blue so it's clear where the name of the widget ends and the rest of the sentence resumes, e.g.

The "Avoid color shift" checkbox in the [[Chromatic Aberration Correction]] tool in the [[Main_Page#Raw_Tab|Raw]] tab applies Munsell correction.

However, a link can only refer to a page and section in RawPedia, but not all widgets have their own section in the documentation (and widgets which do what their name implies don't need to be documented), such as "Avoid color shift". So relying purely on links doesn't work. Besides, now that RawPedia can be generated to PDF and printed on paper, links might not look like links at all.

As such, it might make sense to revert to using double quotes around all widget names (tool names, frame titles, slider names, etc).

What are your thoughts on how to refer to interface elements in a normal sentence and in a breadcrumb-style reference?

[Beep6581]

I wrote this in RawPedia:

Refer to user interface elements (toolnames, frame titles, slider names, etc.) using the capitalization used in RawTherapee. That is, all tool names and frame titles use title case, while all other elements use sentence case. Surround these other user interface element names in double-quotes. e.g. There is no need to surround "Dynamic Range Compression" in quotes, since every word is capitalized and it's clear that this is the name of the tool, while "Restrict LC to red and skin-tones" should be quoted so that it is clear in a sentence where the name of this checkbox ends and the rest of the sentence resumes.

[waynesutton50]

What are your thoughts on how to refer to interface elements in a normal sentence and in a breadcrumb-style reference?

The use of double quotes for interface elements in either of these cases can become distracting I find because there is also a tendency to make excessive use of double quotes for emphasis. Without thinking I started reverting to the British English convention of single quotes for setting off a word as word to try and make the text more readable but this was a mistake as it only introduces yet another convention. Perhaps the use of italics would be a good compromise in both normal and breadcrumb type sentences.

There is no need to surround "Dynamic Range Compression" in quotes, since every word is capitalized and it's clear that this is the name of the tool,

I agree if the preference is to standardize on double quotes for interface elements.

[Thanatomanic]

I agree with what @Beep6581 wrote on RawPedia so far (see two posts above). It makes sense that whenever a description to a certain GUI element contains mixed case, it should be quoted to encapsulate the phrase. Double quotes is good, aiming for American English as a default writing style is a reasonable choice.

As for breadcrumbs, first of all, I think they need to be used sparingly because they take up quite a lot of space. If one can be replaced with a direct link to the tool's page, I think that would generally be preferable. I would suggest to use a style (e.g. bold or emphasis color) to set the breadcrumb apart from the regular text. This avoids quotation marks all together. The ">" and applied style indicate to the user that they are being guided to a specific place in the GUI. You could even do away with the word "tab", because that is just part of the route.

If we're talking about style in general: I am not so much in favor of using italics to emphasize text other than as an alert. In addition, I really don't like how the italics look like on RawPedia... They just feel like slanted regular text and not a true italic form. Reading it takes me out of the flow of the text.

[Thanatomanic]

So relying purely on links doesn't work. Besides, now that RawPedia can be generated to PDF and printed on paper, links might not look like links at all.

Links in a PDF could still work, although I'm not sure if they will be generated automatically by whatever pdf-generator is running on the site. I think a paper print of an online, constantly changing documentation is a silly idea and we should not bother trying to optimize for it. As we know from photography itself, different media require very different approaches... Let's focus on improving the online one.

[TechXavAL]

@Beep6581 @Thanatomanic

Take a look at the italics now. They render the real italic font, not a slanted version (there's the need to download an extra font, though).

And PDFs link rendering is not that hard to tweak, if somebody says how it has to look.

[Thanatomanic]

@TechXavAL That's much better! Thanks 😃

[Beep6581]

I agree with everything said.

I would suggest to use a style (e.g. bold or emphasis color) to set the breadcrumb apart from the regular text.

I don't want to use color for text as that will only cause problems down the road. This leaves us with bold or italics for breadcrumb-style references.

As for the question of whether to double-quote interface element names which use sentence-case (e.g. "Avoid color shift") vs those which use title-case (e.g. "Dynamic Range Compression"), the only issue I have with this is the inconsistency. Instead, we could write all interface element names in italics or in bold, without quotes. I'll test this out in the next article I update so we can see whether it works out well in reality, or whether it detracts from the content.

This is not a 5.9 blocker.

[waynesutton50]

The RawPedia chapters listed below been revised and updated and should now be consistent with the 4 June RawPedia guidelines for contributing i.e.

Refer to user interface elements (tool names, frame titles, slider names, etc.) using the capitalization used in RawTherapee. That is, all tool names and frame titles use title case, while all other elements use sentence case. Surround these other user interface element names in double-quotes. e.g. There is no need to surround "Dynamic Range Compression" in quotes, since every word is capitalized and it's clear that this is the name of the tool, while "Restrict LC to red and skin-tones" should be quoted so that it is clear in a sentence where the name of this checkbox ends and the rest of the sentence resumes.

https://rawpedia.rawtherapee.com/About_Noise_Reduction https://rawpedia.rawtherapee.com/Toolchain_Pipeline#Colorimetry https://rawpedia.rawtherapee.com/Color_Management#Abstract_Profiles https://rawpedia.rawtherapee.com/CIECAM02#Color_Appearance_.26_Lighting_.28CIECAM02.2F16.29_and_Log_Encoding_modules https://rawpedia.rawtherapee.com/Local_Adjustments