Experts Only Input

[oschuett]

At the last developer meeting, the idea was raised to make our manual more accessible by de-emphasizing less important sections and keywords. I would suggest we label these as experts only.

Since this is a rather profound change, I wanted to ask for comments before diving into the implementation.

[oschuett]

I've been trying to build experts-only keywords, but I couldn't find a good way to style them. Any annotation would inadvertently draw attention to the keywords we want to de-emphasis. And hiding or obscuring expert keywords would defeat the purpose of a reference manual.

So, I have pivoted to emphasizing important keywords instead: #3138.

[mkrack]

What's about having just two different font colours for the ${\large\sf\color{#1994CE}normal}$ and ${\large\sf\color{#98CEE8}expert}$ keywords in the list of keywords, e.g. a slightly faded (lighter) blue font for the expert keywords and/or a different font (courier or slanted)? The detailed descriptions could be left untouched. Personally, I don't like that star in the keyword list. The Mentions entry is sufficient.

[oschuett]

Messing with the colors would require hacking around the Sphinx template. What we could do easily is to make the expert keywords smaller and italic. Likewise, we could make important keywords bold. It will be subtle but also less irritating. However, without a change to the detailed description, I doubt anybody will get the hint.

So, I still think that emphasizing important keywords it the better strategy. By coupling it to the method section we also have an elegant solution for adoption and maintenance.

The input already has a number of features that are barely used because few people know about them, e.g. units. I'm really worried that a subtle expert-only flag will suffer the same fate

The Mentions entry is sufficient.

I agree. The second star in the detailed description is enough to stand out while skimming the page.