facemenu-listed-faces

["Drew Adams" <drew.adams@oracle.com>]

I don't understand user option `facemenu-listed-faces'. Shouldn't the
default value be t? Wouldn't it be normal, whenever the user applies a face
to text, to add that face to the menu? Isn't that the usual case, which
should be the default?

Also, this user option is not explained anywhere in either the Emacs manual
or the Elisp manual. Given that I don't understand the doc string well (e.g.
"this value _takes effect_ (??) when you load facemenu.el"), I would
appreciate some more explanation.

This is a user option, but the doc string reads as if it were an internal
variable ("subsequently defining or creating those faces", "you can call
`facemenu-update'", etc.). I think we need some user doc for this option,
and it needs to be clear on how you can make use of it.