Re: html dir links, table summary

[Kurt Hornik]

>>>>> Karl Berry writes:

> Hi Kurt - I'm cc-ing my colleagues at texinfo-devel, so will include
> your original msg and intersperse my replies.

Thanks.

>     Date: Wed, 31 Dec 2014 11:14:19 +0100
>     From: Kurt Hornik <address@hidden>
>     To: address@hidden (Karl Berry)
>     Subject: Texinfo to HTML conversion problems

>     [...]
>     I recently tried the effect of running linkchecker on our R-project and
>     CRAN web pages, which as you know contain HTML versions of the R manuals
>     obtained from their texinfo sources.

>     This complains about invalid dir.html links in the top menus, which by
>     default contain something like

>     <div class="header">
>     <p>
>     Next: <a href="#Preamble" accesskey="n" rel="next">Preamble</a>, 
> Previous: <a href="dir.html#Top" accesskey="p" rel="prev">(dir)</a>, Up: <a 
> href="dir.html#Top" accesskey="u" rel="up">(dir)</a> &nbsp; </p>
>     </div>

>     Now in Texinfo 5.2 I can set the configuration variable TOP_NODE_UP_URL
>     to empty to get rid of the "Up" hyperlink: but this still leaves the
>     "Previous" hyperlink in, and I found no way to programmatically get rid
>     of this one.  Is there a way?

> Not that I know of.  I think it would be best if the TOP_NODE_UP_URL
> value (or some new configuration variable) replaced all occurrences of
> (dir).  It doesn't make sense to me otherwise.

That would be perfect afaic.

>  I also think I may be forgetting the exact circumstances of my asking
> Patrice to create TOP_NODE_UP ...

>     Also, is there a way to programmatically generate dir.html?  

> Not that I know of.  It seems a fruitless effort since everyone's site
> is different.

>     (E.g., using install-info?)

> Definitely not with that, or any Texinfo tool.

>     In our case, it would be "best" to simply have the top node menu not
>     have any hyperlinks to dir, so I'll look into a way to post-process the
>     generated HTML accordingly.

> You could replace the (dir) links with your top-level doc url.
> That's more or less what I always had in mind.

Yep, but these don't necessarily have a #Top to go to.

> We could also have some value of TOP_NODE_UP (or whatever), like
> "null", mean to omit the references, if you think that is needed.
    
>     By the way, HTML validators give 
>       Warning: <table> lacks "summary" attribute

> I think those validators are in error.  Suddenly warning about
> something that has never been (and still isn't) required?  I gather
> the US government has started recommending it in section 508.  Fine,
> but the rest of the world cannot change on a dime.

I agree, and the references do not seem very clear about this either.
E.g., <http://www.w3.org/TR/html401/struct/tables.html> only seems to
say

  Authors should provide a summary of a table's content and structure so
  that people using non-visual user agents may better understand it.

but perhaps the "should" should be taken strong enough to justify the
respective warning.

>     because the menu tables have no summary attribute: perhaps in 
>     ./Texinfo/Convert/HTML.pm: 
>        $result .= '<table border="0" cellpadding="0" cellspacing="0">
>     you could add something like summary="Menu" (perhaps with the name of
>     the node the menu is for)?

> Thanks for the finding the reference.  A static summary="Menu" doesn't
> seem useful to me, but with the name of the node, I suppose it is
> better to do it than not.

Yep, for the menu tables adding a suitable summary should be easy.

Dealing with tables generated directly from @table is more of a
nuisance.  I will simply post-process the generated HTML manuals to add
an empty summary ...

Best
-k

> Patrice, Gavin, wdyt?

> Thanks,
> Karl