bug-texinfo
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

new customization variable naming (AUTO_MENU_DESCRIPTION_*)


From: Gavin Smith
Subject: new customization variable naming (AUTO_MENU_DESCRIPTION_*)
Date: Sun, 6 Aug 2023 22:01:07 +0100

There are new customization variables AUTO_MENU_DESCRIPTION_FILLCOLUMN and
AUTO_MENU_DESCRIPTION_INDENT_LENGTH.  I'd like to consider if these are
the best names.

Here is the documentation of what these commands do, from the current
draft of the Texinfo manual:

‘AUTO_MENU_DESCRIPTION_FILLCOLUMN’
     Maximum number of columns in a line for ‘@nodedescription’ or
     ‘@nodedescriptionblock’ menu entry description formatting in Info.
     Undefined by default, in which case 10% more than the fill column
     value is used (*note Invoking texi2any::).

‘AUTO_MENU_DESCRIPTION_INDENT_LENGTH’
     Indentation for ‘@nodedescription’ or ‘@nodedescriptionblock’ menu
     entry description formatting in Info.  Undefined by default, in
     which case 44% of the fill column value is used (*note Invoking
     texi2any::).

First, AUTO_MENU_DESCRIPTION_FILLCOLUMN.  I'd argue that the
documentation here is not perfectly correct, as the value of the
variable doesn't just count the columns in the description, it is for
the entire menu line, which also includes the node name, etc.  The word
"description" in the variable name is relevant, though, as this limit
is only actually used by the code if a description is being added.

There is another variable just called FILLCOLUMN, so this is a good
reference to that variable.

The AUTO_MENU_ prefix is succinct and apposite, in my opinion.

AUTO_MENU_DESCRIPTION_INDENT_LENGTH - I question whether the value
of this variable really counts as an "indent", when it is the number
of columns before the description is to start at, but these columns
are not necessarily all spaces - the first line will always have
the node name in it.

I looked through the manual for inspiration, and thought that we could
follow some of the install-info options:

‘--max-width=COLUMN’
     Specifies the column that the menu entry’s description will be
     word-wrapped at.  COLUMN starts counting at 1.

‘--maxwidth=COLUMN’
     Same as ‘--max-width’.

‘--align=COLUMN’
     Specifies the column that the second and subsequent lines of menu
     entry’s description will be formatted to begin at.  The default for
     this option is ‘35’.  It is used in conjunction with the
     ‘--max-width’ option.  COLUMN starts counting at 1.

‘--calign=COLUMN’
     Specifies the column that the first line of menu entry’s
     description will be formatted to begin at.  The default for this
     option is ‘33’.  It is used in conjunction with the ‘--max-width’
     option.  When the name of the menu entry exceeds this column,
     entry’s description will start on the following line.  COLUMN
     starts counting at 1.

So here's my proposal:

Change AUTO_MENU_DESCRIPTION_FILLCOLUMN -> AUTO_MENU_MAX_WIDTH

Change AUTO_MENU_DESCRIPTION_INDENT_LENGTH -> AUTO_MENU_DESCRIPTION_ALIGN.

As the "align" value should be the 1-based index of the first column of
the menu description, rather than the size of the "indent", the value
provided by the user will have to be decremented by the current code.  E.g.
"align" value of 33 means an indent of 32 columns.

I can easily make this change myself if it is agreed.



reply via email to

[Prev in Thread] Current Thread [Next in Thread]