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

[Eli Zaretskii]

> 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.