rewrite mod build package docs for proposed changes

docs/mod-build-config.md

@@ -1,17 +1,17 @@
-**Stardew.ModBuildConfig** is an open-source NuGet package which automates the build configuration
-for [Stardew Valley](http://stardewvalley.net/) [SMAPI](https://github.com/Pathoschild/SMAPI) mods.
+The **mod build package** is an open-source NuGet package which automates the MSBuild configuration
+for SMAPI mods.
 
 The package...
 
-* lets you write your mod once, and compile it on any computer. It detects the current platform
-  (Linux, Mac, or Windows) and game install path, and injects the right references automatically.
+* lets your code compile on any computer (Linux/Mac/Windows) without needing to change the assembly
+  references or game path.
+* packages the mod into the game's `Mods` folder when you rebuild the code (configurable).
 * configures Visual Studio so you can debug into the mod code when the game is running (_Windows
   only_).
-* packages the mod automatically into the game's mod folder when you build the code (_optional_).
 
 ## Contents
 * [Install](#install)
-* [Simplify mod development](#simplify-mod-development)
+* [Configure](#configure)
 * [Troubleshoot](#troubleshoot)
 * [Release notes](#release-notes)
 
@@ -20,7 +20,7 @@ The package...
 
 1. Create an empty library project.
 2. Reference the [`Pathoschild.Stardew.ModBuildConfig` NuGet package](https://www.nuget.org/packages/Pathoschild.Stardew.ModBuildConfig).
-3. [Write your code](http://canimod.com/guides/creating-a-smapi-mod).
+3. [Write your code](https://stardewvalleywiki.com/Modding:Creating_a_SMAPI_mod).
 4. Compile on any platform.
 
 **When migrating an existing mod:**
@@ -30,59 +30,56 @@ The package...
 2. Reference the [`Pathoschild.Stardew.ModBuildConfig` NuGet package](https://www.nuget.org/packages/Pathoschild.Stardew.ModBuildConfig).
 3. Compile on any platform.
 
-## Simplify mod development
-### Package your mod into the game folder automatically
-You can copy your mod files into the `Mods` folder automatically each time you build, so you don't
-need to do it manually:
+## Configure
+### Deploy files into the `Mods` folder
+By default, your mod will be copied into the game's `Mods` folder (with a subfolder matching your
+project name) when you rebuild the code. The package will automatically include your
+`manifest.json`, any `i18n` files, and the build output.
 
-1. Edit your mod's `.csproj` file.
-2. Add this block above the first `</PropertyGroup>` line:
+To add custom files to the mod folder, just [add them to the build output](https://stackoverflow.com/a/10828462/262123).
+(If your project references another mod, make sure the reference is [_not_ marked 'copy local'](https://msdn.microsoft.com/en-us/library/t1zz5y8c(v=vs.100).aspx).)
 
-     ```xml
-     <DeployModFolderName>$(MSBuildProjectName)</DeployModFolderName>
-     ```
+You can change the mod's folder name by adding this above the first `</PropertyGroup>` in your
+`.csproj`:
+```xml
+<ModFolderName>YourModName</ModFolderName>
+```
 
-That's it! Each time you build, the files in `<game path>\Mods\<mod name>` will be updated with
-your `manifest.json`, build output, and any `i18n` files.
+If you don't want to deploy the mod automatically, you can add this:
+```xml
+<EnableModDeploy>False</EnableModDeploy>
+```
 
-Notes:
-* To add custom files, just [add them to the build output](https://stackoverflow.com/a/10828462/262123).
-* To customise the folder name, just replace `$(MSBuildProjectName)` with the folder name you want.
-* If your project references another mod, make sure the reference is [_not_ marked 'copy local'](https://msdn.microsoft.com/en-us/library/t1zz5y8c(v=vs.100).aspx).
+### Create release zip
+By default, a zip file will be created in the build output when you rebuild the code. This zip file
+contains all the files needed to share your mod in the recommended format for uploading to Nexus
+Mods or other sites.
 
-### Debug into the mod code (Windows-only)
-Stepping into your mod code when the game is running is straightforward, since this package injects
-the configuration automatically. To do it:
+You can change the zipped folder name (and zip name) by adding this above the first
+`</PropertyGroup>` in your `.csproj`:
+```xml
+<ModFolderName>YourModName</ModFolderName>
+```
 
-1. [Package your mod into the game folder automatically](#package-your-mod-into-the-game-folder-automatically).
-2. Launch the project with debugging in Visual Studio or MonoDevelop.
+You can change the folder path where the zip is created like this:
+```xml
+<ModZipPath>$(SolutionDir)\_releases</ModZipPath>
+```
 
-This will deploy your mod files into the game folder, launch SMAPI, and attach a debugger
-automatically. Now you can step through your code, set breakpoints, etc.
+Finally, you can disable the zip creation with this:
+```xml
+<EnableModZip>False</EnableModZip>
+```
 
-### Create release zips automatically (Windows-only)
-You can create the mod package automatically when you build:
+### Game path
+The package usually detects where your game is installed automatically. If it can't find your game
+or you have multiple installs, you can specify the path yourself. There's two ways to do that:
 
-1. Edit your mod's `.csproj` file.
-2. Add this block above the first `</PropertyGroup>` line:
-
-     ```xml
-     <DeployModZipTo>$(SolutionDir)\_releases</DeployModZipTo>
-     ```
-
-That's it! Each time you build, the mod files will be zipped into `_releases\<mod name>.zip`. (You
-can change the value to save the zips somewhere else.)
-
-## Troubleshoot
-### "Failed to find the game install path"
-That error means the package couldn't figure out where the game is installed. You need to specify
-the game location yourself. There's two ways to do that:
-
-* **Option 1: set the path globally.**  
-  _This will apply to every project that uses version 1.5+ of package._
+* **Option 1: global game path (recommended).**  
+  _This will apply to every project that uses the package._
 
   1. Get the full folder path containing the Stardew Valley executable.
-  2. Create this file path:
+  2. Create this file:
   
      platform  | path
      --------- | ----
@@ -99,10 +96,11 @@ the game location yourself. There's two ways to do that:
      </Project>
      ```
 
-  4. Replace `PATH_HERE` with your custom game install path.
+  4. Replace `PATH_HERE` with your game path.
+
+* **Option 2: path in the project file.**  
+  _You'll need to do this for each project that uses the package._
 
-* **Option 2: set the path in the project file.**  
-  _(You'll need to do it for every project that uses the package.)_
   1. Get the folder path containing the Stardew Valley `.exe` file.
   2. Add this to your `.csproj` file under the `<Project` line:
 
@@ -117,8 +115,16 @@ the game location yourself. There's two ways to do that:
 The configuration will check your custom path first, then fall back to the default paths (so it'll
 still compile on a different computer).
 
+
+## Troubleshoot
+### "Failed to find the game install path"
+That error means the package couldn't find your game. You need to specify the game path yourself;
+see _[Game path](#game-path)_ above.
+
 ## Release notes
-### 1.8
+### 2.0
+* Mods are now copied into the `Mods` folder automatically (configurable).
+* The release zip is now created automatically in your build output folder (configurable).
 * Added mod's version to release zip filename.
 * Fixed release zip not having a mod folder.
 * Fixed release zip failing if mod name contains characters that aren't valid in a filename.