Minor documentation changes.

README.md

@@ -12,23 +12,19 @@ With [some work](doc/extend.md), you can also:
 - include your own annotations
 - include the ASOP, complete with clickable links to each rule
 
-*NOTE: This project integrates with my other [`asl-articles`](https://github.com/pacman-ghost/asl-articles) project, so that if an article references a rule, it becomes a clickable link that will open a browser showing that rule.*
+*NOTE: The program requires Firefox; Chrome doesn't support a key feature it needs.*
+
+*NOTE: This project integrates with my other [`asl-articles`](https://github.com/pacman-ghost/asl-articles) project, so that if an article references a rule, it becomes a clickable link that will open a browser showing that rule. The [`vasl-templates`](https://github.com/pacman-ghost/vasl-templates) project can also be configured to allow vehicles and ordnance to open their corresponding Chapter H entries.*
 
 ### Installation
 
 After cloning the repo, you can either:
-- run it using Docker (recommended, run `./run-container.sh`)
+- run it using Docker (recommended, run `./run-container.sh --port 5020`)
 - run it from source (requires Python 3.8.7, install the module, run `asl_rulebook2/webapp/run_server.py`)
 
-*NOTE: Run either command with no arguments to get help.*
-
-Run either command with a `--port` argument, then connect to the server in a browser e.g.
-
-``` ./run-container.sh --port 5020 ```
-
-Then open `http://localhost:5020`.
+*NOTE: Run either command with `--help` to get help.*
 
-*NOTE: The program requires Firefox; Chrome doesn't really support a key feature it needs.*
+Then connect to the server in a browser at `http://localhost:5020`.
 
 A few things need to be set up before the program can be used; the webapp will guide you through the process.
 

asl_rulebook2/webapp/main.py

@@ -41,6 +41,9 @@ def get_control_tests():
     def get_port():
         """Get the configured gRPC service port."""
         # NOTE: The Docker container configures this setting via an environment variable.
+        # NOTE: It would be nice to default this to -1, so that pytest will work out-of-the-box,
+        # without the user having to do anything, but since this endpoint can be used to
+        # mess with the server, we don't want it active by default.
         return app.config.get( "CONTROL_TESTS_PORT", os.environ.get("CONTROL_TESTS_PORT") )
 
     # check if the test control service should be made available

asl_rulebook2/webapp/rule_info.py

@@ -116,7 +116,7 @@ def init_qa( startup_msgs, logger ):
 # ---------------------------------------------------------------------
 
 def init_annotations( startup_msgs, logger ):
-    """Initialize the user-defined annoations."""
+    """Initialize the user-defined annotations."""
 
     # initialize
     global _user_anno

doc/extend.md

@@ -36,9 +36,9 @@ All the files should have the same base filename e.g.
 - kgs.targets
 - etc...
 
-### Adding Q+A, errata, user annoations, ASOP
+### Adding Q+A, errata, user annotations, ASOP
 
-This is described [here](../asl_rulebook2/webapp/tests/fixtures/full/).
+This is described in `$/asl_rulebook2/webapp/tests/fixtures/full/`.
 
 *NOTE: If you add Q+A, there is a tool in `$/asl_rulebook2/bin/qa-helper/` to help with the process.*
 

doc/features/index.html

@@ -28,15 +28,15 @@
 <p> <img src="images/search-cellar.png" class="imageZoom" style="float:right;width:40%;margin-left:1em;">
 <h2> Adding rules for other modules </h2>
 <p> Once you've got the program up and running, you can then think about extending it. It's a lot of work, but the results are insanely cool!
-<p> To the right, I searched for "cellar", and the program has found results from <em>Red Barricades</em>. The rules for this are referenced in the ASLRB index, but the content is not yet in the MMP eASLRB.
-<p> However, I added a PDF scan of the rules, plus information about where each rule is within that PDF (a <em>"targets file"</em>), and so when I click on the <span class="ruleid">O3.3</span> search result, it seamlessly opens the <em>Red Barricades</em> PDF and jumps to that rule.
+<p> To the right, I've searched for <em>"cellar"</em>, and the program has found results from <em>Red Barricades</em>. The rules for this are referenced in the ASLRB index, but the content is not yet in the MMP eASLRB.
+<p> However, I've installed a PDF scan of the rules, plus information about where each rule is within that PDF (a <em>"targets file"</em>), and so when I click on a search result, it seamlessly opens the <em>Red Barricades</em> PDF and jumps to that rule.
 <br clear="all"> <br>
 
 <p> <img src="images/search-air-support.png" class="imageZoom" style="float:right;width:40%;margin-left:1em;">
-You can also include third-party modules that are not referenced in the ASLRB index, in this case, LFT's <em>Kampfgruppe Scherer</em>. I added an index for it, which is then also searched. As with <em>Red Barricades</em>, I also added a PDF scan of the rules, and a targets file that specifies the location of each rule, and clicking on the <span class="ruleid">KGS CG9</span> search result takes me directly to that rule in the KGS PDF.
+You can also include third-party modules that are not referenced in the ASLRB index. I've also installed a PDF of LFT's <em>Kampfgruppe Scherer</em>, a targets files for it, and also an <em>index file</em>. This last file is also searched, and clicking on a search result takes me directly to the associated rule in the KGS PDF.
 <br>
 
-<p> I also added information about chapters in the PDF's, so that I can browse through them in the usual way: <br>
+<p> I've also added information about chapters in the PDF, so that I can browse through them in the usual way: <br>
 <img src="images/chapters-extended.png" class="imageZoom" style="margin:1em 0 0 2em;width:30%;">
 
 <br><br>

doc/prepare.md

@@ -49,13 +49,12 @@ Finally, we need to fixup some issues in the PDF:
         --output /tmp/prepared/ASL\ Rulebook.pdf \
         --progress
 ```
-This rotates any landscape pages, so that the browser shows pages at the correct width (without a horizontal scrollbar).
+This rotates any landscape pages, so that the browser shows pages at the correct width (without a horizontal scrollbar), and optimizes the PDF for use in a browser.
 
 ### Using the prepared files
 
 You should now have 6 files (the 5 extracted data files, plus the fixed-up PDF), which can be passed in to the program e.g.
 ```
     ./run-container.sh \
-        --port 5020 \
         --data /tmp/prepared/
 ```