bug#50041: Add font-lock-doc-markup-face

[Eli Zaretskii <eliz@gnu.org>]

> From: Mattias Engdegård <mattiase@acm.org>
> Date: Fri, 13 Aug 2021 19:41:06 +0200
> Cc: larsi@gnus.org, 50041@debbugs.gnu.org
> 
> >  If so, I think the NEWS entry and the doc string should
> > say so, at least as an example of the intended usage.  I've read the
> > doc string you suggested several time, and still couldn't figure out
> > what the face is for: the description seems too abstract.
> 
> It was assumed that the user of the new face would already be familiar with font-lock-doc-face and its uses.

If the doc string of font-lock-doc-face would explain its usage,
having a link to it might be sufficient.  But doc string of
font-lock-doc-face is just this:

  "Font Lock mode face used to highlight documentation."

I hope you agree with me that this is insufficient, and thus
mentioning it in the doc string of this new face is not enough?

Also, I think "for mark-up elements" is too terse and assumes too much
of prior knowledge; we should make more clear what that means, or
provide a couple of examples.

> The first version of the patch did mention both Javadoc and Doxygen but I re-wrote it after your comments indicated that it might have been unclear. I've now put that explanation back and extended the face doc string and manual entry.

Thanks.  The NEWS entry is now clear enough, but I think the manual
and the doc string still need some work.