Docs cleanup

Author: rustprooflabs

docs/src/update-mode.md

@@ -1,56 +1,56 @@
 # Using Update Mode
 
-Running in experimental Update mode enables using osm2pgsql's `--append`
-option.
+Running with `--update` enables using osm2pgsql's `--append` option to load a second
+input file. The PgOSM Flex functionality uses `--update create` and `--update append`.
+See the discussion in [#275](https://github.com/rustprooflabs/pgosm-flex/issues/275)
+for more context behind the intent for this feature.
+
+Using `--update append` requires the initial import used `--update create`. Attempting
+to use `--update append` without first using `--update create` results in the error:
+"ERROR: This database is not updatable. To create an updatable database use --slim (without --drop)."
+
+
+If your goal is to easily refresh the data for a single, standard region/sub-region
+you should investigate the [`--replication` feature](/replication.md). Using
+replication is the easier and more efficient way to maintain data.
+
 
 > Note: This is **not** the `--append` option that existed in PgOSM Flex 0.6.3 and prior.
 
+## Example
+
 The following command uses `--update create` to load the `district-of-columbia`
-sub-region.
+sub-region. This example assumes you have set the environment variables and
+have ran the docker container as shown in the [Quick Start](quick-start.md) section.
 
 ```bash
 docker exec -it \
     pgosm python3 docker/pgosm_flex.py \
     --ram=8 \
     --region=north-america/us \
     --subregion=district-of-columbia \
-    --skip-nested \
     --update create
 ```
 
-The following loads a second sub-region (`new-hampshire`) using `--update append`.
+The following loads a second sub-region (`maryland`) using `--update append`.
 
 ```bash
 time docker exec -it \
     pgosm python3 docker/pgosm_flex.py \
     --ram=8 \
     --region=north-america/us \
-    --subregion=new-hampshire \
-    --skip-nested --skip-dump \
+    --subregion=maryland \
     --update append
-
-...
-
-2022-12-27 10:14:26,792:INFO:pgosm-flex:helpers:2022-12-27 10:14:26  osm2pgsql took 1420s (23m 40s) overall.
-2022-12-27 10:14:26,832:INFO:pgosm-flex:pgosm_flex:osm2pgsql completed
-2022-12-27 10:14:26,832:INFO:pgosm-flex:pgosm_flex:Running with --update append: Skipping post-processing SQL
-2022-12-27 10:14:26,832:INFO:pgosm-flex:pgosm_flex:Skipping pg_dump
-2022-12-27 10:14:26,832:INFO:pgosm-flex:pgosm_flex:PgOSM Flex complete!
-
-real	23m47.564s
-user	0m0.083s
-sys	0m0.025s
-
 ```
 
-It seems to work, new output at the end: `Skipping post-processing SQL`.
-
-Verified that both New Hampshire and D.C. regions were loaded in `osm.place_polygon`.
 
 
 ## Smaller test
 
-Put the following into `~/pgosm-data/extracts/colorado-extract.json`:
+> This section has notes that probably belong elsewhere but I'm leaving them here for now.
+> They were initially helpful for testing the logic for this functionality.
+
+Put the following into `~/pgosm-data/extracts/colorado-extract.json`.
 
 ```json
 {
@@ -81,14 +81,14 @@ Put the following into `~/pgosm-data/extracts/colorado-extract.json`:
 ```
 
 
-Create Boulder and Longmont extracts.
+Create Boulder and Longmont extracts using `osmium extract`.
 
-```
+```bash
 osmium extract -c extracts/colorado-extracts.json colorado-2022-12-27.osm.pbf
 ```
 
 
-```
+```bash
 ryanlambert@tag201:~/pgosm-data$ ls -alh | grep boulder
 -rw-rw-r--  1 ryanlambert ryanlambert 2.4M Dec 27 14:31 colorado-boulder-latest.osm.pbf
 ryanlambert@tag201:~/pgosm-data$ ls -alh | grep longmont
@@ -97,24 +97,24 @@ ryanlambert@tag201:~/pgosm-data$ ls -alh | grep longmont
 
 Takes 11 seconds.
 
-```
-time docker exec -it \
+```bash
+docker exec -it \
     pgosm python3 docker/pgosm_flex.py \
     --ram=8 \
     --region=north-america/us \
     --subregion=colorado-longmont --input-file colorado-longmont-latest.osm.pbf \
-    --skip-dump --update create
+    --update create
 ```
 
 Takes 2 minutes.
 
 
-```
-time docker exec -it \
+```bash
+docker exec -it \
     pgosm python3 docker/pgosm_flex.py \
     --ram=8 \
     --region=north-america/us \
     --subregion=colorado-boulder --input-file colorado-boulder-latest.osm.pbf \
-    --skip-dump --update append
+    --update append
 ```