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, 8 insertions, 0 deletions

diff --git a/etc/NEWS b/etc/NEWS
index 980a5b453a2..0bf5ba80b38 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -116,6 +116,14 @@ indirectly, e.g., by checking that functions like
 'libxml-parse-html-region' return nil.
 
 +++
+** `libxml-parse-xml-region' and `libxml-parse-html' region take
+a parameter that's called DISCARD-COMMENTS, but it really only
+discards the top-level comment.  Therefore this parameter is now
+obsolete, and the new utility function `xml-remove-comments' can be
+used to remove comments before calling the libxml functions to parse
+the data.
+
++++
 ** New function 'fill-polish-nobreak-p', to be used in 'fill-nobreak-predicate'.
 It blocks line breaking after a one-letter word, also in the case when
 this word is preceded by a non-space, but non-alphanumeric character.