Re: setting up rules on produced HTML class attributes

[Gavin Smith]

On Fri, Jan 07, 2022 at 03:43:52PM +0100, Patrice Dumas wrote:
> Hello,
> 
> I would like to setup rules on class names used in HTML attributes, with
> the final aim to make it easier for users to do CSS, javascript or HTML
> postprocessing.
> 
> 
> Here is my proposition, with 3 rules:
> 
> Reserve class names without hyphen to @-commands.  Output at max one of
> such attribut on an element for each @-command appearing in the Texinfo
> source.  This rule applies to automatically generated class names based
> on some Texinfo code, so these auto generated classes should have at
> least a string with an hyphen prepended or appended.
> 
> Class names <command>-* with <command> a Texinfo @-command name are
> reserved for classes marking that one is an @-command but in other elements,
> in general sub elements.  Does not apply to automatically generated
> class names.
> 
> Class names *-<command> with <command> a Texinfo @-command name are
> reserved for uses related to @-command <command>.  Does not apply to
> automatically generated class names.

I don't understand what the meaning of "automatically generated class
names" is.

It's hard to have an opinion on this without knowing more about how the
class names are used.  Is there a risk of clashing with user-defined
classes, for example if a Texinfo HTML file is combined with another
HTML file somehow?

You are probably more familiar than me with the uses of class attributes
in HTML.  Just to take one example @def* commands are output with
<dl class="def">.  I believe other parts of the @def* line may be
marked with classes; for example, the category with
<span class="category">.  What would be the benefit of changing this
to <span class="def-category">?  I can see it might make it clearer
to somebody looking at that part of the output what the <span> is for.

I can imagine there might be other cases when making the attribute
name longer would be unnecessary.

I don't see the benefit of having a rigid rule for it.  I don't object
if you rename some class attributes if you think it is making the
output clearer.  I think it should be taken on a case-by-case basis.

I ran texi2any --html on texinfo.texi and looked at the output:

This kind of <div>:

<div class="header">
<p>
Next: <a href="#Copying-Conditions" accesskey="n" rel="next">Texinfo Copying 
Conditions</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" 
rel="contents">Contents</a>][<a href="#Command-and-Variable-Index" 
title="Index" rel="index">Index</a>]</p>
</div>

I agree that this would be better as something like <div class="node-header">
or <div class="section-header"> or <div class="nav-header">.

Another one:  <ul class="section-toc">.  This would clash with your rule
as it is not just output in @section's but in @chapter's, @subsection's, etc.

> 
> 
> Note that for names with hyphens (like <some>-<name>) the rules prevents
> from using some names, but do not mandate to use them.  For example if
> there is a bibliography, one should not use in the bibliography the
> class "biblio-contents" as @contents is an @-command related to
> contents, but one can use "list-sections-toc" class name in @contents
> formatting even though there is no "contents" string in the class name.

How would the class 'biblio-contents' appear in Texinfo output unless
texi2any put it there?

I don't see any harm in having such a class name, though.

> Also note that a string within the middle of a class name can be
> anything, so in a bibliography one can have a class like 
> "biblio-contents-last"
> (it is probably best not to do it, though).
> 
> 
> A consequence of those rules is that when a new Texinfo @-command
> is created all the unrelated classes names that are not automatically 
> generated
> and that begin or end with that name need to be renamed.

Good point.  Couldn't that be quite inconvenient?

I saw that the 'right-align' class was used for 'flushright'; I agree
that <p class="flushright"> would be just as good as <p class="right-align">
if not better.

I am sure that there are other class names I haven't mentioned as I haven't
attempted to do a throrough audit.


> Any comment, remark?
> 
> 
> Another rule, not on the name per se, would be to use as much as
> possible semantic names corresponding to the use in the document
> and not styling names.

Does this refer to the center-align classes?  I don't like them very
much.   The <h1 class="settitle center-align"> could just be
<h1 class="settitle">.

> With these rules some class names already output should change.  One
> case of change is the @example arguments which would need to be changed
> and contradicts the current manual content.  According to the proposal
> @example arguments should not be left as is (for the first rule), but
> have something prepended or appended. I would propose prepending arg-.
> 
> The manual is right now:
> 
>  You may optionally give arguments to the '@example' command,
>  separated by commas if there is more than one.  In the HTML output, any
>  such arguments are output as class names.
> 
> It would become
> 
>  You may optionally give arguments to the '@example' command,
>  separated by commas if there is more than one.  In the HTML output, any
>  such arguments are output as class names with 'arg-' prepended.
> 
> Any comment, remark?

I'm not sure; I wonder if there would be a better prefix than "arg-".