[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: organization of the documentation of customization variables
|
From: |
Gavin Smith |
|
Subject: |
Re: organization of the documentation of customization variables |
|
Date: |
Sun, 17 Mar 2024 16:23:06 +0000 |
On Sat, Mar 16, 2024 at 03:53:45PM +0100, Patrice Dumas wrote:
> Hello,
>
> In a recent thread, on help-texinfo, Eli raised valid concerns on the
> documentation of customization variables of texi2any, see for example:
> https://lists.gnu.org/archive/html/help-texinfo/2024-03/msg00014.html
Quoting from that message:
What I was looking for is some kind of combination, in a single
manual, where one could find both the general background and
description of the conversion process (as texi2any_api does), and
description of the customizations via variables in the context of that
description of the conversion process. Customization by writing Perl
function should be considered a whole different level of
customizations, which I believe very few will go to, especially given
the large number of variables which presumably should already allow to
do a lot, and should therefore be described in separate subsections.
> The current situation is that in the main Texinfo manual most of the
> customization variables are simply presented in a list, like a
> reference, not in a way that makes it easy to use them, as a tutorial
> with logical groupings and background information. In the texi2any_api
> manual, the customization variables are presented in a more pedagogical
> manner, but, for now, only for some variables, and the explanation of
> the variables use appear in sections that may also cover some advanced
> way of customizating texi2any HTML output that require knowledge of
> Perl.
The first thing I would say is that the more the number of customization
variables can be minimized, the less problematic it is simply presenting
them in the manual as a simple list.
The relevant list in "(texinfo)HTML Customization Variables" is not
easy to read through from beginning to end. I feel if the documentation
could be made more clear, users would be less likely to give up trying
to read through it.
Even the second variable in the list is obscure:
‘AFTER_BODY_OPEN’
If set, the corresponding text will appear at the beginning of each
HTML file; default unset.
It is not clear what "corresponding text" means - corresponding to what?
I think it means the value of the variable but this is not clear.
‘BODYTEXT’
The text appearing in ‘<body>’. By default, sets the HTML ‘lang’
attribute to the document language (*note @documentlanguage::).
I first thought this meant the text occuring between <body> and
</body>, which would be most of the file, rather than text for the
attributes.
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.
> I think that we should decide on how the customization variables
> documentation should be organized. I think that we should keep some
> reference lists in the main Texinfo manual. But I also think that we
> should make a choice regarding a pedagogical/tutorial-oriented
> documentation of the customization variable, with two options (there may
> be more, please add some if you have ideas):
> 1) document customization variables in the texi2any_api manual even
> though it will be mixed with more advanced customization which
> requires perl code
> 2) add sections presenting customization of texi2any output with
> customization variables in the main Texinfo manual presented in a
> tutorial fashion and remove the corresponding existing documentation
> from the texi2any_api manual.
>
> What do you think?
It's of secondary importance what is done to the texi2any_api manual.
The more important thing, in my opinion, is to document the customization
variables in the texinfo manual as well as possible. So if there is content
in the texi2any_api manual on customization variables which would improved
the texinfo manual, it would be good to use it.
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.
I suggest the the list in "(texinfo)HTML Customization Variables" could
be split up into smaller nodes, potentially with some more narrative
content in each node. (For example, other non-HTML-specific variables
could be discussed, such as USE_NODES or NUMBER_FOOTNOTES.) This would
hopefully be kept brief and not reach the length or complication of the
corresponding documentation in texi2any_api.
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.
HTML Version control
To allow for some variation in the version of HTML output.
NO_CUSTOM_HTML_ATTRIBUTE
USE_XML_SYNTAX
CSS
Options relating to CSS.
INLINE_CSS_STYLE
NO_CSS
SHOW_BUILTIN_CSS_RULES
Output structure
Options affecting the overall structure of the HTML output, including
ordering and optional output.
DO_ABOUT
PROGRAM_NAME_IN_ABOUT
CONTENTS_OUTPUT_LOCATION
MONOLITHIC
SHOW_TITLE
INFO_JS_DIR
JS_WEBLABELS
JS_WEBLABELS_FILE
SHORT_TOC_LINK_TO_TOC
TOC_LINKS
TOP_FILE
USE_TITLEPAGE_FOR_TITLE
USE_NEXT_HEADING_FOR_LONE_NODE
USE_NODE_DIRECTIONS
HTML file control
Options affecting the output of a single HTML file, including header
and footer customization.
USE_LINKS
SECTION_NAME_IN_TITLE
DATE_IN_HEADER
PROGRAM_NAME_IN_FOOTER
HTML content insertion:
Arguments are HTML content to be inserted at certain points in the
output.
AFTER_BODY_OPEN
AFTER_SHORT_TOC_LINES
AFTER_TOC_LINES
BEFORE_SHORT_TOC_LINES
BEFORE_TOC_LINES
EXTRA_HEAD
PRE_BODY_CLOSE
BODYTEXT
HTML_ROOT_ELEMENT_ATTRIBUTES
Specification of HTML constructs
BIG_RULE
DEFAULT_RULE
Navigation header
For the navigation header that occurs at the beginning and/or end of
each node.
HEADER_IN_TABLE
ICONS
WORDS_IN_PAGE
VERTICAL_HEAD_NAVIGATION
File names, links and cross-references
BASEFILENAME_LENGTH
CASE_INSENSITIVE_FILENAMES
CHECK_HTMLXREF
HTMLXREF_FILE
HTMLXREF_MODE
IGNORE_REF_TO_TOP_NODE_UP
XREF_USE_FLOAT_LABEL
XREF_USE_NODE_NAME_ARG
NODE_NAME_IN_INDEX
IMAGE_LINK_PREFIX
EXTERNAL_CROSSREF_SPLIT
EXTERNAL_DIR
EXTERNAL_CROSSREF_EXTENSION
USE_ACCESSKEY
USE_REL_REV
TOP_NODE_FILE_TARGET
TOP_NODE_UP_URL
Header levels
CHAPTER_HEADER_LEVEL
FOOTNOTE_END_HEADER_LEVEL
FOOTNOTE_SEPARATE_HEADER_LEVEL
MAX_HEADER_LEVEL
Menu
Options for the output of @menu, as well as indices.
AVOID_MENU_REDUNDANCY
MENU_ENTRY_COLON
MENU_SYMBOL
INDEX_ENTRY_COLON
Output of other constructs
These only affect the output "locally" at the place where the construct
in question is used.
COMPLEX_FORMAT_IN_TABLE
DEF_TABLE
CONVERT_TO_LATEX_IN_MATH
HTML_MATH
COPIABLE_LINKS
NO_NUMBER_FOOTNOTE_SYMBOL
USE_ISO