RE: read-face-name doc string incorrect

[Drew Adams]

Hi Nick,

     > The doc string for read-face-name says this:
     >
     >  Read a face, defaulting to the face or faces on the char
     >  after point.  If it has a `read-face-name' property, that
     >  overrides the `face' property.  prompt describes what you
     >  will do with the face (don't end in a space).
     >  string-describing-default describes what default you will use
     >  if this function returns nil.
     >  If multiple is non-nil, return a list of faces (possibly only one).
     >  Otherwise, return a single face.
     >
     > The part about "if this function returns nil" is incorrect. The
     > function never returns nil - it returns a non-empty list of
     > faces or a single face. This should say something to the effect
     > of "if the user just hits RET".

    It does return nil e.g with customize-face when the user hits RET.

In that case, the part about "(possibly only one)" or "a single face" is
incorrect or, at best, misleading. It's not clear to me, in any case.

    It wouldn't make sense to say "if the user just hits RET" for
    read-face-name because it's not an interactive function.

It calls completing-read, which reads user input. The "default to use"
presumably refers to the case where the user just hits `RET'. My point was
not to propose exact wording but to indicate that that section of the doc
string has nothing to do with what the function returns - it has to do with
how the user responds to the prompt for input (IIUC).

    I agree that it's not clear from the doc string what
    read-face-name returns.

A lot is unclear about the doc string. The main thing unclear to me is what
the prompt and default-string arg are for and what they should look like.
All I know is that the prompt should not end in a space (!).

    The phrase "If it has a `read-face-name' property," appears as a link to
    the function read-face-name so perhaps it could be rewritten as:

    If it has the property `read-face-name',...

I don't see the difference in meaning there.

    and help-xref-symbol-regexp modified by replacing
"\\(symbol\\|program\\)\\|"
with "\\(symbol\\|program\\|property\\)\\|".

Ah, I see what you meant now. That would be an extra nicety here.

The main problem is that it is unclear what the prompt string and the
default-string should be. Apparently, the prompt string is different from
usual. I really don't see what they should be. How about an example?

 > The prompt and default-string are not clear, in any case, especially
 > the part about describing what you will do with the face and not
 > ending in a space. The doc string must give an example, or no one will
 > understand what kind of prompt string and default-string arguments to
 > use.

 I think the elisp manual is the right place for examples but I don't think
 read-face-name is described there.  But then it's not used much either.

Either some way needs to be found to describe clearly what those two
arguments should be, or a simple example should do that. If it's easier and
clearer to show with a short example, then there is no reason not to do
that. If you can describe these args clearly without an example, that's
fine.

I really have no clue what's intended or how they are used (beyond the fact
that prompt is a prompt - but it is apparently different from normal, not
ending in ": ").

We use ~examples in doc strings all the time, in the sense of showing
patterns like (REGEXP . FUNCTION). Whether the example is concrete or an
abstract template is not so important - the point is that it's sometimes
easier to show what the thing looks like than to just describe it in words.

For example, if the prompt and default-string are somehow combined to create
the actual prompt used, then depict this, showing the resulting prompt as
composed of the two inputs. I can't help here, because I don't understand
what happens.

Thx - Drew