all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
From: Christopher Dimech <dimech@gmx.com>
To: Yuri Khan <yuri.v.khan@gmail.com>
Cc: Help Gnu Emacs <help-gnu-emacs@gnu.org>
Subject: Re: Setting up user defined texinfo headlines using outline-heading-alist
Date: Thu, 13 May 2021 20:35:51 +0200	[thread overview]
Message-ID: <trinity-645fd002-b3e5-4a22-b1fd-9cc1801b04fd-1620930951479@3c-app-mailcom-bs03> (raw)
In-Reply-To: <CAP_d_8XmK=o0czsvgsK02OuHdS3V0z3WdMRYU_OrN=rksTj61A@mail.gmail.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.
>



  parent reply	other threads:[~2021-05-13 18:35 UTC|newest]

Thread overview: 46+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-05-10 14:21 outline-heading-alist for elisp using ";; * " Christopher Dimech
2021-05-10 21:08 ` Philip Kaludercic
2021-05-11  1:55   ` Christopher Dimech
2021-05-11  3:00     ` Stefan Monnier via Users list for the GNU Emacs text editor
2021-05-11  5:05       ` Christopher Dimech
2021-05-11 12:06         ` Jean Louis
2021-05-11 12:40           ` Christopher Dimech
2021-05-11 14:17             ` Jean Louis
2021-05-11 12:56           ` Christopher Dimech
2021-05-11 14:20             ` Jean Louis
2021-05-11 15:32               ` Christopher Dimech
2021-05-11 18:09                 ` Jean Louis
2021-05-12  1:46                   ` Christopher Dimech
2021-05-12  4:00                     ` Jean Louis
2021-05-13  3:33                       ` Christopher Dimech
2021-05-13  7:22                         ` Jean Louis
2021-05-13  7:41                           ` Christopher Dimech
2021-05-13 10:03                             ` Jean Louis
2021-05-13 10:22                               ` Christopher Dimech
2021-05-13 10:33                                 ` Jean Louis
2021-05-13 11:37                                   ` Christopher Dimech
2021-05-11 13:15           ` Christopher Dimech
2021-05-11 14:22             ` Jean Louis
2021-05-11 15:22               ` Christopher Dimech
2021-05-12  1:53       ` Christopher Dimech
2021-05-12 12:31         ` Stefan Monnier
2021-05-12 12:43           ` Christopher Dimech
2021-05-12 14:35             ` Yuri Khan
2021-05-12 14:52               ` Christopher Dimech
2021-05-13 12:29               ` Setting up user defined texinfo headlines using outline-heading-alist Christopher Dimech
2021-05-13 13:26                 ` Yuri Khan
2021-05-13 15:10                   ` Christopher Dimech
2021-05-13 16:05                     ` Yuri Khan
2021-05-13 18:29                       ` Jean Louis
2021-05-13 18:48                         ` Christopher Dimech
2021-05-13 19:01                         ` Yuri Khan
2021-05-13 18:35                       ` Christopher Dimech [this message]
2021-05-13 19:13                         ` Yuri Khan
2021-05-14  3:49                           ` Christopher Dimech
2021-05-14  3:56                             ` Stefan Monnier via Users list for the GNU Emacs text editor
2021-05-14  5:25                               ` Christopher Dimech
2021-05-13 15:34                   ` Jean Louis
2021-05-11  2:52   ` outline-heading-alist for elisp using ";; * " Christopher Dimech
2021-05-11  4:50   ` Jean Louis
2021-05-11  5:17     ` Christopher Dimech
2021-05-11 20:54 ` Jeremie Juste

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=trinity-645fd002-b3e5-4a22-b1fd-9cc1801b04fd-1620930951479@3c-app-mailcom-bs03 \
    --to=dimech@gmx.com \
    --cc=help-gnu-emacs@gnu.org \
    --cc=yuri.v.khan@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.