Make DISCARD-COMMENTS in `libxml-parse-{html,xml}-region' obsolete

* doc/lispref/text.texi (Parsing HTML/XML): Mention that
discard-comments is obsolete.

* lisp/xml.el (xml-remove-comments): New function (bug#27178).

* src/xml.c (Flibxml_parse_html_region): Clarify what
DISCARD-COMMENTS actually does, and say that the parameter is
obsolete.
(Flibxml_parse_xml_region): Ditto.

1 files changed, 4 insertions, 1 deletions

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 9769043b729..e89bd0b7ef7 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -4724,7 +4724,10 @@ The optional argument @var{base-url}, if non-@code{nil}, should be a
 string specifying the base URL for relative URLs occurring in links.
 
 If the optional argument @var{discard-comments} is non-@code{nil},
-then the parse tree is created without any comments.
+any top-level comment is discarded.  (This argument is obsolete and
+will be removed in future Emacs versions.  To remove comments, use the
+@code{xml-remove-comments} utility function on the data before you
+call the parsing function.)
 
 In the parse tree, each HTML node is represented by a list in which
 the first element is a symbol representing the node name, the second