How to add syntax-highlighting to a Help buffer?

How to add syntax-highlighting to a Help buffer?

[Raffaele Ricciardi]

I would like to add some syntax-highlighting to Help buffers. I have
tried to do that for example with the Help buffer displayed by C-h f
read-string RET, by following the usual way:

(font-lock-add-keywords
  nil
  `(("\\(arbitrary regexp\\)" 1 'font-lock-function-name-face)))

But the above expression breaks the existing highlighting (the
highlighting of the function arguments disappears).  Also, now C-- C-x
C-q M-: (insert (propertize "test" 'face 'font-lock-warning-face)) RET
does not insert colorized text as it would do with a fresh Help buffer.

I am using GNU Emacs 24.5.

Thank you.

Re: How to add syntax-highlighting to a Help buffer?

[Vaidheeswaran C]

Put it in hi-lock-mode.  See if it helps.

C-h K C-x w h




On Friday 03 July 2015 01:29 PM, Raffaele Ricciardi wrote:
> I would like to add some syntax-highlighting to Help buffers. I have
> tried to do that for example with the Help buffer displayed by C-h f
> read-string RET, by following the usual way:
> 
> (font-lock-add-keywords
>  nil
>  `(("\\(arbitrary regexp\\)" 1 'font-lock-function-name-face)))
> 
> But the above expression breaks the existing highlighting (the
> highlighting of the function arguments disappears).  Also, now C-- C-x
> C-q M-: (insert (propertize "test" 'face 'font-lock-warning-face)) RET
> does not insert colorized text as it would do with a fresh Help buffer.
> 
> I am using GNU Emacs 24.5.
> 
> Thank you.
> 

Re: How to add syntax-highlighting to a Help buffer?

[Emanuel Berg]

Raffaele Ricciardi <rfflrccrd@gmail.com> writes:

> I would like to add some syntax-highlighting to Help
> buffers. I have tried to do that for example with
> the Help buffer displayed by C-h f read-string RET,
> by following the usual way:

You mean, you want *more* than what's already there
for buttons etc.?

Check out this file - it isn't help, but the one of
the buffer menus, but you might find the mechanics
interesting for your purposes:

    http://user.it.uu.se/~embe8573/conf/emacs-init/buffer-menu.el

Here are the actual regexps to "help" you to a quick
start:

(defvar buffer-menu-buffer-font-lock-keywords
  '(
    ("\\(KILL\\|my-kill\\) "              .  font-lock-builtin-face)
    ("\\*\\(Errors\\|Backtrace\\)\\*"     .  font-lock-warning-face)
    ("\\*\\(Group\\|Server\\)\\*"         .  font-lock-comment-face)
    ("\\*\\(Help\\|Completions\\|Messages\\|info\\|Apropos\\)\\*"
                                          .  font-lock-constant-face)
    ("\\*\\(ielm\\|Article\\)\\*"         . 'font-lock-regexp-grouping-backslash)
    (".* \\(.*\\.txt\\) "                 (1 font-lock-negation-char-face))
    ("[[:space:]]+\\([[:digit:]]+\\) "    (1 font-lock-comment-delimiter-face))
    ("<.*\\(>\\|\\.\\.\\.\\)"             . 'font-lock-regexp-grouping-construct)
    ("Makefile"                           .  font-lock-comment-face)
    ("\\(\\*Man\\) \\(.*\\)\\(\\*\\)"
     (1  font-lock-type-face)
     (2 'font-lock-regexp-grouping-construct)
     (3  font-lock-type-face) )
    (".* \\(.*\\.\\(el\\|cc?\\|cpp\\)\\) "(1 font-lock-string-face))
    ("\\*w3m\\*"                          .  font-lock-function-name-face)
    (".* \\(.*\\.html?\\) "               (1 font-lock-doc-face))
    (".* \\(.*\\.\\(hh?\\|tex\\)\\) "     (1 font-lock-variable-name-face))
    (".* \\(\\.[[:alnum:]_.-]*\\) "       (1 font-lock-builtin-face))
))

Be sure to post your results somewhere - here, the
repos (ELPA, MELPA, etc.), the EmacsWiki, #emacs, ...

And come back with more questions if you'd like.

Good luck! 

-- 
underground experts united
http://user.it.uu.se/~embe8573

Re: How to add syntax-highlighting to a Help buffer?

[Michael Heerdegen]

Raffaele Ricciardi <rfflrccrd@gmail.com> writes:

> (font-lock-add-keywords
>  nil
>  `(("\\(arbitrary regexp\\)" 1 'font-lock-function-name-face)))
>
> But the above expression breaks the existing highlighting (the
> highlighting of the function arguments disappears).

AFAICT you experience a normal "feature" of font-lock-mode.

help-mode doesn't use font-lock.  It directly attaches face text
properties to the buffer text.  If font-lock-mode fontifies such a
buffer (it doesn't as long as font-lock-keywords is nil even when it is
active), all face text properties get ignored by the display engine.
Note that there is a font-lock-face text property existing as well.

hi-lock works in this case because it handles that case specially and
uses overlays.


HTH,

Michael.

Re: How to add syntax-highlighting to a Help buffer?

[Emanuel Berg]

Michael Heerdegen <michael_heerdegen@web.de> writes:

> help-mode doesn't use font-lock. It directly attaches
> face text properties to the buffer text.
> If font-lock-mode fontifies such a buffer (it
> doesn't as long as font-lock-keywords is nil even
> when it is active), all face text properties get
> ignored by the display engine.

Yes, however that doesn't mean we can't use it the
same way we are used to. See the below solution.

One question is, why doesn't help-mode do this the
customary way?

> Note that there is a font-lock-face text property
> existing as well.

Yes - see line 17 in the source below, in the original
file. It is set to nil.

Here is is a dump that shows this works:

    http://user.it.uu.se/~embe8573/dumps/color-help.png

Here is the source that does it:

    http://user.it.uu.se/~embe8573/conf/emacs-init/help-font-lock.el

Here is the source that does it, only yanked:

(defvar help-font-lock-keywords
  '(
    ("interactive"  . 'font-lock-regexp-grouping-backslash)
    ("autoloaded"   .  font-lock-function-name-face)
    ("compiled"     .  font-lock-doc-face)
    ("Lisp"         .  font-lock-variable-name-face)
    ("function"     .  font-lock-builtin-face)
))

(defun help-custom-font-lock ()
  (interactive)
  (let ((font-lock-unfontify-region-function
         (lambda (start end)
           (remove-text-properties (point-min) (point-max)
                                   '(font-lock-face nil)))))
    (font-lock-unfontify-buffer)
    (set (make-local-variable 'font-lock-defaults)
         '(help-font-lock-keywords t))
    (font-lock-fontify-buffer)))

(add-hook 'help-mode-hook 'help-custom-font-lock)

-- 
underground experts united
http://user.it.uu.se/~embe8573

Re: How to add syntax-highlighting to a Help buffer?

[Michael Heerdegen]

Emanuel Berg <embe8573@student.uu.se> writes:

> One question is, why doesn't help-mode do this the
> customary way?

`font-lock-mode' is not so useful for the fontification of Help buffers,
so it makes sense not to use it.  For highlighting regexps, as in your
examples, hi-lock is just fine.  *Help* is mostly text, not code.

OTOH the code could be easily rewritten to use font-lock-mode and
propertize via the font-lock-face text property.  I guess the reason for
that this is not the case is just that *Help* is much older than
font-lock-face, and nobody yet wanted/needed/requested to use
font-lock-mode in *Help*.


Michael.

Re: How to add syntax-highlighting to a Help buffer?

[tomas]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Sat, Jul 04, 2015 at 05:09:03PM +0200, Emanuel Berg wrote:

[...]

> One question is, why doesn't help-mode do this the
> customary way?

Perhaps because much of font-lock's complexity deals
with keeping up with changes to the buffer (while you
are editing), something which doesn't happen to a help
buffer.

But this is just my guess.

- -- t
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)

iEYEARECAAYFAlWYCi0ACgkQBcgs9XrR2kZwZACfULir+3EKDrrfGu0YhVp3EPLO
GbAAn0zdzPX4Hyjw4eA+f5OV8Kk8M2Pe
=h0fS
-----END PGP SIGNATURE-----

Re: How to add syntax-highlighting to a Help buffer?

[Raffaele Ricciardi]

On 04/07/15 17:25, Michael Heerdegen wrote:
 > `font-lock-mode' is not so useful for the fontification of Help buffers,
 > so it makes sense not to use it.  For highlighting regexps, as in your
 > examples, hi-lock is just fine.  *Help* is mostly text, not code.

I thought that Help buffers relied on Font Lock Mode because -- in a
Help buffer -- `C-h v font-lock-mode RET' replied:

     Its value is t
     Local in buffer *Help*; global value is nil

     Non-nil if Font-Lock mode is enabled.

Had the value of `font-lock-mode' been `nil', I would have thought
otherwise.

> OTOH the code could be easily rewritten to use font-lock-mode and
> propertize via the font-lock-face text property.

Now that I have understood how things work, I doubt that it would be
beneficial to use Font Lock Mode in Help buffers, because the text could
be mixed (for example: Emacs Lisp code and regular text).  Therefore, it
makes sense to highlight each portion of text in an specific way, as
Emacs does now.

Re: How to add syntax-highlighting to a Help buffer?

[Michael Heerdegen]

Raffaele Ricciardi <rfflrccrd@gmail.com> writes:

> I thought that Help buffers relied on Font Lock Mode because -- in a
> Help buffer -- `C-h v font-lock-mode RET' replied:
>
>     Its value is t
>     Local in buffer *Help*; global value is nil
>
>     Non-nil if Font-Lock mode is enabled.

AFAIK this is a side effect of `global-font-lock-mode'.  The global mode
(on by default) enables font-lock-mode in any buffer, while the default
value of `font-lock-mode' remains nil.

But OTOH the font-lock-mode related display functions kick in only when
certain variables are not nil (like `font-lock-keywords').


Michael.

Re: How to add syntax-highlighting to a Help buffer?

[Stefan Monnier]

There are 2 "font-lock"s:

- the font-lock-mode minor mode is used to control whether to highlight
  or not.  IOW it's the way the user tells Emacs whether she wants
  things to be "colorized/highlighted/fontlocked/younameit".
- font-lock.el provides a functionality to automatically
  highlight/colorize/fontlock based on the buffer's content.

At some point in time the two were one and the same.  But there are
cases where it's easier to add the highlighting as part of the creation
of the buffer's content rather than separately (where we'd have to
re-discover what that buffer's content mean in order to highlight it
correctly).  So there were modes that highlighted their content without
resorting the to font-lock machinery.  Since then we've tried to unify
the two using the `font-lock-face' property: you can add this property
to your buffer while filling it, and if the user enables font-lock-mode
then this property will be "displayed" whereas if font-lock-mode is off
then this property stays dormant.

For some reason (not sure why) help-mode does not use the font-lock
machinery, so it could/should use the font-lock-face property, but it
has not been updated to that yet.


        Stefan

Re: How to add syntax-highlighting to a Help buffer?

[Emanuel Berg]

Michael Heerdegen <michael_heerdegen@web.de> writes:

>> One question is, why doesn't help-mode do this the
>> customary way?
>
> `font-lock-mode' is not so useful for the
> fontification of Help buffers, so it makes sense not
> to use it. For highlighting regexps, as in your
> examples, hi-lock is just fine.

I am unfamiliar with hi-lock.

> *Help* is mostly text, not code.

Yeah, but there are recurring patterns, for example
those that I just fontified: interactive, compiled,
Lisp (sometimes "C"), function, etc. Here,
highlighting could be used just as anywhere to reduce
reading and increase seeing. Hand on the heart, when
you bring up the help, do you actually *read*

    ... is an interactive compiled Lisp function ...
    
I sure don't, so for me it is a small window of
improvement to have that colorized because then it
would enter my mind that way instead (more), and
I would still not read it.

For example, having "Lisp" in one color and "C" in
another would be cool.

> OTOH the code could be easily rewritten to use
> font-lock-mode and propertize via the font-lock-face
> text property. I guess the reason for that this is
> not the case is just that *Help* is much older than
> font-lock-face, and nobody yet
> wanted/needed/requested to use font-lock-mode in
> *Help*.

Yeah, that sound reasonable.

-- 
underground experts united
http://user.it.uu.se/~embe8573

Re: How to add syntax-highlighting to a Help buffer?

[Emanuel Berg]

<tomas@tuxteam.de> writes:

> Perhaps because much of font-lock's complexity deals
> with keeping up with changes to the buffer (while
> you are editing), something which doesn't happen to
> a help buffer.

All the more reason to use it because if it isn't
edited it only has to be done once :)

-- 
underground experts united
http://user.it.uu.se/~embe8573

Re: How to add syntax-highlighting to a Help buffer?

[Emanuel Berg]

Raffaele Ricciardi <rfflrccrd@gmail.com> writes:

> I thought that Help buffers relied on Font Lock Mode
> because -- in a Help buffer -- `C-h v font-lock-mode
> RET' replied:
>
>     Its value is t Local in buffer *Help*; global
> value is nil
>
>     Non-nil if Font-Lock mode is enabled.
>
> Had the value of `font-lock-mode' been `nil',
> I would have thought otherwise.

Yeah, but just because it is enabled doesn't mean it
is used.

I don't know why it is enabled if it isn't used,
perhaps someone else can answer that.

> Now that I have understood how things work, I doubt
> that it would be beneficial to use Font Lock Mode in
> Help buffers, because the text could be mixed (for
> example: Emacs Lisp code and regular text).

That is not a problem and that happens all the time.
The regexps are so advanced.

This sentence -

    describe-key is an interactive compiled Lisp
    function in `help.el'

- can be picked apart with only one regexp, and with
groups every single word can be highlighted in
a different color, and none of that that appears
anywhere else would get that color.

I'll do an example some other time and show you.
But if you don't want it, I still want it :)

-- 
underground experts united
http://user.it.uu.se/~embe8573