style(tutorials): Standardising sub-headings and layout

As part of r-devel#191 the style of sub-headings for instructions in the `docs/tutorials/` section.

Level 4 markdown headings have been used, where numbering is required these have been included as the number followed by
a period.

Two pages (`multi_r_compilation.md` and `running_r.md`) had paragraphs numbered. These have had short section headers
added and the text follows as paragraphs afterwards.

docs/tutorials/building_r.md

@@ -1,5 +1,5 @@
 <!-- markdownlint-disable MD036 -->
-**1) Environment variables**
+#### 1. Environment variable
 
 - We have environment variables defining paths to directories for building R and
   storing the source code.
@@ -10,7 +10,7 @@
 
     ![alt text](../assets/rdev6.png)
 
-**2) svn checkout**
+#### 2. svn checkout
 
 - The svn checkout command lets us create a local copy of a specific tag/branch
   of a repository.
@@ -26,7 +26,7 @@
 
     ![alt text](../assets/rdev8.png)
 
-**3) Download recommended packages for R**
+#### 3. Download recommended packages for R
 
 To build R with the recommended packages, we need to run the
 `tools/rsync-recommended` script from the source directory to download the
@@ -38,7 +38,7 @@ $TOP_SRCDIR/tools/rsync-recommended
 
 ![alt text](../assets/rdev9.png)
 
-**4) Change to the build directory**
+#### 4. Change to the build director
 
 - To keep the source directory clean, we change to a build directory to
   configure and build R.
@@ -55,7 +55,7 @@ mkdir -p $BUILDDIR
 cd $BUILDDIR
 ```
 
-**5) Configure the build**
+#### 5. Configure the build
 
 - After we change directory, we must run the configure script from the source
 directory.  This step takes ~1 minute on the codespace.
@@ -77,7 +77,7 @@ $TOP_SRCDIR/configure --with-valgrind-instrumentation=1
 
     ![alt text](../assets/rdev7.png)
 
-**6) Build R**
+#### 6. Build
 
 Having configured R, we run `make` to build R. This take 5-10 minutes on the
 codespace.
@@ -86,19 +86,19 @@ codespace.
 make
 ```
 
-**7) Check R**
+#### 7. Check R
 
 Check that the build of R passes R's standard checks:
 
 ```bash
 make check
 ```
 
-This takes a couple of minutes in the codespace. The check will stop with a
+This takes a couple of minutes in the codespace. The check will stop with an
 error message if any of the tests fail. If this happens, see [SVN
 Help](./svn_help.md) for how to revert to a version that passes check.
 
-**8) Make R terminals use the built R**
+#### 8) Make R terminals use the built R
 
 Run the `which_r` script to set which R to use for R terminals in VSCode. When
 prompted, enter the number corresponding to `r-devel`
@@ -122,7 +122,7 @@ built![^1]
 selected version is saved in the VSCode settings, so will be saved when you stop
 and restart the codespace.
 
-**9) Make contributions**
+#### 9) Make contributions
 
 - After having built the current development version of R, we can now make
   changes to the source code and contribute to the project.

docs/tutorials/multi_r_compilation.md

@@ -10,62 +10,66 @@ It can be helpful to work with multiple versions of R:
 
 You can build multiple R versions in the same Codespaces environment.
 
-1. First choose a name for the R version. This will be used to identify the
-    version and to name the build/source directory. By default, we use the name
-    `r-devel` and the environment variables `BUILDDIR` and `TOP_SRCDIR` are set
-    to match.
+#### 1.Choose a name
 
-    For illustration, we will use `r-devel-raw`, which you might use to name a
-    version of R that you never modify.
+First choose a name for the R version. This will be used to identify the `r-devel`
+and the environment variables `BUILDDIR` and `TOP_SRCDIR` are set to match.
 
-2. You can set the `BUILDDIR` and `TOP_SRCDIR` environment variables to match
-    your chosen name using the `set_build_r` function:
+For illustration, we will use `r-devel-raw`, which you might use to name a
+version of R that you never modify.
 
-    - Open a terminal in the codespace.
+#### 2. Set environment variables
 
-    - Run the `set_build_r` function with your chosen name as the argument, e.g.
+You can set the `BUILDDIR` and `TOP_SRCDIR` environment variables to match your
+chosen name using the `set_build_r` function:
 
-        ```bash
-        set_build_r r-devel-raw
-        ```
+- Open a terminal in the codespace.
 
-        The new values of the environment variables will be printed as
-        confirmation:
+- Run the `set_build_r` function with your chosen name as the argument, e.g.
 
-        ```bash
-        BUILDDIR is now set to /workspaces/r-dev-env/build/r-devel-raw
-        TOP_SRCDIR is now set to /workspaces/r-dev-env/svn/r-devel-raw
-        ```
+```bash
+set_build_r r-devel-raw
+```
 
-3. If you have an unmodified build of R-devel using the default name of
-    `r-devel`, you can simply copy the sources and the build to the new
-    directories with `rsync`:
+The new values of the environment variables will be printed as confirmation:
 
-    ```bash
-    rsync -a "$(dirname "$BUILDDIR")/r-devel/"* $BUILDDIR
-    rsync -a "$(dirname "$TOP_SRCDIR")/r-devel/"* $TOP_SRCDIR
-    ```
+```bash
+BUILDDIR is now set to /workspaces/r-dev-env/build/r-devel-raw
+TOP_SRCDIR is now set to /workspaces/r-dev-env/svn/r-devel-raw
+```
 
-    Otherwise you can follow the steps in the [Building R](./building_r.md)
-    tutorial to checkout the R sources and build R using the new source and
-    build directories.
+#### 3. Synchronise builds
 
-4. Once you have a build of R under the new build directory, you will see your
-    chosen name in the choices when running the `which_r` script to select the
-    version of R to run in new terminals, e.g.
+If you have an unmodified build of R-devel using the default name of
+directories with `rsync`:
 
-    ```bash
-    which_r
-    ```
+```bash
+rsync -a "$(dirname "$BUILDDIR")/r-devel/"* $BUILDDIR
+rsync -a "$(dirname "$TOP_SRCDIR")/r-devel/"* $TOP_SRCDIR
+```
 
-    ```bash
-    Which version of R should be used in new R terminals?
-      1. R 4.4.0 (release version built into this container)
-      Additional R builds available:
-        2. r-devel
-        3. r-devel-raw
+Otherwise you can follow the steps in the [Building R](./building_r.md)
+tutorial to checkout the R sources and build R using the new source and
+build directories.
+
+4. Check your build is available
+
+Once you have a build of R under the new build directory, you will see your
+chosen name in the choices when running the `which_r` script to select the
+version of R to run in new terminals, e.g.
+
+```bash
+which_r
+```
+
+```bash
+Which version of R should be used in new R terminals?
+1. R 4.4.0 (release version built into this container)
+Additional R builds available:
+2. r-devel
+3. r-devel-raw
     Enter the number corresponding to the selected version:
-    ```
+```
 
 !!! Note
 

docs/tutorials/patch_update.md

@@ -4,13 +4,13 @@ a change to R, e.g. a fix for a bug.
 
 To make a patch
 
-1) Update your local copy of the source
+#### 1. Update your local copy of the source
 
 If you have not recently updated your local copy of the R Subversion repository,
 follow the instructions in [Updating the Source Code](./update_source.md) to do
 this first.
 
-2) Create a patch file
+#### 2. Create a patch file
 
 Go to the source directory and use `svn diff` to create a patch.
 

docs/tutorials/running_r.md

@@ -1,20 +1,25 @@
 
-1) Create a file in VS Code ending with a .R extension. You can create new files
+#### 1. Create a new file
+
+Create a file in VS Code ending with a .R extension. You can create new files
 by clicking on the new file icon in VS Code Explorer, or use the `code` command
 in the terminal to create and open an R file
 
 ```bash
 code R/test.R
 ```
 
-![alt text](../assets/rdev4.png)
+![Screen shot of VSCode running the Containerised R Development Environment.](../assets/rdev4.png)
 
-2) You should see `R:(not attached)` in the Status Bar at the bottom of the
+You should see `R:(not attached)` in the Status Bar at the bottom of the
 VSCode window.
 
-![alt text](../assets/rdev11.png)
+![Status bar of VSCode showing message that `R:(not attached)`.](../assets/rdev11.png)
+
+#### 2. Launch R
 
-3) Click on the `R:(not attached)` link to launch an R terminal. You can then
+Click on the `R:(not attached)` link to launch an R terminal. You can then
 send code from the `.R` file to the R terminal by pressing `cmd/ctrl + enter`.
 
-![alt text](../assets/rdev12.png) ![alt text](../assets/rdev5.png)
+![Screen shot of R session running in the Terminal tab of VSCode.](../assets/rdev12.png)
+![VSCode screen shot showing R terminal and plot in a separate tab.](../assets/rdev5.png)

docs/tutorials/update_source.md

@@ -3,27 +3,27 @@ multiple times a day. It's a good idea to update your local copy of the source
 code from time to time, especially before creating a patch. To do so, follow
 these steps:
 
-#### 1) Close R terminal
+#### 1. Close R terminal
 
 If you have an R terminal open, quit R or close the terminal.
 
-#### 2) Go to the source directory
+#### 2. Go to the source directory
 
 In a bash terminal, change to the source directory
 
 ```bash
 cd $TOP_SRCDIR
 ```
 
-#### 3) Review local changes
+#### 3. Review local changes
 
 Use the Subversion diff command to review changes you have made to source code
 
 ```bash
 svn diff
 ```
 
-#### 4) Revert changes (optional)
+#### 4. Revert changes (optional)
 
 If you no longer want to keep your local changes, you can revert them.
 
@@ -45,7 +45,7 @@ Revert all local changes
 svn revert -R .
 ```
 
-#### 5) Rebuild and check with any local changes
+#### 5. Rebuild and check with any local changes
 
 If you have no local changes remaining, skip to the next step.
 
@@ -66,7 +66,7 @@ to continue
 cd $TOP_SRCDIR
 ```
 
-#### 6) Update using svn
+#### 6. Update using svn
 
 Use the Subversion command `update` to update your local copy with the latest
 changes by the R Core Team.
@@ -75,7 +75,7 @@ changes by the R Core Team.
 svn update
 ```
 
-#### 7)  Rebuild and check with the updates
+#### 7.  Rebuild and check with the updates
 
 To rebuild R with the latest changes from the R Core Team and any local changes
 you have kept, go to the build directory to build and check R