basis/xml/writer/writer-docs.factor

   1 ! Copyright (C) 2005, 2009 Daniel Ehrenberg
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax io strings xml.data ;
   4 IN: xml.writer
   5
   6 ABOUT: "xml.writer"
   7
   8 ARTICLE: "xml.writer" "Writing XML"
   9 "These words are used to print XML preserving whitespace in text nodes"
  10 { $subsections
  11     write-xml
  12     xml>string
  13 }
  14 "These words are used to prettyprint XML"
  15 { $subsections
  16     pprint-xml>string
  17     pprint-xml
  18 }
  19 "Certain variables can be changed to manipulate prettyprinting"
  20 { $subsections
  21     sensitive-tags
  22     indenter
  23 }
  24 "All of these words operate on arbitrary pieces of XML: they can take, as in put, XML documents, comments, tags, strings (text nodes), XML chunks, etc." ;
  25
  26 HELP: xml>string
  27 { $values { "xml" "an XML document" } { "string" string } }
  28 { $description "This converts an XML document " { $link xml } " into a string. It can also be used to convert any piece of XML to a string, eg an " { $link xml-chunk } " or " { $link comment } "." }
  29 { $notes "This does not preserve what type of quotes were used or what data was omitted from version declaration, as that information isn't present in the XML data representation. The whitespace in the text nodes of the original document is preserved." } ;
  30
  31 HELP: pprint-xml>string
  32 { $values { "xml" "an XML document" } { "string" string } }
  33 { $description "Converts an XML document into a string in a prettyprinted form." }
  34 { $notes "This does not preserve what type of quotes were used or what data was omitted from version declaration, as that information isn't present in the XML data representation. The whitespace in the text nodes of the original document is preserved." } ;
  35
  36 HELP: write-xml
  37 { $values { "xml" "an XML document" } }
  38 { $description "Prints the contents of an XML document to " { $link output-stream } "." }
  39 { $notes "This does not preserve what type of quotes were used or what data was omitted from version declaration, as that information isn't present in the XML data representation. The whitespace in the text nodes of the original document is preserved." } ;
  40
  41 HELP: pprint-xml
  42 { $values { "xml" "an XML document" } }
  43 { $description "Prints the contents of an XML document to " { $link output-stream } " in a prettyprinted form." }
  44 { $notes "This does not preserve what type of quotes were used or what data was omitted from version declaration, as that information isn't present in the XML data representation. Whitespace is also not preserved." } ;
  45
  46 { xml>string write-xml pprint-xml pprint-xml>string } related-words
  47
  48 HELP: indenter
  49 { $var-description "Contains the string which is used for indenting in the XML prettyprinter. For example, to print an XML document using " { $snippet "%%%%" } " for indentation, you can use the following:" }
  50 { $example "USING: xml.syntax xml.writer namespaces ;
  51 [XML <foo>bar</foo> XML] \"%%%%\" indenter [ pprint-xml ] with-variable " "
  52 <foo>
  53 %%%%bar
  54 </foo>" } ;
  55
  56 HELP: sensitive-tags
  57 { $var-description "Contains a sequence of " { $link name } "s where whitespace should be considered significant for prettyprinting purposes. The sequence can contain " { $link string } "s in place of names. For example, to preserve whitespace inside a " { $snippet "pre" } " tag:" }
  58 { $example "USING: xml.syntax xml.writer namespaces ;
  59 [XML <!DOCTYPE html> <html> <head> <title> something</title></head><body><pre>bing
  60 bang
  61    bong</pre></body></html> XML] { \"pre\" } sensitive-tags [ pprint-xml ] with-variable"
  62 "
  63 <!DOCTYPE html>
  64 <html>
  65   <head>
  66     <title>
  67       something
  68     </title>
  69   </head>
  70   <body>
  71     <pre>bing
  72 bang
  73    bong</pre>
  74   </body>
  75 </html>" } ;