more help docs

library/io/server.facts

@@ -1,3 +1,5 @@
+USING: help io ;
+
 HELP: log-stream f
 { $description "Variable. Holds an output stream for logging messages." }
 { $see-also log-error log-client with-log-file with-logging } ;

library/io/stdio.factor

@@ -27,29 +27,24 @@ SYMBOL: stdio
 : print ( string -- ) stdio get stream-print ;
 
 : with-stream ( stream quot -- )
-    #! Close the stream no matter what happens.
     [ swap stdio set [ close ] cleanup ] with-scope ; inline
 
 : with-stream* ( stream quot -- )
-    #! Close the stream if there is an error.
     [ swap stdio set [ close rethrow ] recover ] with-scope ;
     inline
 
 SYMBOL: style-stack
 
 : >style ( style -- )
-    #! Push a style on the style stack.
     dup hashtable? [ "Style must be a hashtable" throw ] unless
     style-stack [ ?push ] change ;
 
-: style> ( -- style )
-    style-stack get pop ;
+: style> ( -- style ) style-stack get pop ;
 
 : with-style ( style quot -- )
     [ >r >style r> call style> drop ] with-scope ; inline
 
 : current-style ( -- style )
-    #! Always returns a fresh hashtable.
     style-stack get hash-concat ;
 
 : format* ( string -- ) current-style format ;
@@ -63,7 +58,6 @@ SYMBOL: style-stack
     >r presented associate r> with-style ;
 
 : simple-object ( string object -- )
-    #! Writes a clickable presentation with the specified string.
     [ format* ] write-object ;
 
 : write-outliner ( content caption -- )

library/io/stdio.facts

@@ -1,3 +1,5 @@
+USING: help io ;
+
 HELP: stdio f
 { $description "Variable. Holds a stream, used for various implicit stream operations. Rebound using " { $link with-stream } " and " { $link with-stream* } "." } ;
 
@@ -55,7 +57,7 @@ $io-error ;
 
 HELP: with-nesting "( style quot -- )"
 { $values { "style" "a hashtable" } { "quot" "a quotation" } }
-{ $contract "Calls the quotation in a new dynamic scope, where the " { $link stdio } " stream is rebound to a nested stream of the current " { $link stdio } " stream, with formatting information applied." }
+{ $contract "Calls the quotation in a new dynamic scope with the " { $link stdio } " stream rebound to a nested paragraph stream, with formatting information applied." }
 { $notes "Details are in the documentation for " { $link stream-format } "." }
 $io-error ;
 
@@ -63,3 +65,65 @@ HELP: print "( style quot -- )"
 { $values { "style" "a hashtable" } { "quot" "a quotation" } }
 { $description "Outputs a newline-terminated string to the " { $link stdio } " stream." }
 $io-error ;
+
+HELP: with-stream "( stream quot -- )"
+{ $values { "stream" "an input or output stream" } { "quot" "a quotation" } }
+{ $description "Calls the quotation in a new dynamic scope, with the " { $link stdio } " variable rebound to  " { $snippet "stream" } ". The stream is closed if the quotation returns or throws an error." } 
+{ $see-also with-stream* } ;
+
+HELP: with-stream* "( stream quot -- )"
+{ $values { "stream" "an input or output stream" } { "quot" "a quotation" } }
+{ $description "Calls the quotation in a new dynamic scope, with the " { $link stdio } " variable rebound to  " { $snippet "stream" } ". The stream is closed if the quotation throws an error, however it is " { $emphasis "not" } " closed if the quotation returns without incident." }
+{ $see-also with-stream } ;
+
+HELP: style-stack f
+{ $description "Variable. Holds a vector of hashtables." }
+{ $see-also with-style format* } ;
+
+HELP: with-style "( style quot -- )"
+{ $values { "style" "a hashtable" } { "quot" "a quotation" } }
+{ $description "Pushes a style on the style stack, and calls the quotation." }
+{ $see-also format* with-nesting* } ;
+
+HELP: current-style "( -- style )"
+{ $values { "style" "a hashtable" } }
+{ $description "Creates a new hashtable by concatenating all styles on the style stack, with keys in more recently pushed styles taking precedence." }
+{ $see-also format* with-nesting* } ;
+
+HELP: format* "( str -- )"
+{ $values { "str" "a string" } }
+{ $description "Writes formatted text to the " { $link stdio } " stream using the current style." }
+{ $see-also current-style } 
+$io-error ;
+
+HELP: bl "( -- )"
+{ $description "Writes a word break to the " { $link stdio } " stream using the current style." }
+{ $notes "This word is useful even when not doing formatting. If " { $link stdio } " is a plain text stream, it simply outputs a space." }
+{ $see-also current-style } 
+$io-error ;
+
+HELP: with-nesting* "( style quot -- )"
+{ $values { "style" "a hashtable" } { "quot" "a quotation" } }
+{ $description "Calls the quotation in a new dynamic scope with the " { $link stdio } " stream rebound to a nested paragraph stream with the current style." }
+$io-error
+{ $see-also current-style } ;
+
+HELP: write-object "( obj quot -- )"
+{ $values { "obj" "an object" } { "quot" "a quotation" } }
+{ $description "Pushes a style on the style stack associating all output with the object, and calls the quotation. If the " { $link stdio } " stream supports it, any text output by the quotation will become a clickable presentation of the object." }
+$io-error ;
+
+HELP: simple-object "( str obj -- )"
+{ $values { "str" "a string" } { "obj" "an object" } }
+{ $description "Writes a string to the " { $link stdio } " stream, associating it with the object. If formatted output is supported, the string will become a clickable presentation of the object, otherwise this word behaves like a call to " { $link write } "." }
+$io-error ;
+
+HELP: write-outliner "( content caption -- )"
+{ $values { "content" "a quotation" } { "caption" "a quotation" } }
+{ $description "Writes an outliner to the " { $link stdio } " stream. The " { $snippet "caption" } " quotation is called to produce a label for an outliner. Expanding the outliner calls " { $snippet "content" } " in a new dynamic scope with " { $link stdio } " rebound to the body of the outliner. If the stream does not support formatted output, this simply calls " { $snippet "caption" } " and ignores " { $snippet "content" } "." }
+$io-error ;
+
+HELP: simple-outliner "( str obj content -- )"
+{ $values { "str" "a string" } { "obj" "an object" } { "content" "a quotation" } }
+{ $description "Writes an outliner to the " { $link stdio } " stream. The outliner's caption is a the string " { $snippet "str" } " with an associated presentation of " { $snippet "obj" } ". Expanding the outliner calls " { $snippet "content" } " in a new dynamic scope with " { $link stdio } " rebound to the body of the outliner. If the stream does not support formatted output, this simply writes " { $snippet "str" } " and ignores everything else." }
+$io-error ;