(index ("serialize-sxml" 0) ("conventional-ns-prefixes" 2336) ("allow-prefix-redeclarations?" 2769))
(def (sig (procedure "(serialize-sxml doc #!key keys)" (id serialize-sxml))) (p "Serialize the SXML document " (tt "DOC") ", an SXML node or nodeset, to XML or HTML.  Returns the result string if the serialization was done to a string, or an unspecified value if serializing to file or port.") (p (tt "serialize-sxml") " accepts the following keyword arguments:") (dl (dt "output") (dd "[default " (tt "#f") "] An output port or filename to write the output to, or " (tt "#f") " to write it to a string.") (dt "cdata-section-elements") (dd "[default " (tt "'()") "] A list of SXML element names, as symbols, which will have their contents serialized to CDATA.") (dt "indent") (dd "[default, two spaces] Indentation level to apply to XML elements, as a string or " (tt "#f") ".  When a string, a newline is written when a new tag is opened, and the tag is indented by printing the string " (i "x") " times for indentation level " (i "x") ".  When " (tt "#f") ", indentation is totally disabled and no newline is printed.  To print all tags left-aligned, use the empty string.") (dt "method") (dd "[default " (tt "'xml") "] Serialization method, " (tt "'xml") " or " (tt "'html") ".  When " (tt "'html") ", an end-tag is not output for empty HTML elements; character escaping is not performed for the content of script and style elements; \"<\" characters in attribute values are not escaped; whitespace is not added inside a formatted element; and boolean attributes are output in minimized form.  HTML output is provided for completeness; using " (int-link "sxml-transforms") " may give better results.") (dt "ns-prefixes") (dd "[default " (tt "conventional-ns-prefixes") "] An alist mapping namespace prefixes (symbols) to URIs, which allows the application to specify the mapping between namespace URIs and the corresponding namespace prefixes to be used for serialization.  When no namespace prefix assignment is provided for some namespace URI, the serializer generates an XML prefix name by itself.  This URI to prefix map is applied after any user shortcuts are expanded to full URIs.") (dt "allow-prefix-redeclarations") (dd "[default: value of " (tt "allow-prefix-redeclarations?") " param] Permit different URIs to map to the same XML prefix.  See the " (int-link "#Redeclaring XML prefixes" "section on redeclaration") ".")))
(def (sig (constant "conventional-ns-prefixes" (id conventional-ns-prefixes))) (p "An alist mapping well-known namespace prefixes to URIs.  Typically used when augmenting the serializer's existing namespace map:") (highlight scheme ";; translate namespace URI http://3e8.org/zb to the XML prefix zb:\n(serialize-sxml doc ns-prefixes: `((zb . \"http://3e8.org/zb\")\n                                   ,@conventional-ns-prefixes))"))
(def (sig (parameter "(allow-prefix-redeclarations? #t)" (id allow-prefix-redeclarations?))) (p "This parameter determines the default value of the " (tt "allow-prefix-redeclarations:") " keyword to " (tt "serialize-sxml") ".") (p "If " (tt "#t") ", allows redeclaration of XML prefixes when a namespace URI maps to a previously declared XML prefix; if " (tt "#f") ", a new prefix will be autogenerated so that XML prefixes map one-to-one to URIs. Defaults to " (tt "#t") ".  The behavior of the stock " (tt "sxml-tools") " serializer is to avoid all prefix redeclarations; to retain this behavior, set this value to " (tt "#f") ".") (p "When enabled, you can provide multiple identical prefixes in " (tt "ns-prefixes") ", mapped to different URIs.  The serializer will redeclare the prefix with a different namespace URI if it has already been declared in a parent:") (pre "> (serialize-sxml '((*TOP* (http://foo:one (http://bar:two))\n                           (http://bar:three)))\n                  ns-prefixes: '((BAZ . \"http://foo\") (BAZ . \"http://bar\")))\n<BAZ:one xmlns:BAZ=\"http://foo\">\n  <BAZ:two xmlns:BAZ=\"http://bar\" />\n</BAZ:one>\n<BAZ:three xmlns:BAZ=\"http://bar\" />") (p "Contrast this to the case where redeclarations are disallowed:") (pre "> (serialize-sxml '((*TOP* (http://foo:one (http://bar:two))\n                           (http://bar:three)))\n                  ns-prefixes: '((BAZ . \"http://foo\") (BAZ . \"http://bar\"))\n                  allow-prefix-redeclarations: #f)\n<BAZ:one xmlns:BAZ=\"http://foo\">\n  <prfx1:two xmlns:prfx1=\"http://bar\" />   <!-- ooooh -->\n</BAZ:one>\n<BAZ:three xmlns:BAZ=\"http://bar\" />") (p "Here the nested element " (tt "http://bar:two") " had its XML prefix " (tt "prfx1") " auto-generated, because " (tt "BAZ") " had already been declared in the enclosing scope.  Notice that " (tt "http://bar:three") " still becomes " (tt "BAZ:three") " though, because BAZ was " (i "not") " declared in " (i "that") " element's enclosing scope.") (p "This is extremely useful when the default namespace is employed, because you can declare multiple default namespace URIs, and switch back and forth between the empty namespace and a default namespace.  You can consider the default namespace to be a dedicated prefix called " (tt "*default*") " which happens to render into XML without a prefix.") (pre "(serialize-sxml\n  '(*TOP* (http://foo:one\n            (http://bar:two\n              (http://bar:three)\n              (http://foo:four)\n              (five (six (http://foo:seven))))))\n   ns-prefixes: '((*default* . \"http://foo\") (*default* . \"http://bar\")))") (pre "<!-- redeclarations #t -->          <!-- redeclarations #f -->\n<one xmlns=\"http://foo\">            <one xmlns=\"http://foo\">\n  <two xmlns=\"http://bar\">            <prfx1:two xmlns:prfx1=\"http://bar\">\n    <three />                           <prfx1:three />\n    <four xmlns=\"http://foo\" />         <four />\n    <five xmlns=\"\">                     <five xmlns=\"\">\n      <six>                               <six>\n        <seven xmlns=\"http://foo\" />        <prfx2:seven xmlns:prfx2=\"http://foo\" />\n      </six>                              </six>\n    </five>                             </five>\n  </two>                              </prfx1:two>\n</one>                              </one>") (p "One thing to note is that the empty namespace can always be redeclared to be the default namespace, despite the value of " (tt "allow-prefix-redeclarations?") ".  That's because in XML it is illegal to associate the empty namespace with an XML prefix, so we cannot auto-generate a prefix for it."))
