Re: styling flexibility for definitions

[Per Bothner]

On 10/30/20 12:13 AM, Gavin Smith wrote:
> I think it's worth supporting this with CSS if all it needs is adding
> some element classes to the output.

Note that adding descriptive class names isn't just for styling - they
could be useful for searching or (say) extracting only all the definitions.

> I don't think non-standard HTML attributes should be used so the
> category="Function" part should be removed.

Well, it can't be just removed, since it is used for css:
    dt.synopsis[category]:after { content: "["  attr(category) "]" }
Specifically, attr(category) is the value of the "category" attribute.

I don't think there is a strong reason to not use non-standard attributes:
It's fully supported by javascript and css.  There are a couple of minor reasons
(validation becomes more complicated without a custom DTD, and there is a small 
chance
they might clash with a future standard or browser extension), and some people
disapprove of them.

A HTML5-standards compliant approach (which will not break in older browsers)
is to use a data- attribute:
https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes

Another approach (which I think I would prefer):
<dt class="synopsis" category="Function"><span class="category">Function</span><span 
class="category-suffix">: </span>...</span>

Then the CSS could be:

dt.synopsis span.category { float: right; padding-left: 2em; }
dt.synopsis span.category:before { content: "[" }
dt.synopsis span.category:after { content: "]" }
dt.synopsis span.category-suffix { display: none }

> I can't see where $brk and $sep are used in the patch.

Indeed, that's left over from before I used a separate $category_text variable.

> If deftypefnnewline > is on could the category be wrapped in <span 
> class="category">
> anyway?

One idea when deftypefnnewline is on is to put the <br/> inside the 
category-suffix element.

> Some of the class names could be made more specific, e.g. def-synopsis
> instead of synopsis.

Do you mean specific class names for specific categories? That could be useful,
but a generic "synopsis" is more useful.

Or so you mean replacing the classname "synopsis" by "def-synopsis"?
I don't see any particular value in that, since the value is already
nested as a "definition" class, so the "definition"/"synopsis" follows by 
context.

> > +      $category_text = $category ? $$category{text} : '';
>
> The $$ looks wrong.

It's needed.  $category is a reference to a hash.  Dereferencing it would be
@$category, and retrieving the specific 'text' element is $$category{text}.

> There is an _attribute_class function that could be used to output the
> <span class="category">.

I'll try it out.
--
        --Per Bothner
per@bothner.com   http://per.bothner.com/