! Copyright (C) 2005, 2009 Daniel Ehrenberg
! See http://factorcode.org/license.txt for BSD license.
-USING: help.syntax help.markup io strings ;
+USING: help.markup help.syntax io strings xml.data ;
IN: xml.writer
ABOUT: "xml.writer"
ARTICLE: "xml.writer" "Writing XML"
- "These words are used in implementing prettyprint"
- { $subsection write-xml-chunk }
- "These words are used to print XML normally"
- { $subsection xml>string }
- { $subsection write-xml }
- { $subsection print-xml }
- "These words are used to prettyprint XML"
- { $subsection pprint-xml>string }
- { $subsection pprint-xml>string-but }
- { $subsection pprint-xml }
- { $subsection pprint-xml-but } ;
-
-HELP: write-xml-chunk
-{ $values { "object" "an XML element" } }
-{ $description "writes an XML element to " { $link output-stream } "." }
-{ $see-also write-xml-chunk write-xml } ;
+"These words are used to print XML preserving whitespace in text nodes"
+{ $subsections
+ write-xml
+ xml>string
+}
+"These words are used to prettyprint XML"
+{ $subsections
+ pprint-xml>string
+ pprint-xml
+}
+"Certain variables can be changed to manipulate prettyprinting"
+{ $subsections
+ sensitive-tags
+ indenter
+}
+"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." ;
HELP: xml>string
-{ $values { "xml" "an xml document" } { "string" "a string" } }
-{ $description "converts an XML document into a string" }
-{ $notes "does not preserve what type of quotes were used or what data was omitted from version declaration" } ;
+{ $values { "xml" "an XML document" } { "string" string } }
+{ $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 } "." }
+{ $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." } ;
HELP: pprint-xml>string
-{ $values { "xml" "an xml document" } { "string" "a string" } }
-{ $description "converts an XML document into a string in a prettyprinted form." }
-{ $notes "does not preserve what type of quotes were used or what data was omitted from version declaration" } ;
+{ $values { "xml" "an XML document" } { "string" string } }
+{ $description "Converts an XML document into a string in a prettyprinted form." }
+{ $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." } ;
HELP: write-xml
{ $values { "xml" "an XML document" } }
-{ $description "prints the contents of an XML document to " { $link output-stream } "." }
-{ $notes "does not preserve what type of quotes were used or what data was omitted from version declaration" } ;
-
-HELP: print-xml
-{ $values { "xml" "an XML document" } }
-{ $description "prints the contents of an XML document to " { $link output-stream } ", followed by a newline" }
-{ $notes "does not preserve what type of quotes were used or what data was omitted from version declaration" } ;
+{ $description "Prints the contents of an XML document to " { $link output-stream } "." }
+{ $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." } ;
HELP: pprint-xml
{ $values { "xml" "an XML document" } }
-{ $description "prints the contents of an XML document to " { $link output-stream } " in a prettyprinted form." }
-{ $notes "does not preserve what type of quotes were used or what data was omitted from version declaration" } ;
-
-HELP: pprint-xml-but
-{ $values { "xml" "an XML document" } { "sensitive-tags" "a sequence of names" } }
-{ $description "Prettyprints an XML document, leaving the whitespace of the tags with names in sensitive-tags intact." }
-{ $notes "does not preserve what type of quotes were used or what data was omitted from version declaration" } ;
+{ $description "Prints the contents of an XML document to " { $link output-stream } " in a prettyprinted form." }
+{ $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." } ;
-HELP: pprint-xml>string-but
-{ $values { "xml" "an XML document" } { "sensitive-tags" "a sequence of names" } { "string" string } }
-{ $description "Prettyprints an XML document, returning the result as a string and leaving the whitespace of the tags with names in sensitive-tags intact." }
-{ $notes "does not preserve what type of quotes were used or what data was omitted from version declaration" } ;
+{ xml>string write-xml pprint-xml pprint-xml>string } related-words
-{ xml>string print-xml write-xml pprint-xml pprint-xml>string pprint-xml>string-but pprint-xml-but } related-words
+HELP: indenter
+{ $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:" }
+{ $example "USING: xml.syntax xml.writer namespaces ;
+[XML <foo>bar</foo> XML] \"%%%%\" indenter [ pprint-xml ] with-variable " "
+<foo>
+%%%%bar
+</foo>" } ;
+HELP: sensitive-tags
+{ $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:" }
+{ $example "USING: xml.syntax xml.writer namespaces ;
+[XML <!DOCTYPE html> <html> <head> <title> something</title></head><body><pre>bing
+bang
+ bong</pre></body></html> XML] { \"pre\" } sensitive-tags [ pprint-xml ] with-variable"
+"
+<!DOCTYPE html>
+<html>
+ <head>
+ <title>
+ something
+ </title>
+ </head>
+ <body>
+ <pre>bing
+bang
+ bong</pre>
+ </body>
+</html>" } ;
projects / factor.git / blobdiff