bug-texinfo
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: setting up rules on produced HTML class attributes


From: Patrice Dumas
Subject: Re: setting up rules on produced HTML class attributes
Date: Sun, 9 Jan 2022 14:49:04 +0100

On Sat, Jan 08, 2022 at 07:02:19PM +0000, Gavin Smith wrote:
> 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 corresponds to the classes that are derived from some texinfo text
and are not preset, and therefore could be about anything.  For example
 @printindex something
leads to a class being output, index-something.

Another example is @example
 @example a, b, c
leads to classes a, b and c being output.

> 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?

That's clearly not what I am trying to improve.  If anything, adding more
classes for @-commands and use @-commands names increase the risk of
having clashes with user-defined classes.  The objective is rather to
have rules that makes CSS, javascript and html postprocessing easier
because there are rules on class names that allows users to have
expectations about what the class relates too.

I thought about that in particular based on some things Per Bothner
said or wrote, and on Mahlon analysis of CSS styling of Texinfo
documents:
http://www.softwaresam.us/docs/html_doc/infodoc_css.html

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

The idea is that changing to def-category would make clear that it
does not relate to a @category Texinfo @-command and that it relates to
a @def* @-command.

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

Ok.  I will try to do renamings based on the rules, but with a priority
on usability.

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

Indeed, here nav-header would be much better in my opinion.

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

Yes.  Independently, I find section-toc for this class confusing,
mini-toc for instance would be clearer to me.

> > 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?

Indeed, texi2any would put it there, it was an example set in a future
where texi2any could output such a class name.

> 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?

It is, but I can't imagine a way to avoid that.  At least the first rule
(without hyphen use only Texinfo @-commands names) makes sure that it
cannot happen for names without hyphen.

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

Note that in my proposal, it would become something like
  flushright-align
or
  flushright-paragraph

as flushright would be reserved for the class appearing where the
@flushright is (presumably on a <div>).

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

Exactly.  I plan to do that kind of changes when possible, and try to do
it for all the classes used for style, instead of describing the style,
describe the use/location in document.

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

That's the best I could come up with...

-- 
Pat



reply via email to

[Prev in Thread] Current Thread [Next in Thread]