Merge pull request #72166 from Brambor/friendly-docs

docs on compiling: friendlier to first-time contributors

doc/COMPILING/COMPILING-CMAKE.md

@@ -117,7 +117,7 @@ $ cmake-gui ..
 
 ## CMake Build for MSYS2 (MinGW)
 
-1. Follow `COMPILING-MSYS.md` 
+1. Follow [`COMPILING-MSYS.md`](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/COMPILING/COMPILING-MSYS.md)
 
 2. Run
 ```

doc/COMPILING/COMPILING-CYGWIN.md

@@ -57,6 +57,8 @@ You will see messages saying packages are already installed, as well as Cygwin i
 
 **Note:** This will download the entire CDDA repository and all of its history (3GB). If you're just testing, you should probably add `--depth=1` (~350MB).
 
+**Note:** If you want to contribute to CDDA, see [example git workflow](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/CONTRIBUTING.md#example-workflow).
+
 ```bash
 cd /cygdrive/c/dev
 git clone https://github.com/CleverRaven/Cataclysm-DDA.git
@@ -71,7 +73,7 @@ make CCACHE=1 RELEASE=1 CYGWIN=1 DYNAMIC_LINKING=1 SDL=1 TILES=1 SOUND=1 LOCALIZ
 
 You will receive warnings about unterminated character constants; they do not impact the compilation as far as this writer is aware.
 
-**Note**: This will compile release version with Sound and Tiles support and all localization languages, skipping checks and tests and using ccache for faster build. You can use other switches, but `Cygwin=1`, `DYNAMIC_LINKING=1` and probably `RELEASE=1` are required to compile without issues.
+This will compile release version with Sound and Tiles support and all localization languages, skipping checks and tests and using ccache for faster build. You can use other switches, but `Cygwin=1`, `DYNAMIC_LINKING=1` and probably `RELEASE=1` are required to compile without issues.
 
 ## Running:
 

doc/COMPILING/COMPILING-MSYS.md

@@ -74,7 +74,7 @@ git clone https://github.com/CleverRaven/Cataclysm-DDA.git ./Cataclysm-DDA
 
 **Note:** This will download the entire CDDA repository and all of its history (3GB). If you're just testing, you should probably add `--depth=1` (~350MB).
 
-**Note:** See `COMPILING-CMAKE.md` section `CMake Build for MSYS2 (MinGW)` for using the CMake build system.
+**Note:** If you want to contribute to CDDA, see [example git workflow](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/CONTRIBUTING.md#example-workflow).
 
 2. Compile with following command line:
 
@@ -85,9 +85,9 @@ make -j$((`nproc`+0)) CCACHE=1 RELEASE=1 MSYS2=1 DYNAMIC_LINKING=1 SDL=1 TILES=1
 
 You will receive warnings about unterminated character constants; they do not impact the compilation as far as this writer is aware.
 
-**Note**: This will compile a release version with Sound and Tiles support and all localization languages, skipping checks and tests, and using ccache for build acceleration. You can use other switches, but `MSYS2=1`, `DYNAMIC_LINKING=1` and probably `RELEASE=1` are required to compile without issues.
+This will compile a release version with Sound and Tiles support and all localization languages, skipping checks and tests, and using ccache for build acceleration. You can use other switches, but `MSYS2=1`, `DYNAMIC_LINKING=1` and probably `RELEASE=1` are required to compile without issues.
 
-See `COMPILING-CMAKE.md` section `CMake Build for MSYS2 (MinGW)` for using the CMake build system.
+**Note:** See `COMPILING-CMAKE.md` section [`CMake Build for MSYS2 (MinGW)`](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/COMPILING/COMPILING-CMAKE.md#cmake-build-for-msys2-mingw) for using the CMake build system.
 
 ## Running:
 

doc/COMPILING/COMPILING-VS-VCPKG.md

@@ -35,7 +35,7 @@ cd vcpkg
 .\vcpkg integrate install
 ```
 In a Git Bash shell, the commands are almost the same except the filesystem path separator is `/` instead of `\`.
-```
+```cmd
 # cd to the appropriate folder first
 git clone https://github.com/Microsoft/vcpkg.git
 cd vcpkg
@@ -47,13 +47,15 @@ cd vcpkg
 
 1. Clone Cataclysm-DDA repository with following command line:
 
-**Note:** This will download the entire CDDA repository; about three gigs of data. If you're just testing you should probably add `--depth=1`.
-
 ```cmd
 git clone https://github.com/CleverRaven/Cataclysm-DDA.git
 cd Cataclysm-DDA
 ```
 
+**Note:** This will download the entire CDDA repository; about three gigs of data. If you're just testing you should probably add `--depth=1`.
+
+**Note:** If you want to contribute to CDDA, see [example git workflow](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/CONTRIBUTING.md#example-workflow).
+
 2. Open the provided solution (`msvc-full-features\Cataclysm-vcpkg-static.sln`) in `Visual Studio`.
 
 3. Open the `Build > Configuration Manager` menu and adjust `Active solution configuration` and `Active solution platform` to match your intended target.
@@ -63,7 +65,7 @@ cd Cataclysm-DDA
 
 4. Start the build process by selecting either `Build > Build Solution` or `Build > Build > 1 Cataclysm-vcpkg-static`. The process may take a long period of time, so you'd better prepare a cup of coffee and some books in front of your computer :) The first build of each architecture will also download and install dependencies through vcpkg, which can take an especially long time.
 
-5. If you need localization support, execute the bash script `lang/compile_mo.sh` inside Git Bash GUI just like on a UNIX-like system. This will compile the language files that were not automatically compiled in step 2 above.
+5. If you need localization support, execute the bash script `lang/compile_mo.sh` inside Git Bash GUI just like on a UNIX-like system. This will compile the language files that were not automatically compiled in step 3 above.
 
 Even if you do not need languages other than English, you may still want to execute `lang/compile_mo.sh` to compile the language files if you're planning to run the unit tests, since those rely on the language files existing.
 

doc/CONTRIBUTING.md

@@ -139,6 +139,8 @@ Helpful pages:
 
 1. [Fork](https://github.com/CleverRaven/Cataclysm-DDA/fork) this repository here on GitHub.
 
+**Note:** Fork is different from branch, branches are covered [later](#make-your-changes).
+
 2. Clone your fork locally.
 
     ```bash

doc/USER_INTERFACE_AND_ACCESSIBILITY.md

@@ -3,13 +3,13 @@
 Cataclysm: Dark Days Ahead uses ncurses, or in the case of the tiles build, an
 ncurses port, for user interface. Window management is achieved by `ui_adaptor`,
 which requires a resizing callback and a redrawing callback for each UI to handle
-resizing and redrawing. A migration effort is underway for user interface code 
+resizing and redrawing. A migration effort is underway for user interface code
 to be moved to ImGui, which uses SDL on the tiled build, and ncurses on non-tiled
 Linux builds.
 
 Some good examples of the usage of `ui_adaptor` can be found within the following
 files:
-- `string_input_popup` in `string_input_popup.cpp`, specifically in 
+- `string_input_popup` in `string_input_popup.cpp`, specifically in
  `string_input_popup::query_string()`
 - `Messages::dialog` in `messages.cpp`
 
@@ -18,17 +18,17 @@ Details on how to use `ui_adaptor` can be found within `ui_manager.h`.
 New user interfaces should be coded using ImGui. ImGui-backed windows are created
 using `cataimgui::window` as a base, see `cata_imgui.h/cpp`. `cataimgui::window`
 still uses `ui_adaptor` but it is handled internally. `cataimgui::window` handles
-creating the ImGui window itself, but any widgets (i.e. text boxes, tables, input 
-fields) must be created using the correct function under the `ImGui` namespace. 
+creating the ImGui window itself, but any widgets (i.e. text boxes, tables, input
+fields) must be created using the correct function under the `ImGui` namespace.
 Examples of creating any ImGui widget can be found in `src/third-party/imgui_demo.cpp`
 
 Good examples of implementating an ImGui-based UI in cataclysm:
 - `query_popup` and `static_popup` in `popup.h/cpp`, specifically `query_popup_impl`
  which is a private implementation class used by the aforementioned classes.
-- `keybindings_ui` in `input.cpp`, which is a private implementation class used 
+- `keybindings_ui` in `input.cpp`, which is a private implementation class used
  by `input_context::display_menu()`.
 
-## SDL version requirement of the tiles build 
+## SDL version requirement of the tiles build
 
 Some functions used by this project require SDL 2.0.6, and the actual version
 requirement might be higher. While using a newer version is optional, new versions add