Re: Customization variables for HTML filenames like NODE_FILES

[Gavin Smith]

On Tue, Apr 16, 2019 at 12:23:02AM +0200, Patrice Dumas wrote:
> > NODE_FILENAMES (and the --node-filenames option) seems to be a holdover 
> > from texi2html, before node filenames were named in a predictable way.
> 
> I do not think so, I think that it allowed to have the generation of the
> file required for the inter manual links and also have other files
> generated with another extensions.  This was actually used in the
> Singular manual.

I was confused: there is no --node-filenames option.  (I was thinking of 
--node-files which is used for redirection files.)  The NODE_FILENAMES 
option could be used to give filenames like "elisp_859.html" instead of 
"Comment-Tips.html".  I see that is what is done at 
https://www.singular.uni-kl.de/Manual/4-0-3/, with filenames like 
sing_5.htm -- is that the Singular manaul you refer to?

Those pages state they are generated by texi2html.  If they ever start 
using texi2any instead, is there any reason why they would need to keep 
that scheme?

> > The only use I can think of for NODE_FILE_EXTENSION is to use ".htm" 
> > instead of ".html" on MS-DOS - not worth worrying about.
> 
> Actually to be able to use both, .htm for files not used as targets from
> external manuals, and .html for files used as targets from external 
> manuals.

I don't understand; what HTML files that texi2any generates would not be 
linked to from other HTML manuals?  My understanding is that 
NODE_FILE_EXTENSION was used for all of the HTML files that texi2any 
generated.

Do you mean that with NODE_FILE_EXTENSION, links to other manuals would 
still use '.html'?

I saw the change that you made to use EXTENSION instead of 
NODE_FILE_EXTENSION, with external links hardcoded to use '.html' -- that 
seems fine to me and is consistent with other output formats.

> 
> > TOP_NODE_FILE and TOP_NODE_FILE_TARGET should always be "index" 
> > (basename of file containing "Top" node).
> 
> Actually, there are 3 options for the Top node file, TOP_FILE, 
> TOP_NODE_FILE and TOP_NODE_FILE_TARGET.  TOP_FILE and TOP_NODE_FILE
> seem to be redundant, maybe now that NODE_FILENAMES is gone.
> 
> I think that one of TOP_NODE_FILE or TOP_FILE should be removed.
> Probably TOP_NODE_FILE, in order to keep TOP_FILE only.

I've removed TOP_NODE_FILE.

> TOP_NODE_FILE_TARGET (which I just changed to be index.html) allows to 
> have a different TOP_FILE/TOP_NODE_FILE and target for the other
> manuals (and file added with --node-files/NODE_FILES).
> 
> I think that this option could stay.

I agree it is simpler to include the extension in the value of 
TOP_NODE_FILE_TARGET.  But the Top node file for other manuals will 
always be 'index.html' if these manuals have been generated in such a 
way that they can be linked to reliably.  Moreover, if a manual links to 
more than one external manual, there is no way to specify different 
filenames for the Top nodes of those manuals.

TOP_NODE_FILE_TARGET doesn't interact with other options now and I don't 
think it would much of a maintenance burden.

> > It is not useful to set USE_SETFILENAME_EXTENSION explicitly (the extension 
> > to the argument to @setfilename, usually .info, is only used for Info 
> > output).
> 
> Indeed, but this needs to remain in one way or another, to do something
> different for info and other formats.  It is explicitly said that users
> should not modify it:
> 
> 'USE_SETFILENAME_EXTENSION'
>      Default is on for Info, off for other output.  If set, use exactly
>      what '@setfilename' gives for the output file name, including the
>      extension.  You should not need to explicitly set this variable.
> 
> I think that this one should stay.

What's the point of making this visible to the users?  Couldn't it be 
made the default behaviour without an option?  I could think of these 
two use cases:

* If you want to say something like "@setfilename manual.htm" for a 
manual that is only converted to HTML, and not to Info -- but this would 
be an incorrect use of @setfilename.
* If you are outputting to Info, and you want to override the 
@setfilename command in the file (e.g. if they had done "@setfilename 
manual", with no extension).  I think this could be dealt with by 
setting EXTENSION to the desired extension.

> > In general, removing useless customization variables is a good thing, as
> > it makes the code clearer, and makes useful customization variables 
> > easier to notice in the manual.  I am not in a rush to remove as many 
> > customization variables as possible, but removing a few at a time seems 
> > like a good idea.  It would help to hold down the complexity of the 
> > Texinfo project, and improve its long-term maintainability, even as it
> > possibily gets more complex in other areas.
> 
> I would be in favor of removing PREFIX too.  There is nothing that can
> really replace it, but the usefulness of that option is not clear, and
> the description in the documentation is very unclear.  It is used in the
> Singular style manual too, so I think that it would be better to first
> try to find another way to do the same with customization functions
> before removing it.
> 
> -- 
> Pat