Allow raw string literals and add a sample usage.

tools/gn/args.cc

 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #include "tools/gn/args.h"
 
 #include "base/sys_info.h"
 #include "build/build_config.h"
 #include "tools/gn/variables.h"
 
 const char kBuildArgs_Help[] =
-    "Build Arguments Overview\n"
-    "\n"
-    "  Build arguments are variables passed in from outside of the build\n"
-    "  that build files can query to determine how the build works.\n"
-    "\n"
-    "How build arguments are set\n"
-    "\n"
-    "  First, system default arguments are set based on the current system.\n"
-    "  The built-in arguments are:\n"
-    "   - host_cpu\n"
-    "   - host_os\n"
-    "   - current_cpu\n"
-    "   - current_os\n"
-    "   - target_cpu\n"
-    "   - target_os\n"
-    "\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"
-    "  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\" for more.\n"
-    "\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"
-    "  If you want to use an argument, you use declare_args() and specify\n"
-    "  default values. These default values will apply if none of the steps\n"
-    "  listed in the \"How build arguments are set\" section above apply to\n"
-    "  the given argument, but the defaults will not override any of these.\n"
-    "\n"
-    "  Often, the root build config file will declare global arguments that\n"
-    "  will be passed to all buildfiles. Individual build files can also\n"
-    "  specify arguments that apply only to those files. It is also useful\n"
-    "  to specify build args in an \"import\"-ed file if you want such\n"
-    "  arguments to apply to multiple buildfiles.\n";
+    R"(Build Arguments Overview

[Peter Kasting, 2016/11/01 01:13:29]

This indenting is slightly odd, but clang-format doesn't like not having the
leading 4 spaces, and it's kinda got a point.

+
+  Build arguments are variables passed in from outside of the build
+  that build files can query to determine how the build works.
+
+How build arguments are set
+
+  First, system default arguments are set based on the current system.
+  The built-in arguments are:
+   - host_cpu
+   - host_os
+   - current_cpu
+   - current_os
+   - target_cpu
+   - target_os
+
+  If specified, arguments from the --args command line flag are used. If
+  that flag is not specified, args from previous builds in the build
+  directory will be used (this is in the file args.gn in the build
+  directory).
+
+  Last, for targets being compiled with a non-default toolchain, the
+  toolchain overrides are applied. These are specified in the
+  toolchain_args section of a toolchain definition. The use-case for
+  this is that a toolchain may be building code for a different
+  platform, and that it may want to always specify Posix, for example.
+  See "gn help toolchain" for more.
+
+  If you specify an override for a build argument that never appears in
+  a "declare_args" call, a nonfatal error will be displayed.
+
+Examples
+
+  gn args out/FooBar
+      Create the directory out/FooBar and open an editor. You would type
+      something like this into that file:
+          enable_doom_melon=false
+          os="android"
+
+  gn gen out/FooBar --args="enable_doom_melon=true os=\"android\""
+      This will overwrite the build directory with the given arguments.
+      (Note that the quotes inside the args command will usually need to
+      be escaped for your shell to pass through strings values.)
+
+How build arguments are used
+
+  If you want to use an argument, you use declare_args() and specify
+  default values. These default values will apply if none of the steps
+  listed in the "How build arguments are set" section above apply to
+  the given argument, but the defaults will not override any of these.
+
+  Often, the root build config file will declare global arguments that
+  will be passed to all buildfiles. Individual build files can also
+  specify arguments that apply only to those files. It is also useful
+  to specify build args in an "import"-ed file if you want such
+  arguments to apply to multiple buildfiles.
+)";
 
 namespace {
 
 // Removes all entries in |overrides| that are in |declared_overrides|.
 void RemoveDeclaredOverrides(const Scope::KeyValueMap& declared_arguments,
                              Scope::KeyValueMap* overrides) {
   for (Scope::KeyValueMap::iterator override = overrides->begin();
        override != overrides->end();) {
     if (declared_arguments.find(override->first) == declared_arguments.end())
       ++override;
@@ skipping 276 matching lines @@
     Scope* scope) const {
   lock_.AssertAcquired();
   return declared_arguments_per_toolchain_[scope->settings()];
 }
 
 Scope::KeyValueMap& Args::OverridesForToolchainLocked(
     Scope* scope) const {
   lock_.AssertAcquired();
   return toolchain_overrides_[scope->settings()];
 }