Update the GN reference.md documentation.

tools/gn/docs/reference.md

 # GN Reference
 
 *This page is automatically generated from* `gn help --markdown all`.
 
 ## **\--args**: Specifies build arguments overrides.
 
 ```
   See "gn help buildargs" for an overview of how build arguments work.
 
   Most operations take a build directory. The build arguments are taken from
@@ skipping 307 matching lines @@
 ```
 ## **gn args <out_dir> [\--list] [\--short] [\--args]**
 
 ```
   See also "gn help buildargs" for a more high-level overview of how
   build arguments work.
 
 ```
 
 ### **Usage**
+
 ```
   gn args <out_dir>
-      Open the arguments for the given build directory in an editor (as
-      specified by the EDITOR environment variable). If the given build
-      directory doesn't exist, it will be created and an empty args file will
-      be opened in the editor. You would type something like this into that
-      file:
+      Open the arguments for the given build directory in an editor. If the
+      given build directory doesn't exist, it will be created and an empty args
+      file will be opened in the editor. You would type something like this
+      into that file:
           enable_doom_melon=false
           os="android"
 
+      To find your editor on Posix, GN will search the environment variables in
+      order: GN_EDITOR, VISUAL, and EDITOR. On Windows GN will open the command
+      associated with .txt files.
+
       Note: you can edit the build args manually by editing the file "args.gn"
       in the build directory and then running "gn gen <out_dir>".
 
   gn args <out_dir> --list[=<exact_arg>] [--short]
       Lists all build arguments available in the current configuration, or, if
       an exact_arg is specified for the list flag, just that one build
       argument.
 
-      The output will list the declaration location, default value, and comment
-      preceeding the declaration. If --short is specified, only the names and
-      values will be printed.
+      The output will list the declaration location, current value for the
+      build, default value (if different than the current value), and comment
+      preceeding the declaration.
 
-      If the out_dir is specified, the build configuration will be taken from
-      that build directory. The reason this is needed is that the definition of
-      some arguments is dependent on the build configuration, so setting some
-      values might add, remove, or change the default values for other
-      arguments. Specifying your exact configuration allows the proper
-      arguments to be displayed.
-
-      Instead of specifying the out_dir, you can also use the command-line flag
-      to specify the build configuration:
-        --args=<exact list of args to use>
+      If --short is specified, only the names and current values will be
+      printed.
 
 ```
 
 ### **Examples**
 
 ```
   gn args out/Debug
     Opens an editor with the args for out/Debug.
 
   gn args out/Debug --list --short
@@ skipping 5353 matching lines @@
 ```
   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
 
+  Next, project-specific overrides are applied. These are specified inside
+  the default_args variable of //.gn. See "gn help dotfile" for more.
+
   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.
 
@@ skipping 95 matching lines @@
       for a BUILD.gn file (or the build config file discussed above), the file
       will first be looked for in the source root. If it's not found, the
       secondary source root will be checked (which would contain a parallel
       directory hierarchy).
 
       This behavior is intended to be used when BUILD.gn files can't be checked
       in to certain source directories for whatever reason.
 
       The secondary source root must be inside the main source tree.
 
+  default_args [optional]
+      Scope containing the default overrides for declared arguments. These
+      overrides take precedence over the default values specified in the
+      declare_args() block, but can be overriden using --args or the
+      args.gn file.
+
+      This is intended to be used when subprojects declare arguments with
+      default values that need to be changed for whatever reason.
+
 ```
 
 ### **Example .gn file contents**
 
 ```
   buildconfig = "//build/config/BUILDCONFIG.gn"
 
   check_targets = [
     "//doom_melon/*",  # Check everything in this subtree.
     "//tools:mind_controlling_ant",  # Check this specific target.
   ]
 
   root = "//:root"
 
   secondary_source = "//build/config/temporary_buildfiles/"
 
+  default_args = {
+    # Default to release builds for this project.
+    is_debug = false
+    is_component_build = false
+  }
+
 
 ```
 ## **Build graph and execution overview**
 
 ### **Overall build flow**
 
 ```
   1. Look for ".gn" file (see "gn help dotfile") in the current directory and
      walk up the directory tree until one is found. Set this directory to be
      the "source root" and interpret this file to find the name of the build
@@ skipping 777 matching lines @@
 **  \--root**: Explicitly specify source root.
 **  \--runtime-deps-list-file**: Save runtime dependencies for targets in file.
 **  \--script-executable**: Set the executable used to execute scripts.
 **  \--threads**: Specify number of worker threads.
 **  \--time**: Outputs a summary of how long everything took.
 **  \--tracelog**: Writes a Chrome-compatible trace log to the given file.
 **  -v**: Verbose logging.
 **  \--version**: Prints the GN version number and exits.
 
 ```