doc: recommend latest dependency tag rather than main branch (#72)

doc/setup.md

@@ -2,15 +2,29 @@
 
 ## Dependencies
 
-### `meson`: Build system used by `iguana`
+The following sections list the dependencies and how to obtain them.
+
+> [!IMPORTANT]
+> If you obtain a dependency with `git clone`, it is strongly recommended to checkout a recent tag,
+> rather than using the most recent version on the main branch. For example, to use version `10.2.0`
+> of `fmt`, run (while in the `fmt` repository directory):
+> ```bash
+> git checkout 10.2.0
+> ```
+> See the list of tags in chronological order (latest is first) by running:
+> ```bash
+> git log --tags --decorate --simplify-by-decoration --oneline
+> ```
+
+### :large_orange_diamond: `meson`: Build system used by `iguana`
 <https://mesonbuild.com/>
 - likely available in your package manager
 - you may also install `meson` (and `ninja`) with `pip`:
 ```bash
 python -m pip install meson ninja
 ```
 
-### `fmt`: C++ output formatting library
+### :large_orange_diamond: `fmt`: C++ output formatting library
 <https://github.com/fmtlib/fmt>
 - likely available in your package manager, possibly under `libfmt`
 - if you compile it yourself, include the `cmake` option `-DCMAKE_POSITION_INDEPENDENT_CODE=ON`
@@ -21,7 +35,7 @@ cmake --build build-fmt -j$(nproc)
 cmake --install build-fmt
 ```
 
-### `hipo`: C++ HIPO API
+### :large_orange_diamond: `hipo`: C++ HIPO API
 <https://github.com/gavalian/hipo>
 - use the `hipo` module on `ifarm`, or obtain and build it yourself
 - example `cmake` commands:
@@ -36,7 +50,7 @@ cmake --install build-hipo
 - For convenience, a configuration script is provided.
 - Advanced users who want more control may skip to the "Using Meson Directly" section.
 
-### Using the Configuration Script
+### :large_blue_diamond: Using the Configuration Script
 
 First, configure your `iguana` build using `configure.py`:
 ```bash
@@ -45,15 +59,29 @@ First, configure your `iguana` build using `configure.py`:
 The `--help` option will print the usage guide.
 Unless the dependencies are installed in one of the system default locations, you will need to specify the path to each of them, _e.g._,
 ```bash
-./configure.py --hipo /path/to/hipo_installation
+./configure.py --hipo /path/to/hipo_installation --fmt /path/to/fmt_installation
 ```
-This will generate a configuration file (`.ini`) with the build settings, along with an installation script (`install-iguana.sh`).
+This will generate a configuration file (`build-iguana.ini`, by default) with the build settings, along with an installation script (`install-iguana.sh`).
 Inspect both of them, and if they look correct, proceed with building and installing `iguana` by running:
 ```bash
 ./install-iguana.sh
 ```
 
-### Using Meson Directly
+> [!TIP]
+> You may edit the configuration file (`build-iguana.ini`, by default) to
+> change any settings, and rebuild `iguana` with `./install-iguana.sh`.
+> - this procedure is preferred if you just want to change some settings
+> - re-running `configure.py` will _overwrite_ your configuration file
+
+> [!TIP]
+> If you have trouble and want to try a clean build, wipe your build directory (`build-iguana/`, by default). The safest
+> way to do this is:
+> ```bash
+> meson setup --wipe build-iguana
+> ```
+> Then try to rebuild
+
+### :large_blue_diamond: Using Meson Directly
 
 Instead of `configure.py`, use `meson` directly for more control:
 

doc/troubleshooting.md

@@ -1,6 +1,6 @@
 # Troubleshooting Notes
 
-## My output appears to be out of order: errors are not printed exactly when they occur
+### :large_blue_diamond: My output appears to be out of order: errors are not printed exactly when they occur
 
 If you redirect `stdout` and `stderr` to a file, you may notice that `stderr` lines are out-of-order with respect to the `stdout` lines; for example:
 ```bash
@@ -14,12 +14,12 @@ To redirect output to a file with the ordering preserved, run your executable wi
 stdbuf -o0 myAnalysisProgram |& tee output.txt
 ```
 
-## I got a crash, but the stack trace (or debugger) is not telling me exactly where
+### :large_blue_diamond: I got a crash, but the stack trace (or debugger) is not telling me exactly where
 
 Try enabling debugging symbols, either by:
 - set built-in option `buildtype` to `'debug'` in your build-configuration `.ini` file (or in your `meson` command)
 - use `--debug` when running `configure.py`
 
-Then re-build `iguana`.
+Then rebuild `iguana`.
 
-Remember to revert this change and re-build, so that `iguana` runs with full optimization when you are processing large data sets (`buildtype = 'release'`).
+Remember to revert this change and rebuild, so that `iguana` runs with full optimization when you are processing large data sets (`buildtype = 'release'`).