[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: HTML <title> node names: Not emitting 'Top (Manual name)'
From: |
Arsen Arsenović |
Subject: |
Re: HTML <title> node names: Not emitting 'Top (Manual name)' |
Date: |
Sun, 17 Mar 2024 13:42:55 +0100 |
Hi,
[this wide-reply fail has happened again.. apologies. my MUA keymaps
need fixing]
Gavin Smith <gavinsmith0123@gmail.com> 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
Description: PGP signature
- Re: HTML <title> node names: Not emitting 'Top (Manual name)', (continued)
- Re: HTML <title> node names: Not emitting 'Top (Manual name)', Eli Zaretskii, 2024/03/16
- Re: HTML <title> node names: Not emitting 'Top (Manual name)', pertusus, 2024/03/16
- Re: HTML <title> node names: Not emitting 'Top (Manual name)', Gavin Smith, 2024/03/17
- Re: HTML <title> node names: Not emitting 'Top (Manual name)', pertusus, 2024/03/17
- Re: HTML <title> node names: Not emitting 'Top (Manual name)', Gavin Smith, 2024/03/17
- Re: HTML <title> node names: Not emitting 'Top (Manual name)', Gavin Smith, 2024/03/17
- Re: HTML <title> node names: Not emitting 'Top (Manual name)', pertusus, 2024/03/17
- Re: HTML <title> node names: Not emitting 'Top (Manual name)', Gavin Smith, 2024/03/17
- Re: HTML <title> node names: Not emitting 'Top (Manual name)', Eli Zaretskii, 2024/03/17
- Re: HTML <title> node names: Not emitting 'Top (Manual name)', pertusus, 2024/03/17
- Re: HTML <title> node names: Not emitting 'Top (Manual name)',
Arsen Arsenović <=
- Re: HTML <title> node names: Not emitting 'Top (Manual name)', Patrice Dumas, 2024/03/15
- Re: HTML <title> node names: Not emitting 'Top (Manual name)', Eli Zaretskii, 2024/03/16
- Re: HTML <title> node names: Not emitting 'Top (Manual name)', Patrice Dumas, 2024/03/16