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