definition lines in Info - 1) link, 2) highlight

definition lines in Info - 1) link, 2) highlight

[Drew Adams]

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

1) This has perhaps been suggested before; I don't know.

How about having definition/reference lines such as the following be links
in the Elisp Info manual?

 - Variable: blink-paren-function
 - User Option: blink-matching-paren
 - Command: blink-matching-open

What would the link target be? Clicking such a link could 1) show you the
current value of a variable, a la pp-eval-expression, and 2) take you to the
defining source code. In many cases, the current value of a variable would
fit in the echo area; in other cases, two buffers would be displayed: the
source-code file and *Pp Eval Output*. For other than variables, only #2
would happen.


2) A related suggestion is this (which I think I might have made already):
highlight definition/reference lines in Info, so they stand out better. See
attached screenshot.

I do this in my own code, and I find that it helps readability. I use a
slightly different background color for the line, starting after the "- ",
and I use a different foregound color for each type name: Variable, User
Option, Command, Macro, Function, Special Form, and Syntax Class. In
particular, this helps you distinguish Variable and User Option visually;
likewise, Function and Command.

The regexp is trivial, and so far I've never seen a false or missed hit:
"^ --? \\(Function:\\|Variable:\\|Special Form:\\|\
Command:\\|User Option:\\|Macro:\\|Syntax class:\\)\\(.*\\)"



[-- Attachment #2: info-reference-items.jpg --]
[-- Type: image/jpeg, Size: 548624 bytes --]

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

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: definition lines in Info - 1) link, 2) highlight

[Richard Stallman]

    2) A related suggestion is this (which I think I might have made already):
    highlight definition/reference lines in Info, so they stand out better. See
    attached screenshot.

    I do this in my own code, and I find that it helps readability. I use a
    slightly different background color for the line, starting after the "- ",
    and I use a different foregound color for each type name: Variable, User
    Option, Command, Macro, Function, Special Form, and Syntax Class. In
    particular, this helps you distinguish Variable and User Option visually;
    likewise, Function and Command.

    The regexp is trivial, and so far I've never seen a false or missed hit:
    "^ --? \\(Function:\\|Variable:\\|Special Form:\\|\
    Command:\\|User Option:\\|Macro:\\|Syntax class:\\)\\(.*\\)"

That sounds like a good idea, and small enough we can use it from you
without papers.  Eli, if no one objects in a few days, would you
please install?

    How about having definition/reference lines such as the following be links
    in the Elisp Info manual?

     - Variable: blink-paren-function
     - User Option: blink-matching-paren
     - Command: blink-matching-open

That is much harder; we should not think about it now.

Re: definition lines in Info - 1) link, 2) highlight

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Fri, 11 Aug 2006 15:24:04 -0400
> Cc: emacs-devel@gnu.org
> 
>     2) A related suggestion is this (which I think I might have made already):
>     highlight definition/reference lines in Info, so they stand out better. See
>     attached screenshot.
> 
>     I do this in my own code, and I find that it helps readability. I use a
>     slightly different background color for the line, starting after the "- ",
>     and I use a different foregound color for each type name: Variable, User
>     Option, Command, Macro, Function, Special Form, and Syntax Class. In
>     particular, this helps you distinguish Variable and User Option visually;
>     likewise, Function and Command.
> 
>     The regexp is trivial, and so far I've never seen a false or missed hit:
>     "^ --? \\(Function:\\|Variable:\\|Special Form:\\|\
>     Command:\\|User Option:\\|Macro:\\|Syntax class:\\)\\(.*\\)"
> 
> That sounds like a good idea, and small enough we can use it from you
> without papers.  Eli, if no one objects in a few days, would you
> please install?

Sorry, I don't understand what to install.  Drew didn't show any code,
nor explained in detail what the code should do and how.  The only
thing I see is a regexp.  Is there already a variable that should be
set to that regexp?  If so, please tell which variable is that.

RE: definition lines in Info - 1) link, 2) highlight

[Drew Adams]

    Sorry, I don't understand what to install.  Drew didn't show any code,
    nor explained in detail what the code should do and how.  The only
    thing I see is a regexp.  Is there already a variable that should be
    set to that regexp?  If so, please tell which variable is that.

I can point you to my code, but Richard might not like that. Here is an
abstract description:

The code searches an Info node for one-line descriptions (specs) of
functions, macros, variables etc., and fontifies these descriptions. An
example description is "Function: foo INTEGER1 &optional INTEGER2". The idea
is to make such lines stand out a bit, and to distinguish the different
types (function, command, etc.).

One way to do it:

1. Define a face for each of the description types: Function, Special Form,
etc. I have 7 such faces, so a reader can easily pick out, say, a Command or
Variable from a list of Functions.

2. Define a face for the rest of each description line, to be used for all
description types. That is, a description such as "Function: foo INTEGER1
&optional INTEGER2" will have one face applied to "Function:" and another
face applied to " foo INTEGER1 &optional INTEGER2". I use the same
background for all 8 faces.

3. Define a function that searches a node for the regexp and fontifies (via
put-text-property) accordingly, using the faces.

4. Call #3 in Info-fontify-node. For Emacs 22, I do that just before the
titles are fontified.

Let me know if you need more detail.

Re: definition lines in Info - 1) link, 2) highlight

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Sat, 12 Aug 2006 10:33:23 -0700
> 
> One way to do it:
> 
> 1. Define a face for each of the description types: Function, Special Form,
> etc. I have 7 such faces, so a reader can easily pick out, say, a Command or
> Variable from a list of Functions.
> 
> 2. Define a face for the rest of each description line, to be used for all
> description types. That is, a description such as "Function: foo INTEGER1
> &optional INTEGER2" will have one face applied to "Function:" and another
> face applied to " foo INTEGER1 &optional INTEGER2". I use the same
> background for all 8 faces.
> 
> 3. Define a function that searches a node for the regexp and fontifies (via
> put-text-property) accordingly, using the faces.
> 
> 4. Call #3 in Info-fontify-node. For Emacs 22, I do that just before the
> titles are fontified.

Thanks.

Richard, is this what you had in mind?  Frankly, it sounds too
complicated to me to install at this point.

Re: definition lines in Info - 1) link, 2) highlight

[Richard Stallman]

    Richard, is this what you had in mind?  Frankly, it sounds too
    complicated to me to install at this point.

I think it could be a lot simpler.  Just add a loop to
Info-fontify-node which would search for that regexp and apply some
faces to the parts that match.

RE: definition lines in Info - 1) link, 2) highlight

[Drew Adams]

        Richard, is this what you had in mind?  Frankly, it sounds too
        complicated to me to install at this point.

    I think it could be a lot simpler.  Just add a loop to
    Info-fontify-node which would search for that regexp and apply some
    faces to the parts that match.

That's exactly what I was trying to say. I just suggested putting the loop
in a separate function, to be called from Info-fontify-node.

Re: definition lines in Info - 1) link, 2) highlight

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> CC: drew.adams@oracle.com, emacs-devel@gnu.org
> Date: Sun, 13 Aug 2006 09:53:28 -0400
> 
>     Richard, is this what you had in mind?  Frankly, it sounds too
>     complicated to me to install at this point.
> 
> I think it could be a lot simpler.  Just add a loop to
> Info-fontify-node which would search for that regexp and apply some
> faces to the parts that match.

Introducing new faces is never simple.  I'd rather leave this alone
until after the release.  But if you insist, perhaps using hi-lock,
an existing facility, would be safer.

Re: definition lines in Info - 1) link, 2) highlight

[Richard Stallman]

    > I think it could be a lot simpler.  Just add a loop to
    > Info-fontify-node which would search for that regexp and apply some
    > faces to the parts that match.

    Introducing new faces is never simple.

It doesn't need to use new faces.  Surely there is some existing
font lock face that would be usable.

RE: definition lines in Info - 1) link, 2) highlight

[Drew Adams]

        > I think it could be a lot simpler.  Just add a loop to
        > Info-fontify-node which would search for that regexp and
        > apply some faces to the parts that match.

        Introducing new faces is never simple.

    It doesn't need to use new faces.  Surely there is some existing
    font lock face that would be usable.

Faces are like global variables - user options. You wouldn't think of
"reusing" some user option that happened to have a default value of t or nil
or 100 that you were after, instead of defining a new user option that had
the same default value - because customizing one might not be appropriate
for the uses of the other. The same is true of faces.

People can, for instance, use a different background for special-display
buffers such as *Info*, and a face that is appropriate for
non-special-display buffers might not then be appropriate for *Info*. Even
an existing Info face might not be appropriate here, depending on how users
might have customized it.

How about waiting until after the release for this, and doing it right,
creating separate faces for this feature?

The other, related suggestion here was more important, and would wait until
after the release anyway (if implemented): link to the source code and
display the current value (for a variable).

BTW, I'm curious - why is introducing new faces not simple? Is it because of
trying to get the default value right for different types of display and
different background values? Perhaps there are some guidelines that might
apply here? I don't know; I'm just curious what the difficulty is.

As I say, better to do it right, after the release, than to do a hurried job
poorly now. But, if you do want to do it now, it might be better to define
new faces that might not have great default values for all contexts than it
would be to reuse existing faces. If you define new faces, even bad ones,
users can at least customize them independently. And users will provide
feedback to help you tweak the default values so they work well in all
contexts.

Re: definition lines in Info - 1) link, 2) highlight

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Tue, 15 Aug 2006 07:57:46 -0700
> 
> BTW, I'm curious - why is introducing new faces not simple? Is it because of
> trying to get the default value right for different types of display and
> different background values?

That, and the ensuing endless arguments about what should the default
colors be.

RE: definition lines in Info - 1) link, 2) highlight

[Drew Adams]

    > BTW, I'm curious - why is introducing new faces not simple?
    > Is it because of trying to get the default value right for
    > different types of display and different background values?

    That, and the ensuing endless arguments about what should the default
    colors be.

Well, then, as I say, either 1) wait until after the release, to give people
lots of time to argue about the best defaults ;-), or 2) define new faces
with possibly imperfect defaults, and let users provide feedback that will
help determine better defaults.

IMO, there will be more argument and frustration if this is implemented
using existing faces: 1) the defaults are just as likely to be bad, 2) the
same discussion will have been skipped (not necessarily a bad thing, IMO),
and 3) there will be no way for users to experiment with different values in
different contexts (e.g. diff backgrounds) and provide feedback to improve
the default values.

If existing faces are reused, however, then users can't customize this
feature without also inadvertently customizing some other features, and
probably what works well for one context will not work well for another.
Faces are essentially global variables; they should be as specific as are
user variables.

Re: definition lines in Info - 1) link, 2) highlight

[David Kastrup]

"Drew Adams" <drew.adams@oracle.com> writes:

>         > I think it could be a lot simpler.  Just add a loop to
>         > Info-fontify-node which would search for that regexp and
>         > apply some faces to the parts that match.
>
>         Introducing new faces is never simple.
>
>     It doesn't need to use new faces.  Surely there is some existing
>     font lock face that would be usable.
>
> Faces are like global variables - user options. You wouldn't think
> of "reusing" some user option that happened to have a default value
> of t or nil or 100 that you were after, instead of defining a new
> user option that had the same default value - because customizing
> one might not be appropriate for the uses of the other. The same is
> true of faces.

[Rest of lecture deleted]

Uhm, Drew?  There is a slight probability that Richard has some
passing acquaintance with faces.  Instead of lecturing him, it might
be smarter to ask for an explanation if you don't get his point.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

RE: definition lines in Info - 1) link, 2) highlight

[Drew Adams]

    >         > I think it could be a lot simpler.  Just add a loop to
    >         > Info-fontify-node which would search for that regexp and
    >         > apply some faces to the parts that match.
    >
    >         Introducing new faces is never simple.
    >
    >     It doesn't need to use new faces.  Surely there is some existing
    >     font lock face that would be usable.
    >
    > Faces are like global variables - user options. You wouldn't think
    > of "reusing" some user option that happened to have a default value
    > of t or nil or 100 that you were after, instead of defining a new
    > user option that had the same default value - because customizing
    > one might not be appropriate for the uses of the other. The same is
    > true of faces.

    [Rest of lecture deleted]

    Uhm, Drew?  There is a slight probability that Richard has some
    passing acquaintance with faces.  Instead of lecturing him, it might
    be smarter to ask for an explanation if you don't get his point.

Feel better now David? Good.

You be smart and ask for an explanation of what the wise words mean; I'll be
stupid and disagree with his point. Progress by exegesis or dialectics?

Sorry to blaspheme in your eyes, but... Richard is (shudder) human, and is
not always right. Please don't assume that disagreeing with Richard means
not understanding his point. Likewise, Jesus, Mohammed, Buddha, Marx, Dylan,
and the rest.

As to *your* technical point in this discussion: =?

 - Drew, infidel, AND as RMS-reverent as unnamable high holier-than-thous

Re: definition lines in Info - 1) link, 2) highlight

[Chong Yidong]

"Drew Adams" <drew.adams@oracle.com> writes:

>     >     It doesn't need to use new faces.  Surely there is some existing
>     >     font lock face that would be usable.
>     >
>     > Faces are like global variables - user options. You wouldn't think
>     > of "reusing" some user option that happened to have a default value
>     > of t or nil or 100 that you were after, instead of defining a new
>     > user option that had the same default value - because customizing
>     > one might not be appropriate for the uses of the other. The same is
>     > true of faces.
>
>     [Rest of lecture deleted]
>
>     Uhm, Drew?  There is a slight probability that Richard has some
>     passing acquaintance with faces.  Instead of lecturing him, it might
>     be smarter to ask for an explanation if you don't get his point.
>
> Sorry to blaspheme in your eyes, but... Richard is (shudder) human, and is
> not always right. Please don't assume that disagreeing with Richard means
> not understanding his point. Likewise, Jesus, Mohammed, Buddha, Marx, Dylan,
> and the rest.
>
> As to *your* technical point in this discussion: =?

Though David was a tad abrasive in pointing this out, I too didn't see
the point of your grand-post.  After all, the whole point of the
default font-lock faces is to be re-used in many different situations.

RE: definition lines in Info - 1) link, 2) highlight

[Drew Adams]

    >     >     It doesn't need to use new faces.  Surely there is
    >     >     some existing font lock face that would be usable.
    >     >
    >     > Faces are like global variables - user options. You
    >     > wouldn't think of "reusing" some user option that
    >     > happened to have a default value of t or nil or 100
    >     > that you were after, instead of defining a new
    >     > user option that had the same default value - because
    >     > customizing one might not be appropriate for the uses
    >     > of the other. The same is true of faces.
    >
    >     [Rest of lecture deleted]
    >
    >     Uhm, Drew?  There is a slight probability that Richard
    >     has some passing acquaintance with faces.  Instead of
    >     lecturing him, it might be smarter to ask for an
    >     explanation if you don't get his point.
    >
    > Sorry to blaspheme in your eyes, but... Richard is
    > (shudder) human, and is not always right. Please don't
    > assume that disagreeing with Richard means not
    > understanding his point. Likewise, Jesus, Mohammed,
    > Buddha, Marx, Dylan, and the rest.
    >
    > As to *your* technical point in this discussion: =?

    Though David was a tad abrasive in pointing this out, I too
    didn't see the point of your grand-post.

Then I wasn't clear. The points were these:

1) Don't reuse faces for this feature, especially if only because someone
might be in a hurry - wait until after the release, and then do it right.

2) The more important suggestion for this feature is to link to the source
code and display the current value (for a variable) - and that would need to
wait until after the release anyway.

In sum, the point is that implementing this feature after the release makes
sense.

    After all, the whole point of the default font-lock faces
    is to be re-used in many different situations.

Ah, *font-lock* faces. Yes, indeed. They are to be reused in many different
*font-lock* situations. IMO, it is usually *not* appropriate to reuse a
font-lock face for something that is not font-lock-related. Do you disagree?

If I give you a face for the mode-line (or for the gimwort), for instance,
and instead of creating a new face I reuse `font-lock-comment-face', is that
a good idea? Not IMO. Of course, there would be nothing wrong with reuse by
copying the default value of `font-lock-comment-face', but simply pointing
to the existing face is not TRT, IMO.

Re: definition lines in Info - 1) link, 2) highlight

[Richard Stallman]

    Faces are like global variables - user options. You wouldn't think of
    "reusing" some user option that happened to have a default value of t or nil
    or 100 that you were after, instead of defining a new user option that had
    the same default value - because customizing one might not be appropriate
    for the uses of the other. The same is true of faces.

We often do use a face for similar purposes in various contexts,
just as we do for variables.

    How about waiting until after the release for this, and doing it right,
    creating separate faces for this feature?

I won't insist on installing it now.

RE: definition lines in Info - 1) link, 2) highlight

[Drew Adams]

        How about having Info definition/reference lines such as the
        following be links in the Elisp Info manual?

         - Variable: blink-paren-function
         - User Option: blink-matching-paren
         - Command: blink-matching-open

    That is much harder; we should not think about it now.

I didn't mean that it should be done now. Feature suggestions are for after
the release, IIUC.