GNU bug report logs - #36478
26.2; Doc strings with "This function has a compiler macro..." and "This function does not change global state"

Previous Next

Full log

View this message in rfc822 format

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: bug#36478 <36478 <at> debbugs.gnu.org>
Subject: bug#36478: Perhaps rearrange *Help* buffer a bit?
Date: Mon, 08 Jul 2019 17:14:05 -0400

> I think Drew (or somebody?) mentioned this in a bug report the other
> day: The way the automated stuff is arranged in the *Help* buffer is
> perhaps not optimal.

>   This function has a compiler macro ‘internal--compiler-macro-cXXr’.
>   Probably introduced at or before Emacs version 20.
[...]
>   Probably introduced at or before Emacs version 1.2.
>   This function does not change global state, including the match data.
[...]
> So the thought here is that those indented lines isn't what's most
> interesting to the user.

I recently reworked the generation of this text specifically to try and
make it easier to tweak it.

> Anyway, what about rearranging this a bit so that the stuff the users
> are interested in comes first?
[...]
> Let the bike-shedding commence!

Here's my favorite color: 
- don't move it to the end, because it's much too far.
- hide it by default, with some obvious-enough button-like thingy to
  expand it on demand.
- maybe the first line could also be moved into this "metadata" block.
- These *Help* buffers would benefit from a bit of face-lift (e.g. put
  a different face on the metadata part, yet another on the
  calling-convention example, ...).


        Stefan

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.