Add command line documentation to handbook

doc/handbook/cli.facts

@@ -0,0 +1,50 @@
+USING: help parser shells ;
+
+ARTICLE: "cli" "Command line usage"
+"Unless the " { $snippet "-no-user-init" } " command line switch is specified, The startup routine runs the " { $snippet ".factor-rc" } " file in the user's home directory, if it exists. This file can contain initialization and customization for your development environment."
+$terpri
+"Zero or more command line arguments may be passed to the Factor runtime. Command line arguments starting with a dash (" { $snippet "-" } ") is interpreted as a switch. All other arguments are taken to be file names."
+$terpri
+"If any file names are specified at all, the first one must be the image name; otherwise, the default image file is used, which is usually a file named " { $snippet "factor.image" } " in the same directory as the runtime executable (on Windows and Mac OS X) or the current directory (on Unix)."
+$terpri
+"All file names other than the first one are source file names which will be run using " { $link try-run-file } " when Factor starts up."
+$terpri
+"Finally, switches can take one of the following three forms:"
+{ $list
+    { { $snippet "-" { $emphasis "foo" } } " - sets the global variable " { $snippet "\"" { $emphasis "foo" } "\"" } " to " { $link t } }
+    { { $snippet "-no-" { $emphasis "foo" } } " - sets the global variable " { $snippet "\"" { $emphasis "foo" } "\"" } " to " { $link f } }
+    { { $snippet "-" { $emphasis "foo" } "=" { $emphasis "bar" } } " - sets the global variable " { $snippet "\"" { $emphasis "foo" } "\"" } " to " { $snippet "\"" { $emphasis "bar" } "\"" } }
+}
+{ $subsection "runtime-cli-args" }
+{ $subsection "bootstrap-cli-args" }
+{ $subsection "standard-cli-args" } ;
+
+ARTICLE: "runtime-cli-args" "Runtime command line switches"
+"A handful of command line switches are processed by the runtime and not the library. They control low-level features."
+{ $table
+    { { $snippet "-D=" { $emphasis "n" } } "Data stack size, kilobytes" }
+    { { $snippet "-R=" { $emphasis "n" } } "Retain stack size, kilobytes" }
+    { { $snippet "-C=" { $emphasis "n" } } "Call stack size, kilobytes" }
+    { { $snippet "-G=" { $emphasis "n" } } "Number of generations, must be >= 2" }
+    { { $snippet "-Y=" { $emphasis "n" } } "Size of n-1 youngest generations, megabytes" }
+    { { $snippet "-A=" { $emphasis "n" } } "Size of tenured and semi-spaces, megabytes" }
+    { { $snippet "-X=" { $emphasis "n" } } "Code heap size, megabytes" }
+} ;
+
+ARTICLE: "bootstrap-cli-args" "Switches available when bootstrapping"
+"A number of command line switches can be passed to a bootstrap image to modify the behavior of the resulting " { $snippet "factor.image" } ":"
+{ $table
+    { { $snippet "-no-compile" } "Do not compile any words in the image or load any modules which depend on the compiler" }
+    { { $snippet "-no-native-io" } "Do not load the native I/O module for your operating system; non-blocking I/O and sockets will not be available" }
+    { { $snippet "-no-cocoa" } "(Mac OS X only) do not load the Cocoa UI backend" }
+    { { $snippet "-x11" } "(Unix only) load the X11 UI backend. You can specify " { $snippet "-no-cocoa -x11" } " to load the X11 UI on Mac OS X" }
+    { { $snippet "-no-x11" } "(Unix only) do not load the X11 UI backend" }
+}
+"To find out how to generate a bootstrap image, see " { $link "images" } "." ;
+
+ARTICLE: "standard-cli-args" "General command line switches"
+"The following command line switches can be passed to a bootstrapped Factor image:"
+{ $table
+    { { $snippet "-shell=" { $emphasis "shell" } } { { $snippet { $emphasis "shell" } } " is either " { $link tty } ", " { $link ui } ", or the name of any other word in the " { $snippet "shells" } " vocabulary. This specifies the user interface to run on startup." } }
+    { { $snippet "-no-user-init" } { "If specified, Factor will not run the " { $snippet "~/.factor-rc" } " file on startup" } }
+} ;

doc/handbook/handbook.facts

@@ -1,5 +1,5 @@
-USING: generic hashtables help inspector namespaces parser
-prettyprint sequences words ;
+USING: generic hashtables help inspector modules namespaces
+parser prettyprint sequences words ;
 
 ARTICLE: "handbook" "Factor documentation"
 { $subsection "changes" }
@@ -7,6 +7,8 @@ ARTICLE: "handbook" "Factor documentation"
 { $list
     { "Load source files using " { $link run-file } ":"
     { $code "\"contrib/httpd/load.factor\" run-file" } }
+    { "Load modules from " { $snippet "contrib/" } " using " { $link require } ":" }
+    { $code "\"httpd\" require" }
     { { $link .s } " prints the contents of the stack." }
     { { $link . } " prints the object at the top of the stack." }
 }
@@ -31,6 +33,7 @@ ARTICLE: "handbook" "Factor documentation"
 { $subsection "prettyprint" }
 { $subsection "alien" }
 { $heading "Environment reference" }
+{ $subsection "cli" }
 { $subsection "tools" }
 { $subsection "help" }
 { $heading "Index" }

doc/handbook/tools.facts

@@ -183,4 +183,6 @@ $terpri
 { $subsection save-image }
 "A new image can also be built from sources; this is known as " { $emphasis "bootstrap" } ". Bootstrap is a two-step process. The first stage is the creation of a bootstrap image inside a running Factor instance:"
 { $subsection make-image }
-"The second stage is initiated by running the resulting bootstrap image. This stage loads any additional platform-specific code, compiles all words, and dumps a new, final image." ;
+"The second stage is initiated by running the resulting bootstrap image. This stage loads any additional platform-specific code, compiles all words, and dumps a new, final image."
+$terpri
+"The bootstrap image supports a number of command line arguments; see " { $link "bootstrap-cli-args" } "." ;

library/bootstrap/boot-stage1.factor

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