Re: organization of the documentation of customization variables

[Patrice Dumas]

On Sun, Mar 17, 2024 at 04:23:06PM +0000, Gavin Smith wrote:
> I do not personally know what all the customization variables are for
> and have always found them overwhelming.  There may be variables which
> aren't very useful or which are rarely used.

That's possible, but the last time I had a look, I did not find much to
remove.
 
> I think that the main texinfo manual should be kept clear from discussion
> of the Perl API, which may mean duplicating documentation of customization
> variables between the two manuals in some places.

Agreed.

> I took the list and tried to sort it into sections.  I may not have
> done an especially good job of this, and there will likely be misplaced
> variables.  I suggest this could be taken as a starting point for
> reorganising the manual.

I started from that and did two nodes, as can be seen in the commit
https://git.savannah.gnu.org/cgit/texinfo.git/commit/?id=c0a8822909514e947cefc7112986a2e704a023d0

Before I continue, is what I did the expected content?

In term of overall organization of the manual, I think that where I have
put those nodes, where the HTML customization variables currently are is
not good.

Here is what I propose:

* move HTML customization variables explanations to the 'Generating HTML'
  chapter, either in an already existing section where they would be
  inserted naturally (for example in the 'HTML CSS' section for
  customization variables related to CSS) or to new sections or
  subsections.  For exampl, I think that the new 'HTML Output Structure
  Customization' node could be before 'Generating EPUB' or together with
  'HTML Splitting', while 'File Names and Links Customization for HTML'
  could be after 'HTML Cross-references' probably with other
  customization variables nodes.
* Move the 'HTML Customization Variables List' node to an appendix.

What do you think?

-- 
Pat