[Emacs-diffs] master e20d738: Make DISCARD-COMMENTS in `libxml-parse-{html, xml}-region' obsolete

[Lars Ingebrigtsen]

branch: master
commit e20d7381ee85611f9e1d1e6bef4fe2d7e2ae7780
Author: Lars Ingebrigtsen <address@hidden>
Commit: Lars Ingebrigtsen <address@hidden>

    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.
---
 doc/lispref/text.texi |  5 ++++-
 etc/NEWS              |  8 ++++++++
 lisp/xml.el           | 13 +++++++++++++
 src/xml.c             | 14 ++++++++++++--
 4 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 9769043..e89bd0b 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -4724,7 +4724,10 @@ The optional argument @var{base-url}, if address@hidden, 
should be a
 string specifying the base URL for relative URLs occurring in links.
 
 If the optional argument @var{discard-comments} is address@hidden,
-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
address@hidden 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
diff --git a/etc/NEWS b/etc/NEWS
index 980a5b4..0bf5ba8 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.
diff --git a/lisp/xml.el b/lisp/xml.el
index 3bc8c08..6ce944c 100644
--- a/lisp/xml.el
+++ b/lisp/xml.el
@@ -1073,6 +1073,19 @@ The first line is indented with INDENT-STRING."
        (insert ?\n indent-string))
       (insert ?< ?/ (symbol-name (xml-node-name xml)) ?>))))
 
+;;;###autoload
+(defun xml-remove-comments (beg end)
+  "Remove XML/HTML comments in the region between BEG and END.
+All text between the <!-- ... --> markers will be removed."
+  (save-excursion
+    (save-restriction
+      (narrow-to-region beg end)
+      (goto-char beg)
+      (while (search-forward "<!--" nil t)
+        (let ((start (match-beginning 0)))
+          (when (search-forward "-->" nil t)
+            (delete-region start (point))))))))
+
 (provide 'xml)
 
 ;;; xml.el ends here
diff --git a/src/xml.c b/src/xml.c
index 42059d7..fa88040 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 ())