xml.writer-docs: update the documentation wording and formatting

diff --git a/basis/xml/writer/writer-docs.factor b/basis/xml/writer/writer-docs.factor
index 8a165205e0d5ba8d2fc917a9e5a1ffa7a1c6e4c3..23c30e324c7cb92c44a5ffac98bbe5ceabf4b1fd 100644 (file)
--- a/basis/xml/writer/writer-docs.factor
+++ b/basis/xml/writer/writer-docs.factor
@@ -6,47 +6,50 @@ IN: xml.writer
 ABOUT: "xml.writer"
 
 ARTICLE: "xml.writer" "Writing XML"
-"These words are used to print XML preserving whitespace in text nodes"
+"These words are used to print XML preserving whitespace in text nodes:"
 { $subsections
     write-xml
     xml>string
 }
-"These words are used to prettyprint XML"
+"These words are used to prettyprint XML:"
 { $subsections
     pprint-xml>string
     pprint-xml
 }
-"Certain variables can be changed to manipulate prettyprinting"
+"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." ;
+"All of these words operate on arbitrary pieces of XML: they can take as input XML documents, comments, tags, strings (text nodes), XML chunks, etc." ;
 
 HELP: xml>string
-{ $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 } "." }
+{ $values { "xml" xml } { "string" string } }
+{ $description "This converts an XML document " { $snippet "xml" } " into a "
+{ $link 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" string } }
-{ $description "Converts an XML document into a string in a prettyprinted form." }
+{ $values { "xml" xml } { "string" string } }
+{ $description "Converts an XML document into a " { $link 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 } "." }
+{ $values { "xml" xml } }
+{ $description "Prints the contents of the 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." }
+{ $values { "xml" xml } }
+{ $description "Prints the contents of the XML document to the "
+{ $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." } ;
 
 { xml>string write-xml pprint-xml pprint-xml>string } 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:" }
+{ $var-description "Contains the string used for indentation in the XML prettyprinter. For example, to print an XML document using " { $snippet "%%%%" } " for indentation, you can do the following:" }
 { $example "USING: xml.syntax xml.writer namespaces ;
 [XML <foo>bar</foo> XML] \"%%%%\" indenter [ pprint-xml ] with-variable " "
 <foo>