Document farkup

basis/farkup/farkup-docs.factor

@@ -1,6 +1,51 @@
-USING: help.markup help.syntax ;
+USING: help.markup help.syntax strings io ;
 IN: farkup
 
 HELP: convert-farkup
-{ $values { "string" "a string" } { "string'" "a string" } }
-{ $description "Parse a string as farkup (Factor mARKUP) and output the result aas an string of HTML." } ;
+{ $values { "string" string } { "string'" string } }
+{ $description "Parse a Farkup string and convert it to an HTML string." } ;
+
+HELP: write-farkup
+{ $values { "string" string } }
+{ $description "Parse a Farkup string and writes the resulting HTML to " { $link output-stream } "." } ;
+
+HELP: farkup ( string -- farkup )
+{ $values { "string" string } { "farkup" "a Farkup syntax tree node" } }
+{ $description "Parses Farkup and outputs a tree of " { $link "farkup-ast" } "." } ;
+
+HELP: (write-farkup)
+{ $values { "farkup" "a Farkup syntax tree node" } }
+{ $description "Writes a Farkup syntax tree as HTML on " { $link output-stream } "." } ;
+
+ARTICLE: "farkup-ast" "Farkup syntax tree nodes"
+"The " { $link farkup } " word outputs a tree of nodes corresponding to the Farkup syntax of the input string. This tree can be programatically traversed and mutated before being passed on to " { $link write-farkup } "."
+{ $subsection heading1 }
+{ $subsection heading2 }
+{ $subsection heading3 }
+{ $subsection heading4 }
+{ $subsection strong }
+{ $subsection emphasis }
+{ $subsection superscript }
+{ $subsection subscript }
+{ $subsection inline-code }
+{ $subsection paragraph }
+{ $subsection list-item }
+{ $subsection list }
+{ $subsection table }
+{ $subsection table-row }
+{ $subsection link }
+{ $subsection image }
+{ $subsection code } ;
+
+ARTICLE: "farkup" "Farkup"
+"The " { $vocab-link "farkup" } " vocabulary implements Farkup (Factor mARKUP), a simple markup language. Farkup was loosely based on the markup languages employed by MediaWiki and " { $url "http://reddit.com" } "."
+$nl
+"The main entry points for converting Farkup to HTML:"
+{ $subsection convert-farkup }
+{ $subsection write-farkup }
+"The syntax tree of a piece of Farkup can also be inspected and modified:"
+{ $subsection farkup }
+{ $subsection (write-farkup) }
+{ $subsection "farkup-ast" } ;
+
+ABOUT: "farkup"

basis/farkup/farkup.factor

@@ -155,32 +155,35 @@ stand-alone
         </pre>
     ] with-string-writer write ;
 
-GENERIC: write-farkup ( obj -- )
+GENERIC: (write-farkup) ( farkup -- )
 : <foo.> ( string -- ) <foo> write ;
 : </foo.> ( string -- ) </foo> write ;
 : in-tag. ( obj quot string -- ) [ <foo.> call ] keep </foo.> ; inline
-M: heading1 write-farkup ( obj -- ) [ obj>> write-farkup ] "h1" in-tag. ;
-M: heading2 write-farkup ( obj -- ) [ obj>> write-farkup ] "h2" in-tag. ;
-M: heading3 write-farkup ( obj -- ) [ obj>> write-farkup ] "h3" in-tag. ;
-M: heading4 write-farkup ( obj -- ) [ obj>> write-farkup ] "h4" in-tag. ;
-M: strong write-farkup ( obj -- ) [ obj>> write-farkup ] "strong" in-tag. ;
-M: emphasis write-farkup ( obj -- ) [ obj>> write-farkup ] "em" in-tag. ;
-M: superscript write-farkup ( obj -- ) [ obj>> write-farkup ] "sup" in-tag. ;
-M: subscript write-farkup ( obj -- ) [ obj>> write-farkup ] "sub" in-tag. ;
-M: inline-code write-farkup ( obj -- ) [ obj>> write-farkup ] "code" in-tag. ;
-M: list-item write-farkup ( obj -- ) [ obj>> write-farkup ] "li" in-tag. ;
-M: list write-farkup ( obj -- ) [ obj>> write-farkup ] "ul" in-tag. ;
-M: paragraph write-farkup ( obj -- ) [ obj>> write-farkup ] "p" in-tag. ;
-M: link write-farkup ( obj -- ) [ href>> ] [ text>> ] bi write-link ;
-M: image write-farkup ( obj -- ) [ href>> ] [ text>> ] bi write-image-link ;
-M: code write-farkup ( obj -- ) [ string>> ] [ mode>> ] bi render-code ;
-M: table-row write-farkup ( obj -- )
-    obj>> [ [ [ write-farkup ] "td" in-tag. ] each ] "tr" in-tag. ;
-M: table write-farkup ( obj -- ) [ obj>> write-farkup ] "table" in-tag. ;
-M: fixnum write-farkup ( obj -- ) write1 ;
-M: string write-farkup ( obj -- ) write ;
-M: vector write-farkup ( obj -- ) [ write-farkup ] each ;
-M: f write-farkup ( obj -- ) drop ;
+M: heading1 (write-farkup) ( obj -- ) [ obj>> (write-farkup) ] "h1" in-tag. ;
+M: heading2 (write-farkup) ( obj -- ) [ obj>> (write-farkup) ] "h2" in-tag. ;
+M: heading3 (write-farkup) ( obj -- ) [ obj>> (write-farkup) ] "h3" in-tag. ;
+M: heading4 (write-farkup) ( obj -- ) [ obj>> (write-farkup) ] "h4" in-tag. ;
+M: strong (write-farkup) ( obj -- ) [ obj>> (write-farkup) ] "strong" in-tag. ;
+M: emphasis (write-farkup) ( obj -- ) [ obj>> (write-farkup) ] "em" in-tag. ;
+M: superscript (write-farkup) ( obj -- ) [ obj>> (write-farkup) ] "sup" in-tag. ;
+M: subscript (write-farkup) ( obj -- ) [ obj>> (write-farkup) ] "sub" in-tag. ;
+M: inline-code (write-farkup) ( obj -- ) [ obj>> (write-farkup) ] "code" in-tag. ;
+M: list-item (write-farkup) ( obj -- ) [ obj>> (write-farkup) ] "li" in-tag. ;
+M: list (write-farkup) ( obj -- ) [ obj>> (write-farkup) ] "ul" in-tag. ;
+M: paragraph (write-farkup) ( obj -- ) [ obj>> (write-farkup) ] "p" in-tag. ;
+M: link (write-farkup) ( obj -- ) [ href>> ] [ text>> ] bi write-link ;
+M: image (write-farkup) ( obj -- ) [ href>> ] [ text>> ] bi write-image-link ;
+M: code (write-farkup) ( obj -- ) [ string>> ] [ mode>> ] bi render-code ;
+M: table-row (write-farkup) ( obj -- )
+    obj>> [ [ [ (write-farkup) ] "td" in-tag. ] each ] "tr" in-tag. ;
+M: table (write-farkup) ( obj -- ) [ obj>> (write-farkup) ] "table" in-tag. ;
+M: fixnum (write-farkup) ( obj -- ) write1 ;
+M: string (write-farkup) ( obj -- ) write ;
+M: vector (write-farkup) ( obj -- ) [ (write-farkup) ] each ;
+M: f (write-farkup) ( obj -- ) drop ;
+
+: write-farkup ( string -- )
+    farkup (write-farkup) ;
 
 : convert-farkup ( string -- string' )
-    farkup [ write-farkup ] with-string-writer ;
+    farkup [ (write-farkup) ] with-string-writer ;