Redo GN "args" command

tools/gn/args.cc

Index: tools/gn/args.cc
diff --git a/tools/gn/args.cc b/tools/gn/args.cc
index 2c4891ca82bb742b3cad77d52afdf2515a43204c..db7b84dd94bbdad105431b0994aa41625b83fef4 100644
--- a/tools/gn/args.cc
+++ b/tools/gn/args.cc
@@ -26,20 +26,33 @@ const char kBuildArgs_Help[] =
     "   - default_os\n"
     "   - os (by default this is the same as \"default_os\")\n"
     "\n"
-    "  Second, arguments specified on the command-line via \"--args\" are\n"
-    "  applied. These can override the system default ones, and add new ones.\n"
-    "  These are whitespace-separated. For example:\n"
+    "  If specified, arguments from the --args command line flag are used. If\n"
+    "  that flag is not specified, args from previous builds in the build\n"
+    "  directory will be used (this is in the file args.gn in the build\n"
+    "  directory).\n"
     "\n"
-    "    gn --args=\"enable_doom_melon=false\" os=\\\"beos\\\"\n"
-    "\n"
-    "  Third, toolchain overrides are applied. These are specified in the\n"
+    "  Last, for targets being compiled with a non-default toolchain, the\n"
+    "  toolchain overrides are applied. These are specified in the\n"
     "  toolchain_args section of a toolchain definition. The use-case for\n"
     "  this is that a toolchain may be building code for a different\n"
     "  platform, and that it may want to always specify Posix, for example.\n"
     "  See \"gn help toolchain_args\" for more.\n"
     "\n"
-    "  It is an error to specify an override for a build argument that never\n"
-    "  appears in a \"declare_args\" call.\n"
+    "  If you specify an override for a build argument that never appears in\n"
+    "  a \"declare_args\" call, a nonfatal error will be displayed.\n"
+    "\n"
+    "Examples\n"
+    "\n"
+    "  gn args out/FooBar\n"
+    "      Create the directory out/FooBar and open an editor. You would type\n"
+    "      something like this into that file:\n"
+    "          enable_doom_melon=false\n"
+    "          os=\"android\"\n"
+    "\n"
+    "  gn gen out/FooBar --args=\"enable_doom_melon=true os=\\\"android\\\"\"\n"
+    "      This will overwrite the build directory with the given arguments.\n"
+    "      (Note that the quotes inside the args command will usually need to\n"
+    "      be escaped for your shell to pass through strings values.)\n"
     "\n"
     "How build arguments are used\n"
     "\n"