[Emacs-diffs] master 97d6e7e: * text.texi (Document Object Model): New node to document dom.el.

[Lars Ingebrigtsen]

branch: master
commit 97d6e7e71182a421050601db662ee95c5b2cc172
Author: Lars Magne Ingebrigtsen <address@hidden>
Date:   Wed Nov 26 20:23:06 2014 +0100

    * text.texi (Document Object Model): New node to document dom.el.
---
 doc/lispref/ChangeLog |    4 ++
 doc/lispref/text.texi |  120 ++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 123 insertions(+), 1 deletions(-)

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index b0da266..37f16a1 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,7 @@
+2014-11-26  Lars Magne Ingebrigtsen  <address@hidden>
+
+       * text.texi (Document Object Model): New node to document dom.el.
+
 2014-11-24  Lars Magne Ingebrigtsen  <address@hidden>
 
        * processes.texi (Network Security): Made into its own section and
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 7c88a5b..2280a8e 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -4349,7 +4349,8 @@ document:
 @end example
 
 @noindent
-A call to @code{libxml-parse-html-region} returns this:
+A call to @code{libxml-parse-html-region} returns this @acronym{DOM}
+(document object model):
 
 @example
 (html ()
@@ -4377,6 +4378,123 @@ that it parses the text as XML rather than HTML (so it 
is stricter
 about syntax).
 @end defun
 
address@hidden
+* Document Object Model:: Access, manipulate and search the @acronym{DOM}.
address@hidden menu
+
address@hidden Document Object Model
address@hidden Document Object Model
address@hidden HTML DOM
address@hidden XML DOM
address@hidden DOM
address@hidden Document Object Model
+
+The @acronym{DOM} returned by @code{libxml-parse-html-region} (and the
+other @acronym{XML} parsing functions) is a tree structure where each
+node has a node name (called a @dfn{tag}), and optional key/value
address@hidden list, and then a list of @dfn{child nodes}.  The child
+nodes are either strings or @acronym{DOM} objects.
+
address@hidden
+(body
+ ((width . "101"))
+ (div
+  ((class . "thing"))
+  "Foo"
+  (div
+   nil
+   "Yes")))
address@hidden example
+
address@hidden dom-node tag &optional attributes &rest children
+This function creates a @acronym{DOM} node of type @var{tag}.  If
+given, @var{attributes} should be a key/value pair list.
+If given, @var{children} should be @acronym{DOM} nodes.
address@hidden defun
+
+The following functions can be used to work with this structure.  Each
+function takes a @acronym{DOM} node, or a list of nodes.  In the
+latter case, only the first node in the list is used.
+
+Simple accessors:
+
address@hidden @code
address@hidden dom-tag @var{node}
+Return the @dfn{tag} (also called ``node name'') of the node.
+
address@hidden dom-attr @var{node} @var{attributes}
+Return the value of @var{attributes} in the node.  A common usage
+would be:
+
address@hidden
+(dom-attr img 'href)
+=> "http://fsf.org/logo.png";
address@hidden lisp
+
address@hidden dom-children @var{node}
+Return all the children of the node.
+
address@hidden dom-attributes @var{node}
+Return the key/value pair list of attributes of the node.
+
address@hidden dom-text @var{node}
+Return all the textual elements of the node as a concatenated string.
+
address@hidden dom-texts @var{node}
+Return all the textual elements of the node, as well as the textual
+elements of all the children of the node, recursively, as a
+concatenated string.  This function also takes an optional separator
+to be inserted between the textual elements.
+
address@hidden dom-parent @var{dom} @var{node}
+Return the parent of @var{node} in @var{dom}.
address@hidden table
+
+The following are functions for altering the @acronym{DOM}.
+
address@hidden @code
address@hidden dom-set-attribute @var{node} @var{attribute} @var{value}
+Set the @var{attribute} of the node to @var{value}.
+
address@hidden dom-append-child @var{node} @var{child}
+Append @var{child} as the last child of @var{node}.
+
address@hidden dom-add-child-before @var{node} @var{child} @var{before}
+Add @var{child} to @var{node}'s child list before the @var{before}
+node.  If @var{before} is nil, make @var{child} the first child.
+
address@hidden dom-set-attributes @var{node} @var{attributes}
+Replace all the attributes of the node with a new key/value list.
address@hidden table
+
+The following are functions for searching for elements in the
address@hidden  They all return lists of matching nodes.
+
address@hidden @code
address@hidden dom-by-tag @var{dom} @var{tag}
+Return all nodes in @var{dom} that are of type @var{tag}.  A typical
+use would be:
+
address@hidden
+(dom-by-tag dom 'td)
+=> '((td ...) (td ...) (td ...))
address@hidden lisp
+
address@hidden dom-by-class @var{dom} @var{match}
+Return all nodes in @var{dom} that have class names that match
address@hidden, which is a regular expression.
+
address@hidden dom-by-style @var{dom} @var{style}
+Return all nodes in @var{dom} that have styles that match @var{match},
+which is a regular expression.
+
address@hidden dom-by-id @var{dom} @var{style}
+Return all nodes in @var{dom} that have IDs that match @var{match},
+which is a regular expression.
+
address@hidden table
+
+
 @node Atomic Changes
 @section Atomic Change Groups
 @cindex atomic changes