Re: Texinfo 7.0 changed the name of HTML output directory

[Patrice Dumas]

On Sat, Aug 24, 2024 at 08:26:13AM +0300, Eli Zaretskii wrote:
> > Date: Fri, 23 Aug 2024 22:17:33 +0200
> > From: Patrice Dumas <pertusus@free.fr>
> > 
> > +The defaults for the @var{host} and @var{dir} correspond with 
> > cross-references
> > +links for a collection of manuals located side by side on a single host.  
> > This
> > +is different from the usual case of HTML manuals published on the World 
> > Wide
> > +Web served from different hosts in directories chosen by the publisher, for
> > +which the @var{host} and @var{dir} must be specially defined to have 
> > working
> > +cross-references.  However this requires external information and is 
> > detailed
> > +later on (@pxref{HTML Xref Configuration}).
> 
> This part is unclear, I could not understand what it means and how
> that affects me as the user of Texinfo.

Maybe I'll let Gavin propose something...

> > +If you want to generate cross-references to HTML manuals published on
> > +the World Wide Web, the @var{host} and @var{dir} parts of
> > +the cross-reference need to be known by Texinfo converters to be able
> > +to generate cross-references.  More generally you may want to specify
> > +the location of other manuals for cross-references.
> 
> This is written from the wrong POV, IMO.  The correct POV is that of a
> manual author/maintainer who wants cross-references from _other_
> manual to his/her one to be correct.  So I suggest the following
> rewording.:
> 
>   For other manuals published on the World Wide Web to be able to have
>   correct cross-references to your manual, the @var{host} and
>   @var{dir} parts of the cross-reference need to be known by Texinfo
>   converters when they produce HTML for those other manuals.
>   Similarly, for your manual in HTML format to have correct
>   cross-references to other manuals, @command{texi2any} needs to know
>   how to construct the URLs for other manuals.  This information is
>   provided by @file{htmlxref.cnf}.

I think that the two points of view need to be addressed.  I'll try to
propose something.

> > +Right now, the @file{htmlxref.cnf} file distributed with GNU Texinfo serves
> > +as the main resource to locate Texinfo HTML manuals in the World Wide Web.
> > +Since it is installed in a location used by @command{texi2any}, HTML 
> > manuals
> > +information found in this file will be used for cross-references by 
> > default.
> > +
> >  If you have additions or corrections to the @file{htmlxref.cnf}
> >  distributed with Texinfo, please email @email{bug-texinfo@@gnu.org} as
> > -usual.  You can get the latest version from
> > +usual.  If you publish a Texinfo HTML manual on the World Wide Web,
> > +having an up-to-date location listed in @file{htmlxref.cnf} should ensure 
> > that
> > +all HTML manuals generated by @command{texi2any} use this location for
> > +cross-references in the default case.  You can get the latest version from
> >  @url{http://ftpmirror.gnu.org/@/texinfo/@/htmlxref.cnf}.
> 
> I suggest to tell here explicitly that having a local htmlxref.cnf
> file with the correct information is the solution for outdated or
> missing data in the file as distributed by Texinfo.

Good idea.

-- 
Pat