Feature Request: Help: Display Relevant Bits First?

Feature Request: Help: Display Relevant Bits First?

[T.V Raman]

At present, if you do describe-function on any command that toggles a
mode, you get a lot of common boiler-plate, with the salient bits
about that particular function at the end -- could we reverse this?

As an example, here is what C-h f font-lock-mode shows 

I'd personally find it more useful if the block of text between 
"this is a minor mode . ..." and 
"the mode's hook is called ..." appeared at the end of the help
buffer.

Thoughts?
font-lock-mode is an interactive compiled Lisp function in
‘font-core.el’.

(font-lock-mode &optional ARG)

Toggle syntax highlighting in this buffer (Font Lock mode).

This is a minor mode.  If called interactively, toggle the ‘Font-Lock
mode’ mode.  If the prefix argument is positive, enable the mode, and
if it is zero or negative, disable the mode.

If called from Lisp, toggle the mode if ARG is ‘toggle’.  Enable the
mode if ARG is nil, omitted, or is a positive number.  Disable the
mode if ARG is a negative number.

To check whether the minor mode is enabled in the current buffer,
evaluate ‘font-lock-mode’.

The mode’s hook is called both when the mode is enabled and when it is
disabled.

When Font Lock mode is enabled, text is fontified as you type it:

 - Comments are displayed in ‘font-lock-comment-face’;
 - Strings are displayed in ‘font-lock-string-face’;
 - Certain other expressions are displayed in other faces
   according to the value of the variable ‘font-lock-keywords’.

To customize the faces (colors, fonts, etc.) used by Font Lock for
fontifying different parts of buffer text, use M-x customize-face.

You can enable Font Lock mode in any major mode automatically by
turning on in the major mode’s hook.  For example, put in your
~/.emacs:

 (add-hook 'c-mode-hook 'turn-on-font-lock)

Alternatively, you can use Global Font Lock mode to automagically
turn on Font Lock mode in buffers whose major mode supports it
and whose major mode is one of ‘font-lock-global-modes’.  For
example, put in your ~/.emacs:

 (global-font-lock-mode t)

Where major modes support different levels of fontification, you
can use the variable ‘font-lock-maximum-decoration’ to specify
which level you generally prefer.  When you turn Font Lock mode
on/off the buffer is fontified/defontified, though fontification
occurs only if the buffer is less than ‘font-lock-maximum-size’.

To add your own highlighting for some major mode, and modify the
highlighting selected automatically via the variable
‘font-lock-maximum-decoration’, you can use
‘font-lock-add-keywords’.

To fontify a buffer, without turning on Font Lock mode and
regardless of buffer size, you can use M-x font-lock-fontify-buffer.

To fontify a block (the function or paragraph containing point,
or a number of lines around point), perhaps because modification
on the current line caused syntactic change on other lines, you
can use M-x font-lock-fontify-block.

You can set your own default settings for some mode, by setting a
buffer local value for ‘font-lock-defaults’, via its mode hook.

The above is the default behavior of ‘font-lock-mode’; you may
specify your own function which is called when ‘font-lock-mode’
is toggled via ‘font-lock-function’.

  Probably introduced at or before Emacs version 19.29.

-- 

Thanks,

--Raman(I Search, I Find, I Misplace, I Research)
♉ Id: kg:/m/0285kf1  🦮

--

Thanks,

--Raman(I Search, I Find, I Misplace, I Research)
♉ Id: kg:/m/0285kf1  🦮

RE: [External] : Feature Request: Help: Display Relevant Bits First?

[Drew Adams]

> At present, if you do describe-function on any command that toggles a
> mode, you get a lot of common boiler-plate, with the salient bits
> about that particular function at the end -- could we reverse this?

The most salient info is the first line of the doc string:

  Toggle syntax highlighting in this buffer (Font Lock mode).

But that's part of the text (you say) you want moved to
the end.

Anyway, I support your general proposal.  I agree that
minor-mode boilerplate info should come after specifics
about the particular minor mode.  It might even be good
to separate the two with a separator (e.g. line).

The problem of documenting minor modes has been around a
l o n g  time.  For a long time the boilerplate info was
only in the doc of `define-minor-mode' itself (but a few
minor-mode doc strings duplicated some of that info).

Eventually maybe we'll get to a place where `C-h f' for a
minor mode shows both the particular info (preferably up
front) and the generic (boilerplate) info, consistently
for all minor modes, and preferably with the two separated.

Either that or just show the particular info and (always)
provide a link to a single description of the generic
(boilerplate) info - IOW, factor that out.  But introduce
that link by saying that it describes the behavior of all
minor modes (to make clear that it's part of the behavior
of this particular command).

RE: [External] : Feature Request: Help: Display Relevant Bits First?

[T.V Raman]

No, I dont want that first line moved -- it's subsequent boiler plate
around the description of the prefix arg etc that I was talking about.
Drew Adams writes:
 > > At present, if you do describe-function on any command that toggles a
 > > mode, you get a lot of common boiler-plate, with the salient bits
 > > about that particular function at the end -- could we reverse this?
 > 
 > The most salient info is the first line of the doc string:
 > 
 >   Toggle syntax highlighting in this buffer (Font Lock mode).
 > 
 > But that's part of the text (you say) you want moved to
 > the end.
 > 
 > Anyway, I support your general proposal.  I agree that
 > minor-mode boilerplate info should come after specifics
 > about the particular minor mode.  It might even be good
 > to separate the two with a separator (e.g. line).
 > 
 > The problem of documenting minor modes has been around a
 > l o n g  time.  For a long time the boilerplate info was
 > only in the doc of `define-minor-mode' itself (but a few
 > minor-mode doc strings duplicated some of that info).
 > 
 > Eventually maybe we'll get to a place where `C-h f' for a
 > minor mode shows both the particular info (preferably up
 > front) and the generic (boilerplate) info, consistently
 > for all minor modes, and preferably with the two separated.
 > 
 > Either that or just show the particular info and (always)
 > provide a link to a single description of the generic
 > (boilerplate) info - IOW, factor that out.  But introduce
 > that link by saying that it describes the behavior of all
 > minor modes (to make clear that it's part of the behavior
 > of this particular command).

-- 

Thanks,

--Raman(I Search, I Find, I Misplace, I Research)
♉ Id: kg:/m/0285kf1  🦮

--

Thanks,

--Raman(I Search, I Find, I Misplace, I Research)
♉ Id: kg:/m/0285kf1  🦮

Re: Feature Request: Help: Display Relevant Bits First?

[Lars Ingebrigtsen]

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

> At present, if you do describe-function on any command that toggles a
> mode, you get a lot of common boiler-plate, with the salient bits
> about that particular function at the end -- could we reverse this?

I agree completely, especially as the boilerplate has expanded over the
years.  I've now moved it to the end of the doc strings in Emacs 29.

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

Re: Feature Request: Help: Display Relevant Bits First?

[Basil L. Contovounesios]

Lars Ingebrigtsen [2022-04-02 15:56 +0200] wrote:

> "T.V Raman" <raman@google.com> writes:
>
>> At present, if you do describe-function on any command that toggles a
>> mode, you get a lot of common boiler-plate, with the salient bits
>> about that particular function at the end -- could we reverse this?
>
> I agree completely, especially as the boilerplate has expanded over the
> years.  I've now moved it to the end of the doc strings in Emacs 29.

Thanks, but the changes in easy-mmode.el don't bootstrap, maybe because
they rely on subr-x.el definitions that are autoloaded only after some
of easy-mmode.el's clients, such as files.el, are loaded in loadup.el.

-- 
Basil

Re: Feature Request: Help: Display Relevant Bits First?

[Lars Ingebrigtsen]

"Basil L. Contovounesios" <contovob@tcd.ie> writes:

> Thanks, but the changes in easy-mmode.el don't bootstrap, maybe because
> they rely on subr-x.el definitions that are autoloaded only after some
> of easy-mmode.el's clients, such as files.el, are loaded in loadup.el.

Oops.  Should now be fixed.

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

Re: Feature Request: Help: Display Relevant Bits First?

[T.V Raman]

Awesome, Thanks!

And speaking of the boiler-plate, I have always found  the sense in
which -1 vs 1 is used in all the minor-mode toggle functions, where
nil actually turns it  on --that usage is too late to change. But
could we perhaps alleviate the pain by adding two special values 'on
and 'off so that
(font-lock-mode 'on) turns it on and (font-lock-mode 'offf) turns it
off?
Lars Ingebrigtsen writes:
 > "T.V Raman" <raman@google.com> writes:
 > 
 > > At present, if you do describe-function on any command that toggles a
 > > mode, you get a lot of common boiler-plate, with the salient bits
 > > about that particular function at the end -- could we reverse this?
 > 
 > I agree completely, especially as the boilerplate has expanded over the
 > years.  I've now moved it to the end of the doc strings in Emacs 29.
 > 
 > -- 
 > (domestic pets only, the antidote for overdose, milk.)
 >    bloggy blog: http://lars.ingebrigtsen.no

-- 

Thanks,

--Raman(I Search, I Find, I Misplace, I Research)
♉ Id: kg:/m/0285kf1  🦮

--

Thanks,

--Raman(I Search, I Find, I Misplace, I Research)
♉ Id: kg:/m/0285kf1  🦮

Re: Feature Request: Help: Display Relevant Bits First?

[Lars Ingebrigtsen]

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

> And speaking of the boiler-plate, I have always found the sense in
> which -1 vs 1 is used in all the minor-mode toggle functions, where
> nil actually turns it on --that usage is too late to change. But could
> we perhaps alleviate the pain by adding two special values 'on and
> 'off so that (font-lock-mode 'on) turns it on and (font-lock-mode
> 'offf) turns it off?

I don't think adding further values here will help much with the
confusion, since there's code going back decades out there that uses the
old values, and that won't change.

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

Re: Feature Request: Help: Display Relevant Bits First?

[Po Lu]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> I agree completely, especially as the boilerplate has expanded over the
> years.  I've now moved it to the end of the doc strings in Emacs 29.

Yes, this has been overdue for a long time now.  Thanks.