From b85af601c04b288189b4ccb46c4c9b4523cc7e84 Mon Sep 17 00:00:00 2001
From: Slava Pestov <slava@factorcode.org>
Date: Mon, 5 Nov 2007 01:23:48 -0500
Subject: [PATCH] Document deployment

---
 extra/tools/deploy/deploy-docs.factor    | 20 ++++++++++++--------
 extra/ui/tools/deploy/deploy-docs.factor | 14 ++++++++++++++
 extra/ui/tools/tools-docs.factor         |  4 +++-
 3 files changed, 29 insertions(+), 9 deletions(-)
 create mode 100644 extra/ui/tools/deploy/deploy-docs.factor

diff --git a/extra/tools/deploy/deploy-docs.factor b/extra/tools/deploy/deploy-docs.factor
index 29e0da1f5c..f6e9cb2882 100644
--- a/extra/tools/deploy/deploy-docs.factor
+++ b/extra/tools/deploy/deploy-docs.factor
@@ -2,16 +2,20 @@ USING: help.markup help.syntax words alien.c-types assocs
 kernel ;
 IN: tools.deploy
 
-ARTICLE: "tools.deploy" "Stand-alone image deployment"
-"The stand-alone image deployment tool takes a vocabulary and generates an image, which when passed to the VM, runs the vocabulary's " { $link POSTPONE: MAIN: } " hook."
+ARTICLE: "tools.deploy" "Application deployment"
+"The stand-alone application deployment tool compiles a vocabulary down to a native executable which runs the vocabulary's " { $link POSTPONE: MAIN: } " hook. Deployed executables do not depend on Factor being installed, and do not expose any source code, and thus are suitable for delivering commercial end-user applications."
 $nl
 "For example, we can deploy the " { $vocab-link "hello-world" } " demo which comes with Factor:"
-{ $code "\"hello-world\" deploy" }
-"This generates an image file named " { $snippet "hello-world.image" } ". Now we can start this image from the operating system's command line (see " { $link "runtime-cli-args" } "):"
-{ $code "./factor -i=hello-world.image" "Hello world" }
-
-"Once the necessary deployment flags have been set, a deployment image can be generated:"
-{ $subsection deploy } ;
+{ $code "\"hello-ui\" deploy" }
+"On Mac OS X, this yields a program named " { $snippet "Hello world.app" } ". On Windows, it yields a directory named " { $snippet "Hello world" } " containing a program named " { $snippet "hello-ui.exe" } ". In both cases, running the program displays a window with a message."
+$nl
+"The deployment tool works by bootstrapping a fresh image, loading the vocabulary into this image, then applying various heuristics to strip the image down to minimal size."
+$nl
+"You must explicitly specify major subsystems which are required, as well as the level of reflection support needed. This is done by modifying the deployment configuration prior to deployment."
+{ $subsection "prepare-deploy" }
+"Once the necessary deployment flags have been set, the application can be deployed:"
+{ $subsection deploy }
+{ $see-also "ui.tools.deploy" } ;
 
 ABOUT: "tools.deploy"
 
diff --git a/extra/ui/tools/deploy/deploy-docs.factor b/extra/ui/tools/deploy/deploy-docs.factor
new file mode 100644
index 0000000000..4898b651a1
--- /dev/null
+++ b/extra/ui/tools/deploy/deploy-docs.factor
@@ -0,0 +1,14 @@
+USING: help.markup help.syntax ui.tools.deploy ;
+
+HELP: deploy-tool
+{ $values { "vocab" "a vocabulary specifier" } }
+{ $description "Opens the graphical deployment tool for the specified vocabulary." }
+{ $examples { $code "\"tetris\" deploy-tool" } } ;
+
+ARTICLE: "ui.tools.deploy" "Application deployment UI tool"
+"The application deployment UI tool provides a graphical front-end to deployment configuration. Using the tool, you can set deployment options graphically."
+$nl
+"To start the tool, pass a vocabulary name to a word:"
+{ $subsection deploy-tool }
+"Alternatively, right-click on a vocabulary presentation in the UI and choose " { $strong "Deploy tool" } " from the resulting popup menu."
+{ $see-also "tools.deploy" } ;
diff --git a/extra/ui/tools/tools-docs.factor b/extra/ui/tools/tools-docs.factor
index e80dfe3c33..df795fa987 100644
--- a/extra/ui/tools/tools-docs.factor
+++ b/extra/ui/tools/tools-docs.factor
@@ -130,12 +130,14 @@ $nl
 { $subsection "ui-presentations" }
 { $subsection "ui-completion" }
 { $heading "Tools" }
-"All development tools are integrated into a single-window " { $emphasis "workspace" } "."
+"A single-window " { $emphasis "workspace" } " contains the most frequently-used tools:"
 { $subsection "ui-listener" }
 { $subsection "ui-browser" }
 { $subsection "ui-inspector" }
 { $subsection "ui-walker" }
 { $subsection "ui-profiler" }
+"Additional tools:"
+{ $subsection "ui.tools.deploy" }
 "Platform-specific features:"
 { $subsection "ui-cocoa" } ;