Re: Customization variables for HTML filenames like NODE_FILES

[Patrice Dumas]

On Sun, Apr 07, 2019 at 10:36:12PM +0100, Gavin Smith wrote:
> I was looking at HTML.pm to check that the rules were what I thought they 
> were for the names of output files for split HTML output.  I find there 
> are quite a lot of customization variables that affect this, including:
> 
> NODE_FILENAMES
> NODE_FILE_EXTENSION
> TOP_NODE_FILE
> TOP_NODE_FILE_TARGET
> USE_SETFILENAME_EXTENSION
> 
> I wonder if some or all of these can be removed in order to make the 
> code simpler and clearer.
> 
> 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.

That being said, I agree that this options is not really useful, and
complicates both code and customization without obvious benefit.

After your recent commit that removes NODE_FILENAMES, I added a
customization function for the Singular style that does the same as the
previous NODE_FILENAMES/NODE_FILE_EXTENSION + EXTENSION combination.

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

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

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.

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

> 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