Docs/improve formatting v2

docs/container_setup/github_codespace/creating_codespace.md

@@ -1,21 +1,30 @@
+# Creating a GitHub Codespace
+
+Follow these steps to create a new codespace:
+
+1. Navigate to the [r-dev-env repo](https://github.com/r-devel/r-dev-env)
+2. Click 'Open in GitHub Codespaces'
+3. Click 'Create Codespace'
 
-1. From the main branch of the [r-dev-env
-repo](https://github.com/r-devel/r-dev-env/tree/main), click on the 'Open in
-GitHub Codespaces' button and then click the green 'Create Codespace' button.
 ![create codespace](../../assets/rdev1.png)
 
-    !!! Note You will see the message "Codespace usage for this repository is
-        paid for by ...", with your username. Don't panic!
+!!! Note "About Codespace Billing"
+    You will see "Codespace usage for this repository is paid for by [user]".
+    Don't worry!
+
+    - GitHub Codespaces: 120 core hours free per month
+    - Free hours = 120 / number of cores
+    - Default: 4 cores = 30 hours free per month
+    - Core count can be adjusted
 
-        GitHub Codespaces offers 120 core hours of free usage per month for every GitHub user. So the actual number of free hours is 120 divided by the number of cores you are using to run your codespaces.
-        For the r-dev-env codespace we have set the codespace usage to 4 cores which leads to 30hrs of free usage per month. This can be changed according to your preference.
+    **Resources:**
+    - [Billing Docs](https://github.com/features/codespaces)
+    - [Pricing Calculator](https://github.com/pricing/calculator)
+    - [Billing Page](https://github.com/settings/billing)
 
-        For more details about codespaces billing, see the [Codespaces Billing Docs](https://github.com/features/codespaces).
-        You can calculate your GitHub services usage with the [GitHub Services
-        Pricing Calculator](https://github.com/pricing/calculator) and check your usage allowance under "Codespaces" on your [GitHub Billing page](https://github.com/settings/billing).
+## Setup
 
-2. The codespace setup screen will then be shown. Starting the container may
-   take a minute or so.
+1. Wait for codespace setup (about 1 minute)
+2. You'll be redirected to VSCode:
 
-3. You will be taken to a VSCode editor within your browser.
 ![codespace](../../assets/rdev3.png)

docs/tutorials/building_r.md

@@ -1,133 +1,112 @@
-<!-- markdownlint-disable MD036 -->
-**1) Environment variables**
+# Building R from Source
 
-- We have environment variables defining paths to directories for building R and
-  storing the source code.
-- `BUILDDIR` defines the build directory: `/workspaces/r-dev-env/build/r-devel`.
-- `TOP_SRCDIR` defines the source directory: `/workspaces/r-dev-env/svn/r-devel`
-- The environment variables are set in the codespace image and are available
-  when the codespace starts.
+## 1. Environment Variables
 
-    ![alt text](../assets/rdev6.png)
+The following environment variables define paths for building R:
 
-**2) svn checkout**
+- `BUILDDIR`: `/workspaces/r-dev-env/build/r-devel`
+- `TOP_SRCDIR`: `/workspaces/r-dev-env/svn/r-devel`
 
-- The svn checkout command lets us create a local copy of a specific tag/branch
-  of a repository.
-- We can check out the latest version of the trunk (the main branch) of the R
-  sources to $TOP_SRCDIR as follows:
+These variables are set in the codespace image and available at startup.
 
-    ```bash
-    svn checkout https://svn.r-project.org/R/trunk/ $TOP_SRCDIR
-    ```
+## 2. SVN Checkout
 
-- Output : We get file structure something like this after checking out R source
-  code from R svn repository.
+Get a local copy of R source code from the repository:
 
-    ![alt text](../assets/rdev8.png)
+```console
+$ svn checkout https://svn.r-project.org/R/trunk/ $TOP_SRCDIR
+A    trunk/COPYING
+A    trunk/INSTALL
+...
+Checked out revision 86543.
+```
 
-**3) Download recommended packages for R**
+## 3. Download Packages
 
-To build R with the recommended packages, we need to run the
-`tools/rsync-recommended` script from the source directory to download the
-source code for these packages:
+Get recommended packages:
 
-```bash
-$TOP_SRCDIR/tools/rsync-recommended
+```console
+$ $TOP_SRCDIR/tools/rsync-recommended
+downloading recommended packages
+trying URL 'https://cran.r-project.org/src/contrib/Recommended/MASS_7.3-60.tar.gz'
+...
+** building package indices
+** testing if installed package can be loaded from temporary location
+** testing if installed package can be loaded from final location
+** testing if installed package keeps a record of temporary installation path
+* DONE
 ```
 
-![alt text](../assets/rdev9.png)
+## 4. Set Up Build Directory
 
-**4) Change to the build directory**
+Keep source directory clean by using a separate build directory:
 
-- To keep the source directory clean, we change to a build directory to
-  configure and build R.
+1. Create build directory:
 
-- First create the directory specified by the BUILDDIR environment variable.
-
-```bash
-mkdir -p $BUILDDIR
-```
+   ```bash
+   mkdir -p $BUILDDIR
+   ```
 
-- Then we can change directory from root to the build directory.
+2. Change to build directory:
 
-```bash
-cd $BUILDDIR
-```
+   ```bash
+   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.
-
-```bash
-$TOP_SRCDIR/configure --with-valgrind-instrumentation=1
+Run configure (~1 minute):
 
+```console
+$ $TOP_SRCDIR/configure --with-valgrind-instrumentation=1
+checking build system type... x86_64-pc-linux-gnu
+checking host system type... x86_64-pc-linux-gnu
+...
+config.status: creating po/Makefile
+config.status: creating src/include/config.h
 ```
 
-<!-- markdownlint-disable MD046 -->
 !!! Note
-    The `--with-valgrind-instrumentation` option is set to 1 for effective use
-    of valgrind. See the [Using
-    valgrind](https://cran.r-project.org/doc/manuals/R-exts.html#Using-valgrind)
-    section of the R-admin manual for more information.
-<!-- markdownlint-enable MD046 -->
-
-- The configure cmd prepares for building R, creating files and folders inside
-  the BUILDDIR directory.
-- Output : We get file structure something like this after using configure
-  command.
+    The `--with-valgrind-instrumentation` option enables effective use of
+    valgrind. See the [docs](https://cran.r-project.org/doc/manuals/R-exts.html#Using-valgrind)
+    for details.
 
-    ![alt text](../assets/rdev7.png)
+## 6. Build R
 
-**6) Build R**
-
-Having configured R, we run `make` to build R. This take 5-10 minutes on the
-codespace.
+Build R (5-10 minutes):
 
 ```bash
 make
 ```
 
-**7) Check R**
+## 7. Run Tests
 
-Check that the build of R passes R's standard checks:
+Run standard tests:
 
 ```bash
 make check
 ```
 
-This takes a couple of minutes in the codespace. The check will stop with a
-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.
+If tests fail, see [SVN Help](./svn_help.md).
 
-**8) Make R terminals use the built R**
+## 8. Configure R Terminal
 
-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`
+Set R version for VSCode:
 
-```bash
-which_r
-```
-
-```bash
+```console
+$ which_r
 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
+1. R 4.4.0 (release version built into this container)
+Additional R builds available:
+  2. r-devel
 Enter the number corresponding to the selected version:
 ```
 
-This means that new R terminals will use the version of R you have just
-built![^1]
+Select `r-devel` to use your built version.[^1]
 
-[^1]: To switch back to the release version, run `which_r` and type `1`. The
-selected version is saved in the VSCode settings, so will be saved when you stop
-and restart the codespace.
+[^1]: To switch back to release version, run `which_r` and select `1`.
+    Selection persists across restarts.
 
-**9) Make contributions**
+## 9. Next Steps
 
-- After having built the current development version of R, we can now make
-  changes to the source code and contribute to the project.
-- Follow the [R Contribution Workflow](./contribution_workflow.md) tutorial to
-  learn how to do this.
+Start contributing! Follow the [R Contribution Workflow](./contribution_workflow.md).

docs/tutorials/contribution_workflow.md

@@ -1,48 +1,48 @@
-#### 1. Example Contribution Workflow using the R Dev Container
+# Example Contribution Workflow using the R Dev Container
 
-- To start working in R we will click on `R:(not attach)` which is in the bottom
-  right of the VSCode window. This will open an R terminal for us.
+## 1. Starting R
 
-    ![alt text](../assets/rdev11.png)
+- To start working in R, click on `R:(not attach)` in the bottom right of
+  VSCode. This will open an R terminal.
 
-    ![alt text](../assets/rdev12.png)
+![alt text](../assets/rdev11.png)
 
-- We can now run R commands. We will use the `utils::askYesNo()` function as an
-  example
+![alt text](../assets/rdev12.png)
 
-    ![alt text](../assets/rdev19.png)
+- We can now run R commands. We will use the `utils::askYesNo()` function as
+  an example:
 
 ```R
-    > askYesNo("Is this a good example?")
-    Is this a good example? (Yes/no/cancel) Yes
-    [1] TRUE
+> askYesNo("Is this a good example?")
+Is this a good example? (Yes/no/cancel) Yes
+[1] TRUE
 ```
 
-#### 2. Editing Source Code
+## 2. Editing Source Code
 
-- Edit the source code of `utils::askYesNo()` to change the default options. The
-  source code can be found in `$TOP_SRCDIR/src/library/utils/R/askYesNo.R`.
-- You can redirect to that file using
+- Edit the source code of `utils::askYesNo()` to change the default options.
+  The source code is in `$TOP_SRCDIR/src/library/utils/R/askYesNo.R`.
+- You can redirect to that file using:
 
 ```bash
 code $TOP_SRCDIR/src/library/utils/R/askYesNo.R
 ```
 
-**> Before edit:** ![alt text](../assets/rdev20.png)
+### Before and After Edit
+
+#### Before edit
 
 ```R title="askYesNo.R" linenums="20"
-    prompts = getOption("askYesNo", gettext(c("Yes", "No", "Cancel"))),
+prompts = getOption("askYesNo", gettext(c("Yes", "No", "Cancel"))),
 ```
 
-**> With edit (for example - change to whatever you like!):**
-
-![alt text](../assets/rdev21.png)
+#### After edit
 
 ```R title="askYesNo.R" linenums="20"
-    prompts = getOption("askYesNo", gettext(c("Oh yeah!", "Don't think so", "Cancel"))),
+prompts = getOption("askYesNo", gettext(c("Oh yeah!", "Don't think so", "Cancel"))),
 ```
 
-#### 3. Rebuild R
+## 3. Rebuilding R
 
 - We can re-build R with our changes. Since we have only modified the utils
   package, rebuilding R will only re-build the utils package.
@@ -61,21 +61,17 @@ cd $BUILDDIR
 make
 ```
 
-![alt text](../assets/rdev22.png)
-
-- Optionally run `make check` to run R's test suite with your local changes. You
-  may skip this step while you are iterating on a bug fix or other development,
+- Optionally run `make check` to run R's test suite with your local changes.
+  You may skip this step while iterating on a bug fix or other development,
   until you are ready to [create a patch](./patch_update.md).
 
 - To use the re-built R, simply open a new R terminal.
 
-#### 4. Cross check and Re-running Code
+## 4. Cross-checking Changes
 
-- Check the edit has worked as expected by re-running the example code: ![alt
-text](../assets/rdev23.png)
+- Check the edit has worked as expected by re-running the example code:
 
 ```R
-    > askYesNo("Is this a good example?")
-    Is this a good example? (Oh yeah!/don't think so/cancel) Oh yeah!
-    [1] TRUE
-```
+> askYesNo("Is this a good example?")
+Is this a good example? (Oh yeah!/don't think so/cancel) Oh yeah!
+[1] TRUE

docs/tutorials/running_r.md

@@ -1,20 +1,24 @@
+1. 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:
 
-1) 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
+```console
+de R/test.R
 ```
 
-![alt text](../assets/rdev4.png)
+2. You should see `R:(not attached)` in the Status Bar at the bottom of the
+   VSCode window. Click on the `R:(not attached)` link to launch an R terminal.
 
-2) You should see `R:(not attached)` in the Status Bar at the bottom of the
-VSCode window.
+3. You can then send code from the `.R` file to the R terminal. For example:
 
-![alt text](../assets/rdev11.png)
+```R
+# In test.R
+print("Hello R Development!")
+```
 
-3) 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`.
+```Rconsole
+> print("Hello R Development!")
+[1] "Hello R Development!"
+```
 
-![alt text](../assets/rdev12.png) ![alt text](../assets/rdev5.png)
+You can send code from the editor to the R terminal by pressing `cmd/ctrl + enter`.