RE: `facemenu-set-face' doesn't add face to the Face menu

[Drew Adams]

    I think this will make the doc strings correct.  Thanks.

I don't think the second paragraph here (To "add FACE"...) is correct:

      (defun facemenu-set-face (face &optional start end)
        "Add FACE to the region or next character typed.
    ! If the region is active (normally true except in Transient
    ! Mark mode) and there is no prefix argument, this command
    ! adds FACE to the region.  Otherwise, this command adds FACE
    ! to the faces to use for the next character
    ! inserted.  (Moving point or switching buffers before typing
    ! a character to insert cancels the specification.)
    !
    ! To \"add FACE\" means putting FACE at the front of the list
    ! of faces to be used.  It also removes any faces further
    ! along in the list that would be completely overridden by
    ! preceding faces (including FACE).

    ! This command also adds FACE to the menu of faces
    ! if `facemenu-listed-faces' says to do that."

To "add" FACE in the first paragraph means to apply it to the region. That
has nothing to do with putting it at the front of the list of faces to be
used, unless I misunderstand. If you apply it to a region, then the text in
the region gets that face; that's all - no?

And, applying the face to the region (1) and adding the face to the front of
the face list (2) have nothing to do with adding FACE to the facemenu, no?

This needs to be clarified, whether or not I'm right. It seems that there
are at least two senses here of "adding" a face.

More importantly, this is the reason I sent this bug report: I don't
understand how `facemenu-listed-faces' determines whether a face gets added
to the face menu by `facemenu-add-face'. So, perhaps the doc string of
`facemenu-listed-faces' also needs to be clarified (since the other two doc
strings just refer to it wrt this).

If you're not sure what to say, let me know how it works, and I'll suggest
what to say. For the moment, I don't understand why `facemenu-set-face'
doesn't seem to add a face that you apply to the region to the face menu.