Re: Setting up user defined texinfo headlines using outline-heading-alist

[Christopher Dimech <dimech@gmx.com>]

> Sent: Friday, May 14, 2021 at 4:05 AM
> From: "Yuri Khan" <yuri.v.khan@gmail.com>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: "Help Gnu Emacs" <help-gnu-emacs@gnu.org>
> Subject: Re: Setting up user defined texinfo headlines using outline-heading-alist
>
> On Thu, 13 May 2021 at 22:10, Christopher Dimech <dimech@gmx.com> wrote:
> 
> > I have followed your suggestion of using a function that sets outline-heading-alist
> > using texinfo-mode-hook.
> >
> > Have included the following setup (see code section), yet I am still getting
> >
> > @node uchapter-amcoh
> > @unnumbered 6 @ Ameliorating Waveform Coherency...
> >
> > whenever I hit  "C-C @ C-t" (Hide Body).  Should I not get @usec and @usubsec
> > showing up as well?
> 
> Now that you gave a recipe, I was able to reproduce it. I saved your
> test.texi and put your code into /tmp/20210513/.emacs and started
> Emacs as “HOME=. emacs test.texi”. This way, my own config does not
> affect the reproduction.
> 
> I pressed C-c @ C-t, and, yes, everything after the first heading got
> collapsed. So next I pressed C-c @ C-h to see what other commands are
> available. I spotted C-c @ C-a (outline-show-all) as the way to expand
> it all back, and C-c @ C-n (outline-next-visible-heading) as a
> reasonable way to check what Emacs thinks are your headings. And,
> predictably, starting at the top, it stopped on @unnumbered, and then
> at the bottom of the buffer. Which means it does not detect @usec as a
> heading.
> 
> Next, I went to read the docstring on outline-next-visible-heading. And it says:
> 
>     A heading line is one that starts with a ‘*’ (or that
>     ‘outline-regexp’ matches).
> 
> So next let’s see what outline-regexp is:
> 
>     outline-regexp is a variable defined in ‘outline.el’.
>     Its value is "[*^L]+"
>     […]
>     Regular expression to match the beginning of a heading.
>     Any line whose beginning matches this regexp is considered to
> start a heading.
>     Note that Outline mode only checks this regexp at the start of a line,
>     so the regexp need not (and usually does not) start with ‘^’.
> 
> So let’s change your hook function to set that:
> 
>     (defun instate-texinfo-hdlevels ()
>       (setq-local outline-heading-alist texinfo-hdlevels)
>       (setq-local outline-regexp
>                   (concat (regexp-opt (mapcar 'car texinfo-hdlevels)) "\\>")))
> 
> Now I press C-M-x within the above source to update the function
> definition, switch to test.texi, and press M-x normal-mode RET to
> reapply the major mode, which reruns all its hooks, which sets the
> variables as needed. Now, C-c @ C-n from the top goes through
> @unnumbered, @usec, @usec, @usubsec, @usec, @usubsec, bottom; and C-c
> @ C-t leaves all custom headings visible:
> 
>     @node uchapter-amcoh
>     @unnumbered 6 @ Ameliorating Waveform Coherency...
>     @usec{@value{seclb}, Abductive Reasoning}...
>     @usec{@value{seclb}, Parsimony over Complexity}...
>     @usubsec{@value{seclb}, The Claerbout Conjecture}...
>     @usec{@value{seclb}, Correlograms in Helioseismology}...
>     @usubsec{@value{seclb}, Solar Magnetic Cycle and the Interface Dynamo}...
> 
> Now I save the modified .emacs and restart this Emacs instance to see
> if my solution works when applied from the init file. It does, so I am
> confident enough to post it.

Yes, your code works.  Nevertheless, I find all this extremely confusing.

For instance:

1. outline.el does not state how to set a user defined outline-regexp or guide 
   you to a particular implementation such as texinfo.el

2. texinfo.el uses a convoluted way to set outline-heading-alist and outline-regexp.

2a. Firstly texinfo.el tries to play around with texinfo-section-list, excluding the
    initial "@" fog texinfo-commands.  The implementation certainly does not watch the
    example on how to set up outline-heading-alist as described in the docstring of
    outline-heading-alist in "outline.el".

2b. outline-heading-alist provides the following example: 

(setq outline-heading-alist
      \\='((\"@chapter\" . 2) (\"@section\" . 3) (\"@subsection\" . 4)
           (\"@subsubsection\" . 5)
        (\"@unnumbered\" . 2) (\"@unnumberedsec\" . 3)
           (\"@unnumberedsubsec\" . 4)  (\"@unnumberedsubsubsec\" . 5)
        (\"@appendix\" . 2) (\"@appendixsec\" . 3)...
           (\"@appendixsubsec\" . 4) (\"@appendixsubsubsec\" . 5) ..))

This is not a real working example because of the additional "..." and ".." in
the declaration.

Consequently, the code rather than helping others see how to set things up, confuses
them because of the inconsistencies described. 

So again, I do not understand how to set outline-heading-alist for a user who wants
to define his own headers.

I also fail to understand how to visualise any differences between different heading
levels.

It is then very easy to tell a user to learn more elisp, rather than convince a
developer to be consistent and write in ways that assist in the reuse of their 
code.
 
> Next you might want to read the full docstring for outline-regexp, as
> it tells you the recommended way to set it so that it travels with
> your file rather than lives in your personal configuration. You might
> also see if setting outline-heading alist the same way works.
>