Fix typos, documentation conventions

TODO.FACTOR.txt

@@ -36,9 +36,7 @@
     - fix remaining HTML stream issues
     - need to present $list in a useful way
   - better line spacing in ui and html - related issue
-
-+ tabular formatting in UI
-  - other help aspects
+- fix word wrap with tables in panes
 
 + fix compiled gc check
   - there was a performance hit, investigate
@@ -55,7 +53,6 @@
 - document that can <void*> only be called with an alien
 - help search
 - automatically update help graph when adding/removing articles/words
-- document conventions
 
 + ui:
 

doc/handbook/alien.facts

@@ -1,4 +1,5 @@
 USING: alien arrays help libc math ;
+
 ARTICLE: "alien" "C library interface"
 "Factor can directly call C functions in native libraries. It is also possible to compile callbacks which run Factor code, and pass them to native libraries as function pointers."
 $terpri
@@ -57,7 +58,6 @@ $terpri
 { $subsection "c-structs" }
 { $subsection "c-unions" } ;
 
-
 ARTICLE: "c-types-numeric" "Integer and floating point C types"
 "The following numerical types are available; a " { $snippet "u" } " prefix denotes an unsigned type:"
 { $table
@@ -69,9 +69,9 @@ ARTICLE: "c-types-numeric" "Integer and floating point C types"
     { { $snippet "int" } "always 4 bytes" }
     { $snippet "uint" }
     { { $snippet "long" } { "same size as CPU word size and " { $snippet "void*" } ", except on 64-bit Windows, where it is 4 bytes" } }
-    { { $snippet "ulong" } { }
+    { { $snippet "ulong" } { } }
     { { $snippet "longlong" } "always 8 bytes" }
-    { { $snippet "ulonglong" } { }
+    { { $snippet "ulonglong" } { } }
     { { $snippet "float" } { } }
     { { $snippet "double" } "same format as " { $link float } " objects" }
 }

doc/handbook/conventions.facts

@@ -0,0 +1,34 @@
+USING: arrays gadgets hashtables help io kernel-internals
+namespaces sequences ;
+
+ARTICLE: "conventions" "Conventions"
+"Various conventions are used throughout the Factor documentation and source code."
+{ $heading "Stack effect conventions" }
+"A stack effect comment lists word inputs and outputs, separated by " { $snippet "--" } ". Stack elements are ordered so that the top of the stack is on the right side. Each value can be named by a data type or description. The following are some examples of value names:"
+{ $table
+    { { { $snippet "?" } } "a boolean" }
+    { { { $snippet "elt" } } "an object which is an element of a sequence" }
+    { { { $snippet "m" } ", " { $snippet "n" } } "an integer" }
+    { { { $snippet "obj" } } "an object" }
+    { { { $snippet "quot" } } "a quotation" }
+    { { { $snippet "seq" } } "a sequence" }
+    { { { $snippet "str" } } "a string" }
+    { { { $snippet "x" } ", " { $snippet "y" } ", " { $snippet "z" } } "a number" }
+    { { { $snippet "{ " { $emphasis "a b c" } " }" } } "an array with specific length and elements" }
+}
+{ $heading "Word naming conventions" }
+"These conventions are not hard and fast, but are usually a good first step in understanding a word's behavior:"
+{ $table
+    { "General form" "Description" "Examples" }
+    { { $snippet { $emphasis "foo" } "?" } "outputs a boolean" { { $link empty? } } }
+    { { $snippet "?" { $emphasis "foo" } } { "conditionally performs " { $snippet { $emphasis "foo" } } } { { $links ?nth ?hash } } }
+    { { $snippet "<" { $emphasis "foo" } ">" } { "creates a new " { $snippet "foo" } } { { $link <array> } } }
+    { { $snippet { $emphasis "foo" } "*" } { "alternative form of " { $snippet "foo" } ", or a generic word called by " { $snippet "foo" } } { { $links hash* draw-gadget* } } }
+    { { $snippet "(" { $emphasis "foo" } ")" } { "implementation detail word used by " { $snippet "foo" } } { { $link (clone) } } }
+    { { $snippet "n" { $emphasis "foo" } } { "(sequence words only) performs " { $snippet "foo" } " but modifies an input sequence instead of creating a new sequence" } { { $links nappend nsort } } }
+    { { $snippet "set-" { $emphasis "foo" } } { "sets " { $snippet "foo" } " to a new value" } { set-length } }
+    { { $snippet { $emphasis "foo" } "-" { $emphasis "bar" } } { "(tuple accessors) outputs the value of the " { $snippet "bar" } " slot of the " { $snippet "foo" } " at the top of the stack" } { } }
+    { { $snippet "set-" { $emphasis "foo" } "-" { $emphasis "bar" } } { "(tuple mutators) sets the value of the " { $snippet "bar" } " slot of the " { $snippet "foo" } " at the top of the stack" } { } }
+    { { $snippet "with-" { $emphasis "foo" } } { "performs some kind of initialization and cleanup related to " { $snippet "foo" } ", usually in a new dynamic scope" } { $links with-scope with-stream } }
+    { { $snippet "$" { $emphasis "foo" } } { "help markup" } { $links $heading $emphasis } }
+} ;

doc/handbook/handbook.facts

@@ -18,6 +18,7 @@ ARTICLE: "handbook" "Factor documentation"
 { $subsection "cookbook-vocabs" }
 { $subsection "cookbook-io" }
 { $heading "Reference" }
+{ $subsection "conventions" }
 { $subsection "tools" }
 { $subsection "syntax" }
 { $subsection "dataflow" }

library/bootstrap/boot-stage1.factor

@@ -284,6 +284,7 @@ vectors words ;
         "/doc/handbook/alien.facts"
         "/doc/handbook/changes.facts"
         "/doc/handbook/collections.facts"
+        "/doc/handbook/conventions.facts"
         "/doc/handbook/cookbook.facts"
         "/doc/handbook/dataflow.facts"
         "/doc/handbook/handbook.facts"

library/help/markup.factor

@@ -151,8 +151,11 @@ M: f >link <link> ;
 : $definition ( content -- )
     "Definition" $heading $see ;
 
+: $links ( content -- )
+    [ 1array $link ] textual-list ;
+
 : $see-also ( content -- )
-    "See also" $heading [ 1array $link ] textual-list ;
+    "See also" $heading $links ;
 
 : $table ( content -- ) [ print-element ] tabular-output ;