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, 12 insertions, 2 deletions

diff --git a/src/xml.c b/src/xml.c
index 42059d77131..fa88040597d 100644
--- a/src/xml.c
+++ b/src/xml.c
@@ -271,7 +271,12 @@ DEFUN ("libxml-parse-html-region", Flibxml_parse_html_region,
        2, 4, 0,
        doc: /* Parse the region as an HTML document and return the parse tree.
 If BASE-URL is non-nil, it is used to expand relative URLs.
-If DISCARD-COMMENTS is non-nil, all HTML comments are discarded. */)
+
+If DISCARD-COMMENTS is non-nil, the top-level HTML comment is discarded.
+
+This parameter is obsolete as of 27.1, and you should use the
+`xml-remove-comments' function to strip comments before calling
+this function if you don't want comments.  */)
   (Lisp_Object start, Lisp_Object end, Lisp_Object base_url, Lisp_Object discard_comments)
 {
   if (init_libxml2_functions ())
@@ -284,7 +289,12 @@ DEFUN ("libxml-parse-xml-region", Flibxml_parse_xml_region,
        2, 4, 0,
        doc: /* Parse the region as an XML document and return the parse tree.
 If BASE-URL is non-nil, it is used to expand relative URLs.
-If DISCARD-COMMENTS is non-nil, all HTML comments are discarded. */)
+
+If DISCARD-COMMENTS is non-nil, the top-level XML comment is discarded.
+
+This parameter is obsolete as of 27.1, and you should use the
+`xml-remove-comments' function to strip comments before calling
+this function if you don't want comments.  */)
   (Lisp_Object start, Lisp_Object end, Lisp_Object base_url, Lisp_Object discard_comments)
 {
   if (init_libxml2_functions ())