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