Re: HTML <title> node names: Not emitting 'Top (Manual name)'

Arsen Arsenović <[email protected]> Sun, 17 Mar 2024 13:42:55 +0100
Newsgroups	gmane.comp.tex.texinfo.general
Message-ID	<[email protected]>
Hi,

[this wide-reply fail has happened again..  apologies.  my MUA keymaps
 need fixing]

Gavin Smith <[email protected]> writes:

> On Fri, Mar 15, 2024 at 09:42:28AM +0200, Eli Zaretskii wrote:
>> > What we envisionned, instead, was to provide with the HTML customization
>> > API to do the kind of modifications you want to do.  I can imagine a
>> > number of reasons why this solution is not that attractive for your use
>> > case, for instance it does not allow to be compatible with a wide range
>> > of makeinfo releases, may not be that stable, is in Perl, and could
>> > require important work.  Still, maybe you could consider using that
>> > possibility in the future if you face incompatible changes again.
>> 
>> I think the main reason this solution is not used is that it is still
>> a kind of "black magic" for almost everyone, definitely for me
>> personally.  The relevant sections of the Texinfo manual are basically
>> a very terse man-page style reference of options in alphabetical
>> order, without any kind of tutorial or general explanations or
>> examples (without which it is hard to even understand some of the
>> customization variables unless one is an HTML expert).  This is very
>> unlike the other sections of the manual, which invariably provide
>> detailed background explanations for each group of commands, describe
>> the recommended practices, and provide a lot of examples.  I write
>> Texinfo manuals for 20 years, and still consult the Texinfo manual all
>> the time, always finding valuable information in it in the sections
>> that describe the Texinfo language and how to use them in a
>> well-written manual.
>> 
>> With better documentation, it is quite possible that we could consider
>> switching most, if not all, of the code in admin.el to using the
>> texi2any customization capabilities -- provided again that those
>> customization variables can be relied upon to be stable enough,
>> without fearing they will be completely redesigned at some future
>> time.
>
> It is probably better to use customization with options and variables
> ("data driven") than customization based on writing code that hooks into the
> internals ("code driven"), if the former is possible to achieve.  This
> is simpler and easier to understand.
>
> For example, I looked at the mentioned code at
> https://git.savannah.gnu.org/cgit/emacs.git/tree/admin/admin.el
> (the manual-html-fix-* functions) and it is not instantly apparent what
> all of the code is supposed to achieve.
>
> Hence, it would be better to try to understand what the Emacs distribution
> code is doing to the HTML output and if customization variables and/or
> the default output could support this.
>
> The code driven customization is more coupled to internals that
> could change, although in theory is more powerful.

A form of "semi" data driven customization that we don't currently
utilize is templating engines.  We could have templates for various
elements that other templates then use recursively etc.  Jinja2 is a
nice (but Python, not Perl) example of a templating engine, if you'd
like to get a feel for how such a template looks, and I believe
Asciidoctor also uses this approach.

This'd give users a relatively simple and intuitive way to tweak some
bits of HTML (given that templates tend to be HTML interspersed with
custom tags or a language isomorphic to HTML), while providing something
perhaps not too difficult to keep stable for Texinfo maintainers.
-- 
Arsen Arsenović
signature.asc (application/pgp-signature, 251 B)