From dcba0a55dfb99f28bb079b895b0d67a2b36602b3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= <hugo@lysator.liu.se>
Date: Tue, 17 Oct 2023 15:50:23 +0200
Subject: Document sxml namespaced utils.

---
 doc/ref/general/sxml.texi | 54 +++++++++++++++++++++++++++++++++++++++++++++++
 doc/ref/webdav.texi       |  9 --------
 2 files changed, 54 insertions(+), 9 deletions(-)

diff --git a/doc/ref/general/sxml.texi b/doc/ref/general/sxml.texi
index dd635b4c..0b77afc8 100644
--- a/doc/ref/general/sxml.texi
+++ b/doc/ref/general/sxml.texi
@@ -17,6 +17,9 @@ Would be represented as
    "Content"))
 @end example
 
+In this document a list with an XML tag object in its car is sometimes
+refered to as an XML node.
+
 @defun namespaced-sxml->sxml tree [namespace-prefixes='()]
 Takes a tree of namespaced-sxml, and optionally an assoc list from
 namespace symbols, to prefered prefix.
@@ -98,3 +101,54 @@ namespace.
        @defun pi-body pi
        @end defun
 @end defun
+
+@section Namespaced SXML utilities
+
+Provided by the module @code{(sxml namespaced util)}.
+
+@defun xml-element-hash-key xml-tag
+Given an xml tag object @ref{xml-tag}, return a suitable key for
+@code{hash-ref} and family.
+
+These key objects should preferably not be carried around for
+long. Prefer to keep the @emph{real} xml-tag object, and only call
+this while directly referencing the hash table.
+@end defun
+
+@defun find-element target list
+@var{list} should be an element of XML nodes, and @var{target} an XML
+element object.
+
+Returns the first element of @var{list} which matches the tagname and
+namespace of @var{target}.
+@end defun
+
+@defun element-matches? element node
+Checks that the bare element @var{element} has the same tagname and
+namespaces as the begining tag of @var{node}.
+@end defun
+
+@defun on-root-element proc tree
+Apply proc to the root element of the tree. The root elemnet here is
+assumed to be the topmost ``regular'' xml component.
+
+For example, the tree
+@example
+<?doctype example?>
+<a/>
+@end example
+
+Would serialize as
+@example
+'(*TOP* (*PI* doctype "example")
+        (a))
+@end example
+
+This procedure would apply @var{proc} to @code{(a)}, and return the
+form generated by replacing @code{(a)} with the return value of
+@var{proc}.
+@end defun
+
+@defun root-element
+Extract the root element of a namespaced sxml tree.
+@end defun
diff --git a/doc/ref/webdav.texi b/doc/ref/webdav.texi
index cc361e71..a6593b93 100644
--- a/doc/ref/webdav.texi
+++ b/doc/ref/webdav.texi
@@ -282,15 +282,6 @@ used Guile's current encoding will be used.
 
 @node WebDAV Utilities
 @section Utilities
-@defun xml-element-hash-key xml-tag
-Given an xml tag object @ref{xml-tag}, return a suitable key for
-@code{hash-ref} and family.
-
-These key objects should preferably not be carried around for
-long. Prefer to keep the @emph{real} xml-tag object, and only call
-this while directly referencing the hash table.
-@end defun
-
 @defun href->string href
 HREF's are represented as lists of strings. The root resource (``/'')
 is the empty list.
-- 
cgit v1.2.3