Describe [autoexec] join vs overwrite in README

1 files changed, 52 insertions, 13 deletions

diff --git a/README b/README
index 544714602..7f5ac812b 100644
--- a/README
+++ b/README
@@ -77,9 +77,30 @@ START: How to start?
 
 
 AUTOMATION: Do I always have to type these commands?
-    In the DOSBox configuration file is an [autoexec] section. The commands
-    present there are run when DOSBox starts, so you can use this section
-    for the mounting. Look at Section 13: "The configuration (options) file".
+    DOSBox configuration files contain an [autoexec] section that holds
+    one or more commands, listed line by line, just as you would type them
+    into the DOSBox command prompt. The [autoexec] section is run on startup.
+
+    When multiple configuration files are loaded that each have [autoexec]
+    sections, DOSBox Staging by default joins these sections into a combined
+    [autoexec] that's run.
+
+    If you prefer to only run the most recently processed [autoexec] when
+    multiple configuration files are provided, you can set the "autoexec_section"
+    setting to "overwrite", in the [dosbox] section.  When in this mode, the
+    the overwrite-order is as follows:
+
+    1. Highest priority are those command(s) provided on the command line
+    2. Second is the [autoexec] section from the last processed custom conf file.
+       This would be custom2, if: dosbox -conf custom1.conf -conf custom2.conf
+    3. Third is the [autoexec] section from the local conf, ie: when
+       dosbox.conf is present in the current directory
+    4. Last is the [autoexec] section from the users primary conf,
+       ie: /user/config/dosbox/dosbox-staging.conf.
+
+    This ordering of configuration files is also discussed in Section 3:
+    "Command Line Parameters", and specific configuration file settings are
+    discussed in Section 13: "The configuration (options) file".
 
 
 FULLSCREEN: How do I change to fullscreen?
@@ -394,20 +415,38 @@ dosbox -opencaptures program
 
         1. The primary configuration file is loaded first, which comes
            from the operating system's user configuration directory.
-           This can be thought of as your "global" configuration file.
-           Adding -noprimaryconf avoids loading your primary conf file.
+           This can be thought of as your "global" configuration file,
+           The -noprimaryconf flag can be used in cases where you want
+           to avoid loading your primary conf file.
 
-        3. Second, if the local directory contains a dosbox.conf file,
-           these settings are added.
-           Adding -nolocalconf avoids loading the local dosbox.conf file.
+        2. Second, if the local directory contains a dosbox.conf file,
+           its settings override those previously set by your Primary file.
+           The -nolocalconf flag can be used in cases where you want to
+           avoid loading the local dosbox.conf file.
 
-        2. Finally, custom configurations are layered on, in order,
+        3. Finally, custom configurations are layered on, in order,
            using one or more -conf <filename> arguments. For example:
            dosbox -conf myshader.conf -conf myaudio.conf
-
-        This layered approach means you can start with the most general
-        settings (from your primary conf) and increasingly fine-tune them
-        for a specific game.
+           These settings override those previously set by either the
+           Local or Primary configurations.
+
+        This layered approach means you can start with general settings
+        (from your Primary conf) and increasingly fine-tune them for a specific
+        game.
+
+        If the [dosbox] "autoexec_section" setting is "overwrite", then
+        the same priority order applies when multiple configuration files
+        provide the [autoexec] section: DOSBox Staging will execute [autoexec]
+        only from the end-most (or highest priority) configuration file.
+
+        Additionally, if you've passed commands as arguments directly on the
+        command line, ie: dosbox /path/game/run.bat, then these take priority
+        over any prior [autoexec] sections - to avoid mount and launch
+        conflicts.
+
+        If you wish to use the original behavior where [autoexec] sections
+        are joined into a combined set of commands, then set the [dosbox]
+        "autoexec_section" setting to "join". This is also the default.
 
 
   -lang languagefilelocation