updated full vm guide hero

docs/hero_mdbook_fullvm.md

@@ -6,17 +6,17 @@
 - [Setting the Full VM](#setting-the-full-vm)
   - [Remote Explorer Access](#remote-explorer-access)
 - [Set the SSH Key Pair](#set-the-ssh-key-pair)
-- [Install hero, crysallib and V](#install-hero-crysallib-and-v)
+- [Install Hero, Crystallib and V](#install-hero-crystallib-and-v)
 - [Use Hero to Generate mdbooks](#use-hero-to-generate-mdbooks)
 - [Troubleshooting](#troubleshooting)
-  - [Fix the error: "cli execution error: Cannot pull repo: /root/code/git.ourworld.tf/tfgrid/info\_tfgrid because there are changes in the dir."](#fix-the-error-cli-execution-error-cannot-pull-repo-rootcodegitourworldtftfgridinfo_tfgrid-because-there-are-changes-in-the-dir)
+  - [Fix the error: "cli execution error: Cannot pull repo..."](#fix-the-error-cli-execution-error-cannot-pull-repo)
   - [Fix: Git hangs at "Cloning into..."](#fix-git-hangs-at-cloning-into)
 
 ***
 
 ## Introduction
 
-In this tutorial, we show all the steps to deploy an mdbook with the [hero](https://github.com/freeflowuniverse/crystallib/tree/development/cli/hero) tool. 
+In this tutorial, we show all the steps to deploy an mdbook with the [Hero](https://github.com/freeflowuniverse/crystallib/tree/development/cli/hero) tool. 
 
 For this guide, we show an example using the mdbook from the repository [info_tfgrid](https://git.ourworld.tf/tfgrid/info_tfgrid). This setup can be done locally or on a VM. Note that it should be run as root. 
 
@@ -26,7 +26,7 @@ We will be using SSH to connect to the VM and to create an SSH tunnel between th
 
 To manage the mdbook files, we will be using the remote explorer feature of either VSCodium or VSCode.
 
-We include some troubleshooting tips from testing the installation.
+We also include some troubleshooting tips.
 
 ## Setting the Full VM 
 
@@ -61,18 +61,18 @@ You can use the remote explorer feature of both [VSCode](https://marketplace.vis
 ## Set the SSH Key Pair
 
 - Generate an SSH key pair
-  - To make it work with info_tfgrid, use books for the filename
+  - To make it work with info_tfgrid, save it here: `/root/.ssh/books`
 ```
-ssh-keygen # save in /root/.ssh/books
+ssh-keygen
 ```
 - Note the public key
 ```
-cat ~/.ssh/books.pub
+cat /root/.ssh/books.pub
 ```
 - Add the SSH public key on [git.ourworld.tf](https://git.ourworld.tf/user/settings/keys) and [github](https://github.com/settings/keys)
-  - Optional: on git.ourworld.tf, verify the key
+  - Optional: on git.ourworld.tf, verify the key. Make sure to put the proper token.
 ```
-echo -n 'token' | ssh-keygen -Y sign -n gitea -f /path/to/private/key
+echo -n 'token' | ssh-keygen -Y sign -n gitea -f /root/.ssh/books
 ```
 - Start the ssh agent
 ```
@@ -83,7 +83,9 @@ eval $(ssh-agent)
 ssh-add /root/.ssh/books
 ```
 
-## Install hero, crysallib and V
+## Install Hero, Crystallib and V
+
+We install hero, Crystallib and V with a script.
 
 ```
 curl https://raw.githubusercontent.com/freeflowuniverse/crystallib/development/scripts/build_hero.sh > /tmp/build_hero.sh
@@ -92,32 +94,59 @@ bash /tmp/build_hero.sh
 
 ## Use Hero to Generate mdbooks
 
+We generate mdbooks with Hero.
+
+Download the git repository from a URL:
+
 - Download the repository
 ```
 hero mdbook -u https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/heroscript/bookname -gp
 ```
+  - The line above will clone the repository `info_tfgrid` at the path `/root/code/git.ourworld.tf/tfgrid`. The same result can be obtained by running the following lines:
+    ```
+    mkdir -p /root/code/git.ourworld.tf/tfgrid
+    cd /root/code/git.ourworld.tf/tfgrid
+    git clone https://git.ourworld.tf/tfgrid/info_tfgrid
+    ```
+
+For the next steps, you can either run the commands locally (with -p and the proper path) or remotely (with -u and the proper URL). Running the command locally is useful when you are doing changes to the mdbook and you want to test them before pushing the new files to the remote repository.
+
 - Build the book
+  - Option 1: Build the book with a URL
   ```
   hero mdbook -u https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/heroscript/bookname
   ```
-- Open the mdbook on your local browser:
+
+  - Option 2: Build the book with a local path
+  ```
+  hero mdbook -p /path/to/tfgrid/info_tfgrid/src/branch/main/heroscript/bookname
+  ```
+
+- Open the book
+  - Option 1: Open the mdbook on your local browser with a URL:
 
   ```
   hero mdbook -u https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/heroscript/bookname -o 
   ```
 
-> Note: In both cases, make sure to replace **bookname** by the name of your book, e.g. test.
+  - Option 2: Open the mdbook on your local browser with a local path:
 
-To see the mdbook online on a local browser (via the file **index.html**), run the following command and open a browser with the URL **localhost:5173**. Make sure to replace `<book_name>` with the name of the book.
+  ```
+  hero mdbook -p /path/to/tfgrid/info_tfgrid/src/branch/main/heroscript/bookname -o 
+  ```
+
+> Note: In all cases, make sure to replace **bookname** by the name of your book, e.g. test.
+
+To preview the mdbook on a local browser (via the file **index.html**), run the following command and open a browser with the URL **localhost:5173**. Make sure to replace `<book_name>` with the name of the book.
 ```
 pushd /root/hero/www/info/<book_name>/;  python3 -m http.server 5173; popd; 
 ```
 
 ## Troubleshooting
 
-### Fix the error: "cli execution error: Cannot pull repo: /root/code/git.ourworld.tf/tfgrid/info_tfgrid because there are changes in the dir."
+### Fix the error: "cli execution error: Cannot pull repo..."
 
-Remove then rerun the command
+If you get the following error: "cli execution error: Cannot pull repo: /root/code/git.ourworld.tf/tfgrid/info_tfgrid because there are changes in the dir.", you can try the following as a fix:
 
 ```
 rm -r /root/code/git.ourworld.tf/tfgrid/info_tfgrid
@@ -137,4 +166,3 @@ If it happens another time, you can try to download it manually:
 mkdir -p /root/code/git.ourworld.tf/tfgrid && cd $_
 git clone https://git.ourworld.tf/tfgrid/info_tfgrid
 ```
-