Tweaking the output of `C-h b'

Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Currently, `C-h b' start with:

Key translations:
key             binding
---             -------

C-x		Prefix Command
A-SPC		 
A-!		¡
A-"		Prefix Command
A-$		¤
A-'		Prefix Command
A-*		Prefix Command
A-+		±
A-,		Prefix Command
A--		­

That goes on for 700 lines (for me) before we get to

`gnus-agent-group-mode' Minor Mode Bindings:
key             binding
---             -------

J		Prefix Command

J S		gnus-group-send-queue
J Y		gnus-agent-synchronize-flags

etc, which is where the useful stuff starts.

Now, the current order is (strictly speaking) correct, because those key
translations are real and they take precedence over the rest of the
bindings.  But the likelihood of a user wanting to inspect that stuff is
pretty low, and it's just so...  long.

Does anybody mind if I put it at the end of the buffer, with at the
start of the buffer saying

"Key translations take precedence, click here to see them"

and clicking there taking you to the start of the translations (towards
the end of the buffer)?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Eric Abrahamsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Currently, `C-h b' start with:
>
> Key translations:
> key             binding
> ---             -------
>
> C-x		Prefix Command
> A-SPC		 
> A-!		¡
> A-"		Prefix Command
> A-$		¤
> A-'		Prefix Command
> A-*		Prefix Command
> A-+		±
> A-,		Prefix Command
> A--		­
>
> That goes on for 700 lines (for me) before we get to
>
> `gnus-agent-group-mode' Minor Mode Bindings:
> key             binding
> ---             -------
>
> J		Prefix Command
>
> J S		gnus-group-send-queue
> J Y		gnus-agent-synchronize-flags
>
> etc, which is where the useful stuff starts.
>
> Now, the current order is (strictly speaking) correct, because those key
> translations are real and they take precedence over the rest of the
> bindings.  But the likelihood of a user wanting to inspect that stuff is
> pretty low, and it's just so...  long.
>
> Does anybody mind if I put it at the end of the buffer, with at the
> start of the buffer saying
>
> "Key translations take precedence, click here to see them"
>
> and clicking there taking you to the start of the translations (towards
> the end of the buffer)?

No, and please close bug#22334 when you do!

Re: Tweaking the output of `C-h b'

[Andreas Schwab]

You can skip over a section with forward-page.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

Re: Tweaking the output of `C-h b'

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Sun, 31 Oct 2021 19:18:56 +0100
> 
> Currently, `C-h b' start with:
> 
> Key translations:
> key             binding
> ---             -------
> 
> C-x		Prefix Command
> A-SPC		 
> A-!		¡
> A-"		Prefix Command
> A-$		¤
> A-'		Prefix Command
> A-*		Prefix Command
> A-+		±
> A-,		Prefix Command
> A--		­
> 
> That goes on for 700 lines (for me) before we get to

How about adding a series of buttons at the beginning of the buffer,
which will allow you to jump to the part of interest instantaneously,
in the same manner as "C-h m" does?  Then the order of presentation is
of much lower importance.

Re: Tweaking the output of `C-h b'

[Eli Zaretskii]

> Date: Sun, 31 Oct 2021 20:36:09 +0200
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: emacs-devel@gnu.org
> 
> > From: Lars Ingebrigtsen <larsi@gnus.org>
> > Date: Sun, 31 Oct 2021 19:18:56 +0100
> > 
> > Currently, `C-h b' start with:
> > 
> > Key translations:
> > key             binding
> > ---             -------
> > 
> > C-x		Prefix Command
> > A-SPC		 
> > A-!		¡
> > A-"		Prefix Command
> > A-$		¤
> > A-'		Prefix Command
> > A-*		Prefix Command
> > A-+		±
> > A-,		Prefix Command
> > A--		­
> > 
> > That goes on for 700 lines (for me) before we get to
> 
> How about adding a series of buttons at the beginning of the buffer,
> which will allow you to jump to the part of interest instantaneously,
> in the same manner as "C-h m" does?  Then the order of presentation is
> of much lower importance.

Btw, this 700-line list of "prefix commands" seems to be the result of
preloading iso-transl?  So maybe we should rethink that decision?

Re: Tweaking the output of `C-h b'

[Stefan Monnier]

> Does anybody mind if I put it at the end of the buffer, with at the
> start of the buffer saying
>
> "Key translations take precedence, click here to see them"

I think many of our Help buffers would benefit from some kind of
"folding", so instead of moving something to the end, we can just
default to folding that part.


        Stefan

Re: Tweaking the output of `C-h b'

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Now, the current order is (strictly speaking) correct, because those key
> translations are real and they take precedence over the rest of the
> bindings.  But the likelihood of a user wanting to inspect that stuff is
> pretty low, and it's just so...  long.

I usually say `C-h b C-s' to find what I'm looking for, so the length
isn't very important to me.  But, on the other hand, it would save me
some typing if what I usually want is at the top.  So in my use, it
doesn't matter too much if we have 50 lines or 5000 before the bits I
want.  The thing that would really help me is having closer to zero.

So I'd definitely appreciate the change you suggest.

Re: Tweaking the output of `C-h b'

[Stefan Monnier]

> My feeling is that many (most?) people don't know that this is how
> outline works (which is why that help text is important).  However --
> why can't the headings here just be buttons?  Everybody knows that you
> can RET/click on buttons to make them do something.  Which would make
> the explanation unnecessary.
>
> Or if we don't want to do that, then:
>
> "Key translations (hit TAB to see)"

Shouldn't we have those standard triangles/arrows on which to click to
hide/unhide?


        Stefan

Re: Tweaking the output of `C-h b'

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: emacs-devel@gnu.org
> Date: Sun, 31 Oct 2021 20:54:23 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Btw, this 700-line list of "prefix commands" seems to be the result of
> > preloading iso-transl?  So maybe we should rethink that decision?
> 
> I think preloading iso-transl makes sense (i.e., it fixes a real UI
> thing), and I haven't seen anybody complain about it.  It's just `C-h b'
> it affects negatively, I think, so I'd prefer fixing that instead.

Perhaps there's another solution for that UI thing, one that doesn't
have such adverse effects on "C-h b".

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> Shouldn't we have those standard triangles/arrows on which to click to
> hide/unhide?

Yes, that'd be nice.  Perhaps with a user option to toggle between
classic "..." outlining and triangles?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Stefan Monnier]

Lars Ingebrigtsen [2021-10-31 21:09:59] wrote:
> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>> Shouldn't we have those standard triangles/arrows on which to click to
>> hide/unhide?
> Yes, that'd be nice.  Perhaps with a user option to toggle between
> classic "..." outlining and triangles?

I don't see we can't have both,


        Stefan

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

[-- Attachment #1: Type: text/plain, Size: 96 bytes --]

By the way, while looking at this, there's also a very puzzling display
glitch in the keymaps:


[-- Attachment #2: Type: image/png, Size: 13017 bytes --]

[-- Attachment #3: Type: text/plain, Size: 113 bytes --]


Note that <up> being indented a TAB too much.  However, if I cut and
paste that into a different buffer I get:


[-- Attachment #4: Type: image/png, Size: 10559 bytes --]

[-- Attachment #5: Type: text/plain, Size: 332 bytes --]


This happens when calling indent-to on something that's 7 characters
long, and it inserts two TABs to get to 16.  Anybody know what's up with
that?  I.e., a TAB at position 6 takes us to 8, but at 7 it takes us to
16 instead.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> This happens when calling indent-to on something that's 7 characters
> long, and it inserts two TABs to get to 16.  Anybody know what's up with
> that?  I.e., a TAB at position 6 takes us to 8, but at 7 it takes us to
> 16 instead.

It's the face:

(defface help-key-binding
[...]
    (((class color) (min-colors 88) (background dark))
     :background "grey19" :foreground "LightBlue"
     :box (:line-width (1 . -1) :color "grey35"))

The box makes a TAB in column 7 think it needs more space.  It also
makes cursor movement misbehave.  Test case:

(insert "1234567\n" (propertize "1234567\n" 'face 'help-key-binding))

Put point on 3 on the first line and hit <down>.  It'll take you to 2.
(At least that's what happens to me.)

The thing is that they're of identical width -- the box is on the
"inside" of the glyph.  Perhaps the stuff that handles :box believes
that all en-:box-ened glyphs are bigger?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Kévin Le Gouguec]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>
>> Shouldn't we have those standard triangles/arrows on which to click to
>> hide/unhide?
>
> Yes, that'd be nice.  Perhaps with a user option to toggle between
> classic "..." outlining and triangles?

Jonas's magit-section (available on NonGNU ELPA) more or less does
exactly that: on the GUI, add chevrons to the left fringe (right chevron
means "hit TAB to expand", down chevron means "hit TAB to fold back");
on the TUI, append ellipses to expandable sections.

It's not 100% feature-complete (IIRC it does not fall back to ellipses
on GUI when there's no fringe, and it has no mouse support), but FWIW
I'd love for outline(-minor)-mode to behave similarly.

(This might have been mentioned in the thread, but Juri recently
introduced describe-bindings-outline, which enables outline-minor-mode
in C-h b)

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> Yes, that'd be nice.  Perhaps with a user option to toggle between
>> classic "..." outlining and triangles?
>
> I don't see we can't have both,

Why not indeed.

Looking at outline-minor-mode, it just uses the standard Emacs
invisibility thing, so it just applies text properties without altering
the text of the buffer, which is nice.  What's the best way to add some
buttons, then?  Zero-length overlays with display/local-map properties
at the start of the line?  No, doesn't seem to work...

An overlay covering the first character, and then repeating the first
char as the last element in the display property?  Yes, that's seems to
work.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Stefan Monnier]

> buttons, then?  Zero-length overlays with display/local-map properties
> at the start of the line?  No, doesn't seem to work...

IIRC it can be an overlay (zero-width or other) with an
`after/before-string` with `display` property.

> An overlay covering the first character, and then repeating the first
> char as the last element in the display property?  Yes, that's seems to
> work.

And this should also work with a property (i.e. as a text-property), IIRC.


        Stefan

Re: Tweaking the output of `C-h b'

[Howard Melman]

Stefan Kangas <stefankangas@gmail.com> writes:

> Lars Ingebrigtsen <larsi@gnus.org> writes:
>
>> Now, the current order is (strictly speaking) correct, because those key
>> translations are real and they take precedence over the rest of the
>> bindings.  But the likelihood of a user wanting to inspect that stuff is
>> pretty low, and it's just so...  long.
>
> I usually say `C-h b C-s' to find what I'm looking for, so the length
> isn't very important to me.  But, on the other hand, it would save me
> some typing if what I usually want is at the top.  So in my use, it
> doesn't matter too much if we have 50 lines or 5000 before the bits I
> want.  The thing that would really help me is having closer to zero.
>
> So I'd definitely appreciate the change you suggest.

FWIW some completion packages define commands like

- helm-descbinds
- counsel-descbinds
- embark-bindings

which read bindings via completing-read and show the
function and its description.  It might be useful if emacs
had such a command built in.  FIlting via completion could
be more useful then isearch.

-- 

Howard

Re: Tweaking the output of `C-h b'

[Stefan Monnier]

> It's not 100% feature-complete (IIRC it does not fall back to ellipses
> on GUI when there's no fringe, and it has no mouse support), but FWIW
> I'd love for outline(-minor)-mode to behave similarly.

FWIW, I find the little triangle visually insufficient, mostly because
I'm never completely sure what state it represents (or more
specifically, because I'm not sure if the icon represents the action
that will take place when I click on it or if it represents the current
state (I suffer from the same confusion with things like the mute button
in video-conferencing software)).  So I think it's much more clear if we
complement the triangle with the ellipses.


        Stefan

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> IIRC it can be an overlay (zero-width or other) with an
> `after/before-string` with `display` property.

I tried that now, but then I couldn't move point to the displayed
string?

>> An overlay covering the first character, and then repeating the first
>> char as the last element in the display property?  Yes, that's seems to
>> work.
>
> And this should also work with a property (i.e. as a text-property), IIRC.

Yup.  Hm...  since outline adds keymaps via font-lock, perhaps that's
better than using overlays.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Stefan Monnier]

>> IIRC it can be an overlay (zero-width or other) with an
>> `after/before-string` with `display` property.
> I tried that now, but then I couldn't move point to the displayed
> string?

Indeed, you can click on it with the mouse, but I don't think we offer
a mechanism to do that from the keyboard (not sure if clicking with the
mouse in a tty can do it either).

That's a problem we should fix regardless of this discussion.

>>> An overlay covering the first character, and then repeating the first
>>> char as the last element in the display property?  Yes, that's seems to
>>> work.
>> And this should also work with a property (i.e. as a text-property), IIRC.

[ Hmm... sorry for this brain misfire.  Instead of "with property"
  I distinctly remember intending to write "without overlay".
  Probably an alpha particle hitting my brain just at the wrong
  moment, flipping some neuron.  ]


        Stefan

Re: Tweaking the output of `C-h b'

[Gregory Heytings]

>
> Does anybody mind if I put it at the end of the buffer, with at the 
> start of the buffer saying
>
> "Key translations take precedence, click here to see them"
>
> and clicking there taking you to the start of the translations (towards 
> the end of the buffer)?
>

Don't we already have that?

(setq describe-bindings-outline t)

was added about six months ago by Juri, and does what you want AFAICS: it 
hides the "Key translations" section, which you can open with TAB.

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> Indeed, you can click on it with the mouse, but I don't think we offer
> a mechanism to do that from the keyboard (not sure if clicking with the
> mouse in a tty can do it either).

I've now implemented this and pushed it to master.  It probably should
be tweaked some (and I only tested the outline stuff in a *Help* buffer,
so if somebody could check whether I broke something in more advanced
Outline minor-mode buffers, that'd be nice).

> That's a problem we should fix regardless of this discussion.

Yup.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Kévin Le Gouguec]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>
>> Indeed, you can click on it with the mouse, but I don't think we offer
>> a mechanism to do that from the keyboard (not sure if clicking with the
>> mouse in a tty can do it either).
>
> I've now implemented this and pushed it to master.  It probably should
> be tweaked some (and I only tested the outline stuff in a *Help* buffer,
> so if somebody could check whether I broke something in more advanced
> Outline minor-mode buffers, that'd be nice).

Nice work!

Some nits:

- Should the variable names include _minor-mode_?  Is there a reason
  these buttons could not be used in the Outline major mode (which would
  make them usable in Org)?

  (FWIW I tried to enable this in NEWS, but the buttons did not seem
  very functional there)

- Customize has recently gained new SVG icons, among which the exact
  same chevrons.  I happen to quite like the way they look; any chance
  these icons could be reused for this feature, at least as an option?

- For some reason,

    emacs -Q
    C-h b
    C-x o       ; move to *Help* buffer
    n           ; move to "Major Mode Bindings" button
    RET

  … moves point back one character, instead of folding the bindings?


Despite the nits, this all looks very nice.  Thanks a lot!

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Kévin Le Gouguec <kevin.legouguec@gmail.com> writes:

> - Should the variable names include _minor-mode_?  Is there a reason
>   these buttons could not be used in the Outline major mode (which would
>   make them usable in Org)?

I assume that people that use Outline mode proper would know (and like)
the TAB action.  But it's pretty obscure if you haven't been exposed to
it before, which happens a lot with outline-minor-mode. 

> - Customize has recently gained new SVG icons, among which the exact
>   same chevrons.  I happen to quite like the way they look; any chance
>   these icons could be reused for this feature, at least as an option?

Sure, using SVG icons here would be nice.  Perhaps the logic to choose
whether to use SVG or not can be reused here?

> - For some reason,
>
>     emacs -Q
>     C-h b
>     C-x o       ; move to *Help* buffer
>     n           ; move to "Major Mode Bindings" button
>     RET
>
>   … moves point back one character, instead of folding the bindings?

I'm unable to reproduce that, but point movement in the *Help* buffer
when using outline mode is really odd.  Due to the invisible overlays?

> Despite the nits, this all looks very nice.  Thanks a lot!

Thanks.  :-)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

>      :box (:line-width (1 . -1) :color "grey35"))

Oh, it was just the Y that was negative -- the X was wider, even if it
wasn't noticeable in the buffer.

The following patch fixes the issue and makes things line up better:

diff --git a/lisp/faces.el b/lisp/faces.el
index 83c6b69532..84180eadc0 100644
--- a/lisp/faces.el
+++ b/lisp/faces.el
@@ -2879,10 +2879,10 @@ help-key-binding
      ;; We use negative thickness of the horizontal box border line to
      ;; avoid enlarging the height of the echo-area display, which
      ;; would then move the mode line a few pixels up.
-     :box (:line-width (1 . -1) :color "grey80"))
+     :box (:line-width (-1 . -1) :color "grey80"))
     (((class color) (min-colors 88) (background dark))
      :background "grey19" :foreground "LightBlue"
-     :box (:line-width (1 . -1) :color "grey35"))
+     :box (:line-width (-1 . -1) :color "grey35"))
     (((class color grayscale) (background light)) :background "grey90")
     (((class color grayscale) (background dark)) :background "grey25")
     (t :background "grey90"))


-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

While we're prettyfying the `C-h b' output...  Here's a random section.

-------------

`emacs-lisp-mode' Major Mode Bindings:
key             binding
---             -------

C-c		Prefix Command
ESC		Prefix Command
DEL		backward-delete-char-untabify
C-H-x		??
H-v		eval-current-buffer

C-c d		??
C-c s		lars-patch-strip

C-M-i		completion-at-point
C-M-q		indent-pp-sexp
C-M-x		eval-defun

-------------

Is the "prefix command" thing vital to know?  And should the ??'s be
fixed?  And the spacing doesn't seem optimal.  So what about:

-------------

`emacs-lisp-mode' Major Mode Bindings:

key             binding
---             -------
DEL		backward-delete-char-untabify
C-H-x		closure
H-v		eval-current-buffer

C-c d		closure
C-c s		lars-patch-strip

C-M-i		completion-at-point
C-M-q		indent-pp-sexp
C-M-x		eval-defun

-------------

Or...  make that

---             -------

into a thin line on graphical displays?  Makes the display even more
compact.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> The following patch fixes the issue and makes things line up better:
>
> diff --git a/lisp/faces.el b/lisp/faces.el
> index 83c6b69532..84180eadc0 100644
> --- a/lisp/faces.el
> +++ b/lisp/faces.el
> @@ -2879,10 +2879,10 @@ help-key-binding
>       ;; We use negative thickness of the horizontal box border line to
>       ;; avoid enlarging the height of the echo-area display, which
>       ;; would then move the mode line a few pixels up.
> -     :box (:line-width (1 . -1) :color "grey80"))
> +     :box (:line-width (-1 . -1) :color "grey80"))
>      (((class color) (min-colors 88) (background dark))
>       :background "grey19" :foreground "LightBlue"
> -     :box (:line-width (1 . -1) :color "grey35"))
> +     :box (:line-width (-1 . -1) :color "grey35"))
>      (((class color grayscale) (background light)) :background "grey90")
>      (((class color grayscale) (background dark)) :background "grey25")
>      (t :background "grey90"))

LGTM.  I used the negative -1 for the y value to avoid the line being
taller, so it makes sense to use it for the x value to avoid characters
being wider.

Re: Tweaking the output of `C-h b'

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Is the "prefix command" thing vital to know?  And should the ??'s be
> fixed?

I don't think the "prefix command" is vital to know, as the commands
will be listed individually later.  I say skip it.

It would be good to fix "??", yes.

> key             binding
> ---             -------
> DEL		backward-delete-char-untabify
> C-H-x		closure
> H-v		eval-current-buffer
>
> C-c d		closure
> C-c s		lars-patch-strip
>
> C-M-i		completion-at-point
> C-M-q		indent-pp-sexp
> C-M-x		eval-defun

Much better.  Perhaps put "closure" as "(closure)" or "[closure]" or
something to make it clear that this is not a command named "closure"?
Or perhaps "<closure>"?

> Or...  make that
>
> ---             -------
>
> into a thin line on graphical displays?  Makes the display even more
> compact.

Is the line necessary at all?  I think one line of spacing is okay
instead.

We could experiment with either bold or a different color for "key" and
"binding" and different combination of blank space/no blank space and
line/no line.

(Can we please capitalize "Key" and "Binding" while we're at it?)

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Stefan Kangas <stefankangas@gmail.com> writes:

> Much better.  Perhaps put "closure" as "(closure)" or "[closure]" or
> something to make it clear that this is not a command named "closure"?
> Or perhaps "<closure>"?

Yes...  Hm...  I think we're outputting these things in other contexts,
too?  But right now I'm blanking of which.  [closure] looks OK to me.

> Is the line necessary at all?  I think one line of spacing is okay
> instead.

I tried with or without -- with a line, we can make the spacing shorter.
Have a look at the trunk now and see what you think.  (I'm not married
to the line, but I tried with a blank space instead, and it didn't look
as clear to me.)

> We could experiment with either bold or a different color for "key" and
> "binding" and different combination of blank space/no blank space and
> line/no line.

Yup.

> (Can we please capitalize "Key" and "Binding" while we're at it?)

Yeah, that is pretty unusual for Emacs to not capitalise those things.
I'll change it.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Po Lu]

Stefan Kangas <stefankangas@gmail.com> writes:

> Is the line necessary at all?  I think one line of spacing is okay
> instead.
>
> We could experiment with either bold or a different color for "key" and
> "binding" and different combination of blank space/no blank space and
> line/no line.
>
> (Can we please capitalize "Key" and "Binding" while we're at it?)

BTW, I'm not sure where to reply to this, but DOWN-POINTING SMALL RED
TRIANGLE is not a good character to use for the down arrows in the new
describe-bindings display.

For instance, it's usually provided by Color Emoji fonts.  Round orange
squares do not fit in nicely at all!  Is there any reason the pixmaps
used for the arrows in Custom buffers couldn't be used instead?

Secondly, it displays as a black square on Xft builds (which are still
relevant, as they're the only way to get anti-alised fonts on X without
Cairo.)

And thirdly, the glyph for this character has some odd stipple pattern
in Free Symbola, for those of us who don't want to use color fonts.

Finally, Emacs built with X11 Core Fonts is utterly incapable of
displaying that character on my system.

Re: Tweaking the output of `C-h b'

[Eli Zaretskii]

> From: Kévin Le Gouguec <kevin.legouguec@gmail.com>
> Date: Sun, 31 Oct 2021 21:42:02 +0100
> Cc: Jonas Bernoulli <jonas@bernoul.li>,
>  Stefan Monnier <monnier@iro.umontreal.ca>, emacs-devel@gnu.org
> 
> Lars Ingebrigtsen <larsi@gnus.org> writes:
> 
> > Stefan Monnier <monnier@iro.umontreal.ca> writes:
> >
> >> Shouldn't we have those standard triangles/arrows on which to click to
> >> hide/unhide?
> >
> > Yes, that'd be nice.  Perhaps with a user option to toggle between
> > classic "..." outlining and triangles?
> 
> Jonas's magit-section (available on NonGNU ELPA) more or less does
> exactly that: on the GUI, add chevrons to the left fringe (right chevron
> means "hit TAB to expand", down chevron means "hit TAB to fold back");
> on the TUI, append ellipses to expandable sections.

Don't we have similar stuff in Customize buffers?

Re: Tweaking the output of `C-h b'

[Stefan Kangas]

Po Lu <luangruo@yahoo.com> writes:

> Round orange squares do not fit in nicely at all!  Is there any reason
> the pixmaps used for the arrows in Custom buffers couldn't be used
> instead?

At a first glance, I sort of like having the colorful orange/yellow
symbol there.  It makes it clear that there is something there that can
be expanded, and it stands out as clickable, etc.  OTOH, it is a bit
noisy, so I'm not against finding a tidier solution.

The symbols used in customize are okay, but are far too inconspicuous
even there, I think.  Or it might just seem that way because the
customize interface in general is clunkier with regards to navigation --
for example you don't have "n"/"p" going to the next and previous entry.

Perhaps a discrete "+" or "-" sign could do the job, as here,

https://code.visualstudio.com/assets/docs/editor/codebasics/folding.png

Re: Tweaking the output of `C-h b'

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Have a look at the trunk now and see what you think.

What you have so far looks really good.  Thanks for bringing `C-h b'
into this century!

I'll think about it some more and I might propose some tweaks later.
For now:

- Why not show the first line of the docstring of the command in a new
  third column?

- The ":" after each section is name more distracting than helpful.
  How about removing it?

- We would be able to avoid some weird indentation if we changed it from
  16/32 to 20/40.  See how it indents around "C-M-<down-mouse-1>".  We
  might even want to consider 22/44 (or something odd like 22/40), see
  the indentation around "<bottom-right-corner>".

- Would the structure become more clear if there was one or two spaces
  of indentation for the text under each section?

Re: Tweaking the output of `C-h b'

[Po Lu]

Stefan Kangas <stefankangas@gmail.com> writes:

> At a first glance, I sort of like having the colorful orange/yellow
> symbol there.  It makes it clear that there is something there that can
> be expanded, and it stands out as clickable, etc.  OTOH, it is a bit
> noisy, so I'm not against finding a tidier solution.

The main problem I have with that is that it's not present or renders
badly on quite a few systems, as I explained below.

> The symbols used in customize are okay, but are far too inconspicuous
> even there, I think.  Or it might just seem that way because the
> customize interface in general is clunkier with regards to navigation --
> for example you don't have "n"/"p" going to the next and previous entry.
>
> Perhaps a discrete "+" or "-" sign could do the job, as here,

How about an arrow bitmap in the left fringe?  Could that work?

Re: Tweaking the output of `C-h b'

[Kévin Le Gouguec]

Eli Zaretskii <eliz@gnu.org> writes:

>> Jonas's magit-section (available on NonGNU ELPA) more or less does
>> exactly that: on the GUI, add chevrons to the left fringe (right chevron
>> means "hit TAB to expand", down chevron means "hit TAB to fold back");
>> on the TUI, append ellipses to expandable sections.
>
> Don't we have similar stuff in Customize buffers?

The UI elements (chevrons) are similar, yes; IIUC the main difference is
that magit-section uses fringe bitmaps, while Customize uses SVG
buttons.

As for features, AFAICT:

- magit-section is a reimplementation of outline-minor-mode which does
  not rely on regexps to delimit sections: it supports arbitrary nesting
  of subsections, and provides commands for visibility cycling and node
  navigation (see magit-section-mode-map).

- Meanwhile, Customize buffers "merely" provide ways to (un)fold single
  entities (user options) and jump to the previous/next buttons (which
  could be enough for the purposes of C-h b).

(I hope my comparison is accurate; if I'm being unfair to either library
I'd love to stand corrected)

Re: Tweaking the output of `C-h b'

[Kévin Le Gouguec]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> I assume that people that use Outline mode proper would know (and like)
> the TAB action.  But it's pretty obscure if you haven't been exposed to
> it before, which happens a lot with outline-minor-mode. 

That's a fair assumption; still, I could imagine some users liking the
new buttons enough to want them in e.g. NEWS or Org buffers.

If that doesn't sound too outlandish,

(1) Should outline-minor-mode-use-buttons be renamed to
    outline-use-buttons?

(2) Should it be left for opinionated modes to tweak (and opinionated
    users to adjust in mode hooks), or should it be customizable?
    Something like

    - nil: never use buttons

    - t: always use buttons (in outline-minor-mode, outline-mode, and
      derived modes)

    - a list of modes; this could be the default value, set to
      '(outline-minor-mode)?

>>   … moves point back one character, instead of folding the bindings?
>
> I'm unable to reproduce that, but point movement in the *Help* buffer
> when using outline mode is really odd.  Due to the invisible overlays?

I can no longer reproduce that specific issue, so 🤷🎉

Another minor nit though: if I move to "Major Mode Bindings:" with 'n',
then hit 'C-p', I move to the end of the previous line (i.e. after the
"Key translations:" ellipsis) instead of the beginning (i.e. the "Key
translations:" button).

It's not a big deal since 'p' works fine; just slightly disorienting.

Re: Tweaking the output of `C-h b'

[Kévin Le Gouguec]

Stefan Kangas <stefankangas@gmail.com> writes:

> The symbols used in customize are okay, but are far too inconspicuous
> even there, I think.  Or it might just seem that way because the
> customize interface in general is clunkier with regards to navigation --
> for example you don't have "n"/"p" going to the next and previous entry.

FWIW I like the SVG symbols in Customize.  The orange Noto glyphs are
visible alright, but I'm not a fan of tying UI elements to the fontset's
emoji font, which varies from system to system, and depends on user
customizations.

Whatever the consensus ends up being for C-h b, I think there is value
in having consistent UI elements for folding across Emacs.  Consistency
means that when users learn about a UI element in one situation, this
knowledge can be instantly applied wherever we made the effort to use
the same convention.

Right now users have to contend with

- ellipses in outline (and derived modes such as Org) and hideshow,
- SVG icons in Customize,
- whichever characters in outline-minor-mode-buttons their fontset can
  display, *when* outline-minor-mode-use-buttons is set,
- fringe bitmaps in magit-section.

Admittedly, none of these UIs is hard to understand individually, and
I'm sure it could be argued that each of these situations has specific
issues that justify using specific symbols; still, collectively, they
make for a rather cacophonic experience IMO.

Re: Tweaking the output of `C-h b'

[Stefan Monnier]

Po Lu [2021-11-01 13:26:16] wrote:
> Stefan Kangas <stefankangas@gmail.com> writes:
>> At a first glance, I sort of like having the colorful orange/yellow
>> symbol there.  It makes it clear that there is something there that can
>> be expanded, and it stands out as clickable, etc.  OTOH, it is a bit
>> noisy, so I'm not against finding a tidier solution.
>
> The main problem I have with that is that it's not present or renders
> badly on quite a few systems, as I explained below.

Also you can't adapt its color to particular color themes, AFAICT.


        Stefan

Re: Tweaking the output of `C-h b'

[Po Lu]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> Also you can't adapt its color to particular color themes, AFAICT.

Yes, that's also a valid point.  I would personally prefer the fringe
bitmap though, as it seems the cleanest.

Re: Tweaking the output of `C-h b'

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Sun, 31 Oct 2021 23:16:22 +0100
> Cc: emacs-devel@gnu.org
> 
> Stefan Monnier <monnier@iro.umontreal.ca> writes:
> 
> > Indeed, you can click on it with the mouse, but I don't think we offer
> > a mechanism to do that from the keyboard (not sure if clicking with the
> > mouse in a tty can do it either).
> 
> I've now implemented this and pushed it to master.

Thanks, but clicking mouse-1 on those triangles does nothing.  I see
that only mouse-2 does, which is confusing, I think, because it's
different from what happens in Customize Group buffers.  (It is also
inconvenient when the middle mouse button is the wheel.)  Also, the
mouse pointer doesn't change to a hand, like it does in Custom
buffers; I think it should.

And on TTY frame, there's no hint that mouse clicks are supported,
because there's no mouse-highlight on the mouse-sensitive text.

Re: Tweaking the output of `C-h b'

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Sun, 31 Oct 2021 18:41:06 -0700
> 
> Lars Ingebrigtsen <larsi@gnus.org> writes:
> 
> > Is the "prefix command" thing vital to know?  And should the ??'s be
> > fixed?
> 
> I don't think the "prefix command" is vital to know, as the commands
> will be listed individually later.  I say skip it.

Incompatible behavior change alert!

Re: Tweaking the output of `C-h b'

[Eli Zaretskii]

> From: Po Lu <luangruo@yahoo.com>
> Cc: Lars Ingebrigtsen <larsi@gnus.org>,  emacs-devel@gnu.org
> Date: Mon, 01 Nov 2021 13:26:16 +0800
> 
> How about an arrow bitmap in the left fringe?  Could that work?

Some people disable the fringes, so this is not a good idea for such a
basic feature, one directed at newbies and confused users at that.

Re: Tweaking the output of `C-h b'

[Eli Zaretskii]

> From: Kévin Le Gouguec <kevin.legouguec@gmail.com>
> Cc: larsi@gnus.org,  jonas@bernoul.li,  monnier@iro.umontreal.ca,
>   emacs-devel@gnu.org
> Date: Mon, 01 Nov 2021 10:47:42 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> Jonas's magit-section (available on NonGNU ELPA) more or less does
> >> exactly that: on the GUI, add chevrons to the left fringe (right chevron
> >> means "hit TAB to expand", down chevron means "hit TAB to fold back");
> >> on the TUI, append ellipses to expandable sections.
> >
> > Don't we have similar stuff in Customize buffers?
> 
> The UI elements (chevrons) are similar, yes; IIUC the main difference is
> that magit-section uses fringe bitmaps, while Customize uses SVG
> buttons.
> 
> As for features, AFAICT:
> 
> - magit-section is a reimplementation of outline-minor-mode which does
>   not rely on regexps to delimit sections: it supports arbitrary nesting
>   of subsections, and provides commands for visibility cycling and node
>   navigation (see magit-section-mode-map).
> 
> - Meanwhile, Customize buffers "merely" provide ways to (un)fold single
>   entities (user options) and jump to the previous/next buttons (which
>   could be enough for the purposes of C-h b).
> 
> (I hope my comparison is accurate; if I'm being unfair to either library
> I'd love to stand corrected)

I'm not sure we are talking about the same thing: I meant the
Customize Group buffers, where you can expand and collapse individual
options that belong to the group.

Re: Tweaking the output of `C-h b'

[Po Lu]

Eli Zaretskii <eliz@gnu.org> writes:

>> How about an arrow bitmap in the left fringe?  Could that work?

> Some people disable the fringes, so this is not a good idea for such a
> basic feature, one directed at newbies and confused users at that.

Reasonable.  How about the pixmap used for the arrows in custom, or the
the regular BLACK DOWN-POINTING TRIANGLE and BLACK RIGHT-POINTING
TRIANGLE characters? Those characters work and look reasonable on every
system I tried.

Re: Tweaking the output of `C-h b'

[Andreas Schwab]

TAB navigation is a bit odd.  When point is on the arrow or the heading
after it, TAB toggles it.  Otherwise TAB moves to the next button, but
skips over the arrows.  C-x ] doesn't move to the next arrow either, but
one position before (so that RET doesn't work).  I think TAB should
always move to the next notable point, either an arrow or a button, and
RET should probably toggle also if over a header line (unless it is over
a button, where RET currently doesn't work).

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

Re: Tweaking the output of `C-h b'

[Eli Zaretskii]

> From: Po Lu <luangruo@yahoo.com>
> Cc: larsi@gnus.org,  stefankangas@gmail.com,  emacs-devel@gnu.org
> Date: Mon, 01 Nov 2021 20:46:19 +0800
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> How about an arrow bitmap in the left fringe?  Could that work?
> 
> > Some people disable the fringes, so this is not a good idea for such a
> > basic feature, one directed at newbies and confused users at that.
> 
> Reasonable.  How about the pixmap used for the arrows in custom, or the
> the regular BLACK DOWN-POINTING TRIANGLE and BLACK RIGHT-POINTING
> TRIANGLE characters? Those characters work and look reasonable on every
> system I tried.

I think using the same methods as in Customize Group buffers would be
a good idea, since there we already have the solutions both for GUI
and for TTY frames.

Re: Tweaking the output of `C-h b'

[T.V Raman]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=gb18030, Size: 1409 bytes --]

Lars Ingebrigtsen <larsi@gnus.org> writes:


Could we also introduce some kind of section delimiter that is
searchable?
A line with a special face would do the trick to for an emacspeak user
to jump across sections of keybindings.
> Stefan Kangas <stefankangas@gmail.com> writes:
>
>> Much better.  Perhaps put "closure" as "(closure)" or "[closure]" or
>> something to make it clear that this is not a command named "closure"?
>> Or perhaps "<closure>"?
>
> Yes...  Hm...  I think we're outputting these things in other contexts,
> too?  But right now I'm blanking of which.  [closure] looks OK to me.
>
>> Is the line necessary at all?  I think one line of spacing is okay
>> instead.
>
> I tried with or without -- with a line, we can make the spacing shorter.
> Have a look at the trunk now and see what you think.  (I'm not married
> to the line, but I tried with a blank space instead, and it didn't look
> as clear to me.)
>
>> We could experiment with either bold or a different color for "key" and
>> "binding" and different combination of blank space/no blank space and
>> line/no line.
>
> Yup.
>
>> (Can we please capitalize "Key" and "Binding" while we're at it?)
>
> Yeah, that is pretty unusual for Emacs to not capitalise those things.
> I'll change it.

-- 

Thanks,

--Raman(I Search, I Find, I Misplace, I Research)
7©4 Id: kg:/m/0285kf1  •0Ü8

Re: Tweaking the output of `C-h b'

[Po Lu]

Eli Zaretskii <eliz@gnu.org> writes:

> I think using the same methods as in Customize Group buffers would be
> a good idea, since there we already have the solutions both for GUI
> and for TTY frames.

Would it be OK to use the `custom-visiblity' widget as-is, or is that
something to be avoided?  Thanks.

Re: Tweaking the output of `C-h b'

[Po Lu]

"T.V Raman" <raman@google.com> writes:

> Could we also introduce some kind of section delimiter that is
> searchable?  A line with a special face would do the trick to for an
> emacspeak user to jump across sections of keybindings.

Isn't the line feed character used for such purposes?

(And doesn't describe-bindings already insert line feed characters where
appropriate?)

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

[-- Attachment #1: Type: text/plain, Size: 165 bytes --]

Stefan Kangas <stefankangas@gmail.com> writes:

> The symbols used in customize are okay, but are far too inconspicuous
> even there, I think.

They're...  subtle:


[-- Attachment #2: Type: image/png, Size: 6735 bytes --]

[-- Attachment #3: Type: text/plain, Size: 422 bytes --]


I think we could do with something that's easier to see.  :-)

> Perhaps a discrete "+" or "-" sign could do the job, as here,
>
> https://code.visualstudio.com/assets/docs/editor/codebasics/folding.png

Oh, yeah, +/- seems like a better thing than these arrows, which don't
really convey much semantically, I think.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Po Lu <luangruo@yahoo.com> writes:

> BTW, I'm not sure where to reply to this, but DOWN-POINTING SMALL RED
> TRIANGLE is not a good character to use for the down arrows in the new
> describe-bindings display.

I guess that means that you don't have the emoji font installed?

Yeah, for these emoji grapheme clusters, I should check the availability
of the glyph with something like

(font-get-glyphs (car (internal-char-font nil ?😀))
                 0 (length "🔽") "🔽")

I think...

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Kévin Le Gouguec <kevin.legouguec@gmail.com> writes:

> Whatever the consensus ends up being for C-h b, I think there is value
> in having consistent UI elements for folding across Emacs.

Definitely.  I think writing a separate little library for this would be
nice, so that people can customise this in one place.  Some people can
use SVGs, some can't, and some want to have it colourful and some don't.

And then outline/customize/sections can use that library to handle the
open/fold thingies.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Stefan Kangas <stefankangas@gmail.com> writes:

> - Why not show the first line of the docstring of the command in a new
>   third column?

Hm...  the display is already pretty busy...

> - The ":" after each section is name more distracting than helpful.
>   How about removing it?

Yes, the ":" seems superfluous, but we'd have to come up with something
else for outline to work off of then.  Uhm...

> - We would be able to avoid some weird indentation if we changed it from
>   16/32 to 20/40.  See how it indents around "C-M-<down-mouse-1>".  We
>   might even want to consider 22/44 (or something odd like 22/40), see
>   the indentation around "<bottom-right-corner>".

I was wondering whether we should just ditch the whole 16/32 thing and
compute the widths (per section), but not totally slavishly.

That is, compute the max width, but if there's one ridiculously wide key
entry (like "<remap> <switch-to-buffer-other-frame>"), then don't take
that into account (for the rest of the entries).  I think that would
give us more readable lists in general, but some experimentation is
needed. 

> - Would the structure become more clear if there was one or two spaces
>   of indentation for the text under each section?

Which text do you mean?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Kévin Le Gouguec <kevin.legouguec@gmail.com> writes:

> That's a fair assumption; still, I could imagine some users liking the
> new buttons enough to want them in e.g. NEWS or Org buffers.
>
> If that doesn't sound too outlandish,
>
> (1) Should outline-minor-mode-use-buttons be renamed to
>     outline-use-buttons?
>
> (2) Should it be left for opinionated modes to tweak (and opinionated
>     users to adjust in mode hooks), or should it be customizable?
>     Something like
>
>     - nil: never use buttons
>
>     - t: always use buttons (in outline-minor-mode, outline-mode, and
>       derived modes)
>
>     - a list of modes; this could be the default value, set to
>       '(outline-minor-mode)?

Currently, the *Help* buffer sets the variable buffer-locally.  So
perhaps just renaming it to outline-use-buttons would make sense and
people could decide to use them in outline major mode, too.  But I
haven't tested that at all.

> Another minor nit though: if I move to "Major Mode Bindings:" with 'n',
> then hit 'C-p', I move to the end of the previous line (i.e. after the
> "Key translations:" ellipsis) instead of the beginning (i.e. the "Key
> translations:" button).
>
> It's not a big deal since 'p' works fine; just slightly disorienting.

Yes, it's not good.  But I think that's a general problem with invisible
text (which outline uses)?  I feel like I've stumbled onto that issue
previosly.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Kévin Le Gouguec]

[-- Attachment #1: Type: text/plain, Size: 1905 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

>> > Don't we have similar stuff in Customize buffers?
>> 
>> The UI elements (chevrons) are similar, yes; IIUC the main difference is
>> that magit-section uses fringe bitmaps, while Customize uses SVG
>> buttons.
>> 
>> As for features, AFAICT:
>> 
>> - magit-section is a reimplementation of outline-minor-mode which does
>>   not rely on regexps to delimit sections: it supports arbitrary nesting
>>   of subsections, and provides commands for visibility cycling and node
>>   navigation (see magit-section-mode-map).
>> 
>> - Meanwhile, Customize buffers "merely" provide ways to (un)fold single
>>   entities (user options) and jump to the previous/next buttons (which
>>   could be enough for the purposes of C-h b).
>> 
>> (I hope my comparison is accurate; if I'm being unfair to either library
>> I'd love to stand corrected)
>
> I'm not sure we are talking about the same thing: I meant the
> Customize Group buffers, where you can expand and collapse individual
> options that belong to the group.

Mmm, I think we are?  See attached screenshot, with UI elements circled
in red:

- on the left, a Customize group buffer, with "Outline 1" expanded, and
  other options collapsed;

- on the right, a magit-revision buffer, with most sections expanded,
  except for lisp/help.el's subsections (diff hunks), which are
  collapsed.

  (Note that nothing indicates visually that the collapsed hunks are
  subsections of the "modified lisp/help.el" section, unfortunately)

Visually they look similar (full arrow heads in column 0 vs fringe
chevrons); functionally, Customize options can be expanded or collapsed
with RET; Magit's sections can be manipulated like outline.el's sections
(toggle node visibility with TAB, toggle children visibility C-TAB, go
up with ^, go forward node with n, skip over sibling nodes with M-n).

Apologies if I've misunderstood.


[-- Attachment #2: customize-vs-magit-section.png --]
[-- Type: image/png, Size: 253320 bytes --]

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> Thanks, but clicking mouse-1 on those triangles does nothing.  I see
> that only mouse-2 does, which is confusing, I think, because it's
> different from what happens in Customize Group buffers.

Yeah, I see the same thing.  But I did put 

                     [follow-link] 'mouse-face
                     [mouse-2] #'outline-hide-subtree)))))

in the keymap -- isn't that supposed to handle this?  Or doesn't that
work on an overlay keymap?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

"T.V Raman" <raman@google.com> writes:

> Could we also introduce some kind of section delimiter that is
> searchable?
> A line with a special face would do the trick to for an emacspeak user
> to jump across sections of keybindings.

The ^L character is used as the delimited (but it's invisible now).  And
the `n'/`p' commands takes you between sections.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Eli Zaretskii]

> From: Po Lu <luangruo@yahoo.com>
> Cc: larsi@gnus.org,  stefankangas@gmail.com,  emacs-devel@gnu.org
> Date: Mon, 01 Nov 2021 21:43:19 +0800
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > I think using the same methods as in Customize Group buffers would be
> > a good idea, since there we already have the solutions both for GUI
> > and for TTY frames.
> 
> Would it be OK to use the `custom-visiblity' widget as-is

Yes, I think so.

Re: Tweaking the output of `C-h b'

[Eli Zaretskii]

> From: Kévin Le Gouguec <kevin.legouguec@gmail.com>
> Cc: larsi@gnus.org,  jonas@bernoul.li,  monnier@iro.umontreal.ca,
>   emacs-devel@gnu.org
> Date: Mon, 01 Nov 2021 15:26:30 +0100
> 
> >> The UI elements (chevrons) are similar, yes; IIUC the main difference is
> >> that magit-section uses fringe bitmaps, while Customize uses SVG
> >> buttons.
> >> 
> >> As for features, AFAICT:
> >> 
> >> - magit-section is a reimplementation of outline-minor-mode which does
> >>   not rely on regexps to delimit sections: it supports arbitrary nesting
> >>   of subsections, and provides commands for visibility cycling and node
> >>   navigation (see magit-section-mode-map).
> >> 
> >> - Meanwhile, Customize buffers "merely" provide ways to (un)fold single
> >>   entities (user options) and jump to the previous/next buttons (which
> >>   could be enough for the purposes of C-h b).
> >> 
> >> (I hope my comparison is accurate; if I'm being unfair to either library
> >> I'd love to stand corrected)
> >
> > I'm not sure we are talking about the same thing: I meant the
> > Customize Group buffers, where you can expand and collapse individual
> > options that belong to the group.
> 
> Mmm, I think we are?  See attached screenshot, with UI elements circled
> in red:
> 
> - on the left, a Customize group buffer, with "Outline 1" expanded, and
>   other options collapsed;
> 
> - on the right, a magit-revision buffer, with most sections expanded,
>   except for lisp/help.el's subsections (diff hunks), which are
>   collapsed.
> 
>   (Note that nothing indicates visually that the collapsed hunks are
>   subsections of the "modified lisp/help.el" section, unfortunately)

Then I think what we have in Custom is better, and it has the problems
I mentioned in my other mail taken care of.  Why should we invent yet
another set of "widgets" for Help buffers?

Re: Tweaking the output of `C-h b'

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: monnier@iro.umontreal.ca,  emacs-devel@gnu.org
> Date: Mon, 01 Nov 2021 15:27:34 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Thanks, but clicking mouse-1 on those triangles does nothing.  I see
> > that only mouse-2 does, which is confusing, I think, because it's
> > different from what happens in Customize Group buffers.
> 
> Yeah, I see the same thing.  But I did put 
> 
>                      [follow-link] 'mouse-face
>                      [mouse-2] #'outline-hide-subtree)))))
> 
> in the keymap -- isn't that supposed to handle this?  Or doesn't that
> work on an overlay keymap?

Sorry, I don't know.  Maybe someone else does.

Customize SVG icons (was: Tweaking the output of `C-h b')

[Kévin Le Gouguec]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Stefan Kangas <stefankangas@gmail.com> writes:
>
>> The symbols used in customize are okay, but are far too inconspicuous
>> even there, I think.
>
> They're...  subtle:

Yup, that's because "fill:#2e3436" is hardcoded in the SVG files.
Removing that bit makes Emacs use the foreground color for the default
face.

I don't know if we want to do that (it's sort of a nuclear solution),
and/or introduce a face to let themes control this color; it's true that
as things stand, these buttons are not very visible for dark themes.

(I still find them more appropriate for UI elements than glyphs that
change depending on fontsets, FWIW)

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

[-- Attachment #1: Type: text/plain, Size: 358 bytes --]

Stefan Kangas <stefankangas@gmail.com> writes:

> I don't think the "prefix command" is vital to know, as the commands
> will be listed individually later.  I say skip it.
>
> It would be good to fix "??", yes.

I've now done both of these, and it looks like an improvement to me --
the lists are a lot more "unified" now without the "Prefix Command"
bits.


[-- Attachment #2: Type: image/png, Size: 47047 bytes --]

[-- Attachment #3: Type: text/plain, Size: 18 bytes --]


vs in emacs-28:


[-- Attachment #4: Type: image/png, Size: 53739 bytes --]

[-- Attachment #5: Type: text/plain, Size: 105 bytes --]



-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Customize SVG icons (was: Tweaking the output of `C-h b')

[Yuri Khan]

On Mon, 1 Nov 2021 at 21:49, Kévin Le Gouguec <kevin.legouguec@gmail.com> wrote:

> Yup, that's because "fill:#2e3436" is hardcoded in the SVG files.
> Removing that bit makes Emacs use the foreground color for the default
> face.
>
> I don't know if we want to do that (it's sort of a nuclear solution),
> and/or introduce a face to let themes control this color; it's true that
> as things stand, these buttons are not very visible for dark themes.

The standard solution for this kind of issue when you don’t want to go
monochrome is to give the shapes a high contrast stroke color or
shadow. A 1.5px white line will do wonders to the visibility of that
dark gray on dark backgrounds.

Although in my opinion monochrome is good for this kind of widgets.
They do not need to draw attention, being only a decluttering device
and expanded by default.

Re: Tweaking the output of `C-h b'

[Matthias Meulien]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Po Lu <luangruo@yahoo.com>
>> Cc: Lars Ingebrigtsen <larsi@gnus.org>,  emacs-devel@gnu.org
>> Date: Mon, 01 Nov 2021 13:26:16 +0800
>> 
>> How about an arrow bitmap in the left fringe?  Could that work?
>
> Some people disable the fringes, so this is not a good idea for such a
> basic feature, one directed at newbies and confused users at that.

But, using the fringe is the only solution that preserves columns
alignment! Please give it a second thought.

I guess unexpected indentation will confuse newbies more than the use of
the fringe. Imagine a buffer with Python source code and outline minor
mode enabled...

Also is a newby expected to disable the fringe??
-- 
Matthias

Re: Tweaking the output of `C-h b'

[Eli Zaretskii]

> From: Matthias Meulien <orontee@gmail.com>
> Cc: Po Lu <luangruo@yahoo.com>,  larsi@gnus.org,  stefankangas@gmail.com,
>   emacs-devel@gnu.org
> Date: Mon, 01 Nov 2021 18:12:56 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Po Lu <luangruo@yahoo.com>
> >> Cc: Lars Ingebrigtsen <larsi@gnus.org>,  emacs-devel@gnu.org
> >> Date: Mon, 01 Nov 2021 13:26:16 +0800
> >> 
> >> How about an arrow bitmap in the left fringe?  Could that work?
> >
> > Some people disable the fringes, so this is not a good idea for such a
> > basic feature, one directed at newbies and confused users at that.
> 
> But, using the fringe is the only solution that preserves columns
> alignment! Please give it a second thought.

What column alignment do you have in mind, and why would it not be
preserved without using the fringes?  Do you see such a problem in the
Customize buffers?

> Also is a newby expected to disable the fringe??

Yes, because they tend to copycat init files by other users.

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> What column alignment do you have in mind, and why would it not be
> preserved without using the fringes?  Do you see such a problem in the
> Customize buffers?

I'm wondering how the fringe markers allow you to toggle the folding.
Do they set some overlay keymap in addition to using the fringe?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: Matthias Meulien <orontee@gmail.com>,  luangruo@yahoo.com,
>   stefankangas@gmail.com,  emacs-devel@gnu.org
> Date: Mon, 01 Nov 2021 18:20:40 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > What column alignment do you have in mind, and why would it not be
> > preserved without using the fringes?  Do you see such a problem in the
> > Customize buffers?
> 
> I'm wondering how the fringe markers allow you to toggle the folding.
> Do they set some overlay keymap in addition to using the fringe?

When you click on the fringe, you get an event [left-fringe mouse-1]
and the coordinates of the click.

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> I'm wondering how the fringe markers allow you to toggle the folding.
>> Do they set some overlay keymap in addition to using the fringe?
>
> When you click on the fringe, you get an event [left-fringe mouse-1]
> and the coordinates of the click.

So you have to use the mouse?  That's a pretty severe limitation and
would make that (as a general design) pretty useless.

But we could have it as an option, I guess.

So if we have a fold-text.el library, it could offer

* fringes
* buttons
  * svg
  * emojis
  * other random text
* "..."

or a combination of these, and then have some kind of fall-back system
(i.e., if you want fringes but they aren't switched on, then fall-back
to button), or something (that the user can specify).

(And similarly, fall back from svg to the other things when that's no
available.)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[T.V Raman]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=gb18030, Size: 607 bytes --]

Lars Ingebrigtsen <larsi@gnus.org> writes:


Awesome, hadn't realized that 'n' and 'p' moved through sections
already.
> "T.V Raman" <raman@google.com> writes:
>
>> Could we also introduce some kind of section delimiter that is
>> searchable?
>> A line with a special face would do the trick to for an emacspeak user
>> to jump across sections of keybindings.
>
> The ^L character is used as the delimited (but it's invisible now).  And
> the `n'/`p' commands takes you between sections.

-- 

Thanks,

--Raman(I Search, I Find, I Misplace, I Research)
7©4 Id: kg:/m/0285kf1  •0Ü8

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

"T.V Raman" <raman@google.com> writes:

> Awesome, hadn't realized that 'n' and 'p' moved through sections
> already.

I added that yesterday.  :-)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Customize SVG icons

[Kévin Le Gouguec]

Kévin Le Gouguec <kevin.legouguec@gmail.com> writes:

> Lars Ingebrigtsen <larsi@gnus.org> writes:
>
>> Stefan Kangas <stefankangas@gmail.com> writes:
>>
>>> The symbols used in customize are okay, but are far too inconspicuous
>>> even there, I think.
>>
>> They're...  subtle:
>
> Yup, that's because "fill:#2e3436" is hardcoded in the SVG files.
> Removing that bit makes Emacs use the foreground color for the default
> face.

Filed bug#51556 for further discussion of this specific itch.

Re: Tweaking the output of `C-h b'

[Stefan Monnier]

> I think using the same methods as in Customize Group buffers would be
> a good idea, since there we already have the solutions both for GUI
> and for TTY frames.

Indeed, I think we should try as much as possible to share the code
between the two, so that if/when we improve one, it also improves
the other.


        Stefan

Re: Tweaking the output of `C-h b'

[Stefan Monnier]

> So if we have a fold-text.el library, it could offer
>
> * fringes
> * buttons
>   * svg
>   * emojis
>   * other random text
> * "..."

Why does the "..." have to be an alternative?
Please, can I have "(fringe OR buttons) AND ellipsis"?

Also, as pointed out, for outline-(minor-)mode some
`outline-regexp`s will work better with fringes, so even if, as a user
I'd generally prefer the buttons, it would be nice for Emacs to know
that in ELisp mode outline-minor-mode should not use buttons because

    ▶ (defun my-foo ( arg1
                    arg2
                    arg3)

is not right.  So major modes should be able to tell `outline-minor-mode`
whether buttons should be avoided.


        Stefan

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> So if we have a fold-text.el library, it could offer
>>
>> * fringes
>> * buttons
>>   * svg
>>   * emojis
>>   * other random text
>> * "..."
>
> Why does the "..." have to be an alternative?
> Please, can I have "(fringe OR buttons) AND ellipsis"?

I didn't mean as an exclusive list -- I think all of the things can be
mixed.  Why not have fringes, buttons and "..." at the same time if you
want?

>     ▶ (defun my-foo ( arg1
>                     arg2
>                     arg3)
>
> is not right.  So major modes should be able to tell `outline-minor-mode`
> whether buttons should be avoided.

Right.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Matthias Meulien]

[-- Attachment #1: Type: text/plain, Size: 787 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

> What column alignment do you have in mind, and why would it not be
> preserved without using the fringes?

I was thinking of a buffer containing source code with
outline-minor-mode enabled. The column alignment would not be preserved
since the emoji, SVG arrow, etc., whatever is inserted at the beginning
of a line but in the fringe, occupies horizontal space within the line.

Stephan Monnier gave an example.

> Do you see such a problem in the Customize buffers?

Customize buffers weren't in my scope.

I don't know if it's related to the arrow but I find their identation
strange: The settings aren't indented but their description is indented
by three spaces and doesn't align with the first non-white space
character following the arrow.


[-- Attachment #2: Type: image/png, Size: 26057 bytes --]

[-- Attachment #3: Type: text/plain, Size: 13 bytes --]

-- 
Matthias

Re: Tweaking the output of `C-h b'

[Matthias Meulien]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> So you have to use the mouse?  That's a pretty severe limitation and
> would make that (as a general design) pretty useless.

No, one need not use the mouse: outline-minor-mode has a panoply of key
bindings to toggle body visibility.

-- 
Matthias

Re: Tweaking the output of `C-h b'

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> > Whatever the consensus ends up being for C-h b, I think there is value
> > in having consistent UI elements for folding across Emacs.
>
> Definitely.  I think writing a separate little library for this would be
> nice, so that people can customise this in one place.  Some people can
> use SVGs, some can't, and some want to have it colourful and some don't.

I'm working on such a library since some time back.  Watch this space.

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Stefan Kangas <stefankangas@gmail.com> writes:

> I'm working on such a library since some time back.  Watch this space.

Great!  🤓

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:
>
> Stefan Kangas <stefankangas@gmail.com> writes:
>
> > I'm working on such a library since some time back.  Watch this space.
>
> Great!  🤓

Let me go into some more detail:

The library (icons.el) I am working on allows inserting external icons
into a buffer, used in the mode-line, etc.  The branch comes with a
curated set of externally developed and free icon sets as svg's, and
functions for updating said set from upstream.

I have a fully working prototype, and I'm currently experimenting with
how exactly the user should be able to customize icons.  Give it a
month or three and I'll post a first draft for review.  Or, if you're
really, really curious, I could what I have so far up on a branch.
But that'd be highly tentative.

PS. Too bad icon.el is not named icon-mode.el.  Hmm.

Re: Tweaking the output of `C-h b'

[Po Lu]

Eli Zaretskii <eliz@gnu.org> writes:

> Yes, I think so.

I found out that would require loading cus-edit from outline.el, which
I'm sure many people wouldn't appreciate.

But it turns out there's already a set of non-problematic characters in
`outline-minor-mode-buttons', so how about removing the first entry from
that that variable, leaving only the usable characters?

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Po Lu <luangruo@yahoo.com> writes:

> But it turns out there's already a set of non-problematic characters in
> `outline-minor-mode-buttons', so how about removing the first entry from
> that that variable, leaving only the usable characters?

They're all usable if you have the correct fonts, but the check for
whether you do so is incorrect.  Since Stefan K is working on a more
complete solution, I haven't fixed it.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Po Lu]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> They're all usable if you have the correct fonts, but the check for
> whether you do so is incorrect.  Since Stefan K is working on a more
> complete solution, I haven't fixed it.

But is it ever desirable to use these emoji-like characters?  An orange
square really doesn't make sense as such an indicator.

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Po Lu <luangruo@yahoo.com> writes:

>> They're all usable if you have the correct fonts, but the check for
>> whether you do so is incorrect.  Since Stefan K is working on a more
>> complete solution, I haven't fixed it.

(I've now tweaked the detection.)

> But is it ever desirable to use these emoji-like characters?  An orange
> square really doesn't make sense as such an indicator.

Why do you think so?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Stefan Kangas <stefankangas@gmail.com> writes:

> The library (icons.el) I am working on allows inserting external icons
> into a buffer, used in the mode-line, etc.  The branch comes with a
> curated set of externally developed and free icon sets as svg's, and
> functions for updating said set from upstream.

Does it fall back on using chars if Emacs doesn't have svg support and
stuff? 

> I have a fully working prototype, and I'm currently experimenting with
> how exactly the user should be able to customize icons.  Give it a
> month or three and I'll post a first draft for review.  Or, if you're
> really, really curious, I could what I have so far up on a branch.
> But that'd be highly tentative.

There's no hurry -- please take however much time you need.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Po Lu]

Lars Ingebrigtsen <larsi@gnus.org> writes:

>> But is it ever desirable to use these emoji-like characters?  An orange
>> square really doesn't make sense as such an indicator.

> Why do you think so?

It doesn't fit in well with color themes, and tends to remind people of
a "play/pause" button instead of an "expand" button.

And looks visually inconsistent with everything else currently done in
Emacs (say, Customize buffers), and with popular packages (for example,
magit).

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

[-- Attachment #1: Type: text/plain, Size: 309 bytes --]

Po Lu <luangruo@yahoo.com> writes:

> It doesn't fit in well with color themes, and tends to remind people of
> a "play/pause" button instead of an "expand" button.

I know that some people absolutely hate all colour, but in this context,
I don't think there's much danger that they're thinking that hitting


[-- Attachment #2: Type: image/png, Size: 4798 bytes --]

[-- Attachment #3: Type: text/plain, Size: 620 bytes --]


is going to start playing music.

> And looks visually inconsistent with everything else currently done in
> Emacs (say, Customize buffers), and with popular packages (for example,
> magit).

Well, Customize and *Help* buffers are eventually going to use the same
insertion buttons, but that's going to take a while.  And one of the
choices for both is going to be these characters, most likely, so it'll
be consistent anyway.

Magit already isn't consistent with anything, so it's not relevant for
the discussion.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Po Lu]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Well, Customize and *Help* buffers are eventually going to use the same
> insertion buttons, but that's going to take a while.  And one of the
> choices for both is going to be these characters, most likely, so it'll
> be consistent anyway.

But the customize buttons already exist, while these characters are new.
Even if there's nothing wrong with them, it would still fit everyone's
existing expectations if outline buttons used what is currently being
used by custom.

> Magit already isn't consistent with anything, so it's not relevant for
> the discussion.

Fair enough.

Re: Tweaking the output of `C-h b'

[Stefan Monnier]

> I know that some people absolutely hate all colour, but in this context,
> I don't think there's much danger that they're thinking that hitting

For me it's a non-starter if it can't be adjusted by color themes.


        Stefan

Re: Tweaking the output of `C-h b'

[Eli Zaretskii]

> From: Matthias Meulien <orontee@gmail.com>
> Cc: luangruo@yahoo.com,  larsi@gnus.org,  stefankangas@gmail.com,
>   emacs-devel@gnu.org
> Date: Mon, 01 Nov 2021 22:55:23 +0100
> 
> > What column alignment do you have in mind, and why would it not be
> > preserved without using the fringes?
> 
> I was thinking of a buffer containing source code with
> outline-minor-mode enabled. The column alignment would not be preserved
> since the emoji, SVG arrow, etc., whatever is inserted at the beginning
> of a line but in the fringe, occupies horizontal space within the line.
> 
> Stephan Monnier gave an example.

This discussion is about "C-h b" buffers and Customize buffers, and I
think you are talking about a different use case.

> > Do you see such a problem in the Customize buffers?
> 
> Customize buffers weren't in my scope.
> 
> I don't know if it's related to the arrow but I find their identation
> strange: The settings aren't indented but their description is indented
> by three spaces and doesn't align with the first non-white space
> character following the arrow.

I don't see a problem here: the line with the arrow is a heading, so
it doesn't have to align to what's below it.

Re: Tweaking the output of `C-h b'

[Stefan Kangas]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> I know that some people absolutely hate all colour, but in this context,
>> I don't think there's much danger that they're thinking that hitting
>
> For me it's a non-starter if it can't be adjusted by color themes.

I agree.  However, rather than spending time on styling this now,
perhaps we can live with this on master until I can get finish up my new
icons branch?  I believe it should solve this issue in a clean and
customizable way.

Or, we could use some other interim glyph, I don't exactly have a strong
opinion about it.  :-)

Re: Tweaking the output of `C-h b'

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Stefan Kangas <stefankangas@gmail.com> writes:
>
>> The library (icons.el) I am working on allows inserting external icons
>> into a buffer, used in the mode-line, etc.  The branch comes with a
>> curated set of externally developed and free icon sets as svg's, and
>> functions for updating said set from upstream.
>
> Does it fall back on using chars if Emacs doesn't have svg support and
> stuff?

That's the idea, yes.  Basically, application code will say
e.g. (icons-insert "fold-expanded"), and what actually happens depends
on the GUI/terminal capabilities (svg, xbm, utf-8 glyph, ascii) and user
customizations; for example, maybe the default is to use icons from the
icon set "foo", but a user prefers to use the icon set "bar" instead.
Users will even be able turn off all icons completely, if they prefer.

> There's no hurry -- please take however much time you need.

Thanks.

Re: Tweaking the output of `C-h b'

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> I don't know if it's related to the arrow but I find their identation
>> strange: The settings aren't indented but their description is indented
>> by three spaces and doesn't align with the first non-white space
>> character following the arrow.
>
> I don't see a problem here: the line with the arrow is a heading, so
> it doesn't have to align to what's below it.

Agreed.

However, maybe Matthias is thinking about buffers where
`outline-minor-mode-buttons' is nil?  In that case, I think we could
consider extending `outline-minor-mode' to put bitmaps in the fringe
instead.

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

>> For me it's a non-starter if it can't be adjusted by color themes.

Not all GUI elements in Emacs can be adjusted by colour themes (that is,
face-based themes), and it's unrealistic to think that it can.  That
would limit us to monochromatic elements (or rather, just one foreground
and background colour).

> I agree.  However, rather than spending time on styling this now,
> perhaps we can live with this on master until I can get finish up my new
> icons branch?  I believe it should solve this issue in a clean and
> customizable way.

Yes, there's no hurry.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Stefan Kangas <stefankangas@gmail.com> writes:

> Basically, application code will say
> e.g. (icons-insert "fold-expanded"), and what actually happens depends
> on the GUI/terminal capabilities (svg, xbm, utf-8 glyph, ascii) and user
> customizations; for example, maybe the default is to use icons from the
> icon set "foo", but a user prefers to use the icon set "bar" instead.
> Users will even be able turn off all icons completely, if they prefer.

Sounds excellent.  😁

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Po Lu <luangruo@yahoo.com> writes:

> But the customize buttons already exist, while these characters are new.

They exist, but I don't think they're good enough.

In any case, this will resolve itself once we get the library previously
described.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Lars Ingebrigtsen]

Andreas Schwab <schwab@linux-m68k.org> writes:

> TAB navigation is a bit odd.  When point is on the arrow or the heading
> after it, TAB toggles it.

Well, that's how outline-minor-mode works...  But perhaps there should
be a separation between how outline-minor-mode works in special-mode and
editing buffers -- TAB might make sense in editing buffers, but probably
not in special-mode buffers.  On the other hand, I'm guessing changing
this would annoy people used to it.

> Otherwise TAB moves to the next button, but
> skips over the arrows.  C-x ] doesn't move to the next arrow either, but
> one position before (so that RET doesn't work).

'n' does work more logically, though.

> I think TAB should always move to the next notable point, either an
> arrow or a button,

Yes.  It apparently not trivial -- adding button/category properties to
those buttons (which will make TAB try to take you to them) does not
work, probably because of the invisible text.

> and RET should probably toggle also if over a header line (unless it
> is over a button, where RET currently doesn't work).

Oh, RET on a button in an outline header doesn't work...  hm...  There's
something odd going on with the key bindings in *Help* buffers.

`C-h k RET' says that it's `newline' instead of `push-button' from
`button-map' -- except on the buttons (which do not have a `keymap' text
property).  How does that all hook up?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Tweaking the output of `C-h b'

[Juri Linkov]

>>> For me it's a non-starter if it can't be adjusted by color themes.
>
> Not all GUI elements in Emacs can be adjusted by colour themes (that is,
> face-based themes), and it's unrealistic to think that it can.  That
> would limit us to monochromatic elements (or rather, just one foreground
> and background colour).

Can the background/foreground color of an SVG icon be affected
by surrounding font-lock faces?  I recall that transparent parts
use the background color.  Then transparent bodies of arrows
in an SVG icon could inherit the face background.

Re: Tweaking the output of `C-h b'

[Juri Linkov]

>   (FWIW I tried to enable this in NEWS, but the buttons did not seem
>   very functional there)

These Local variables give a good result in etc/NEWS by removing
page separators (line feed) from the default value of outline-regexp:

Local variables:
coding: utf-8
outline-regexp: "[*]+"
outline-minor-mode-use-buttons: t
mode: outline-minor
paragraph-separate: "[ 	\f]*$"
end:

Re: Tweaking the output of `C-h b'

[Stefan Kangas]

Juri Linkov <juri@linkov.net> writes:

> Can the background/foreground color of an SVG icon be affected
> by surrounding font-lock faces?

Yes.  If an SVG image doesn't explicitly specify a foreground and/or
background color, it will use the foreground and/or background color of
the face where it is inserted.