MD-linting

src/ch2_00_installation.md

@@ -3,20 +3,30 @@
 Pick the appropriate subchapter for your operating system.
 
 ## Editor
+
 There is no requirement on which editor you should use,
 but if you are undecided VS code offers quite a few nice features,
 is free and highly customizable.
 
-It is also modular with a lot of extensions, including for example, the Rust core group maintained extension that is called ```Rust (rls)``` where you get all kinds of language-specific help such as code completion, IntelliSense, refactoring, reformatting, errors, snippets.
+It is also modular with a lot of extensions, including for example,
+the Rust core group maintained extension that is called ```Rust (rls)```
+where you get all kinds of language-specific help such as code completion,
+IntelliSense, refactoring, reformatting, errors, snippets.
 
 ### VS Code
 
-* Windows: Go to [VS Code for Windows](https://code.visualstudio.com/docs/setup/windows) and follow the instructions
+* Windows: Go to [VS Code for Windows](https://code.visualstudio.com/docs/setup/windows)
+* and follow the instructions
 
 * Linux: Use package manager of choice, see: [VS Code for Linux](https://code.visualstudio.com/docs/setup/linux)
 
 #### VS Code plugins
-When installed, go to the extensions tab and install ```Rust (rls)``` and ```Better TOML```.
 
-[Rust Analyzer](https://github.com/rust-analyzer/rust-analyzer) is an alternative to ```Rust (rls)```
+When installed, go to the extensions tab and install
+
+* ```Rust (rls)```
+* ```Better TOML```
+
+[Rust Analyzer](https://github.com/rust-analyzer/rust-analyzer)
+is an alternative to ```Rust (rls)```
 

src/ch2_01_linux_installation.md

@@ -9,20 +9,19 @@ in case of troubles see if a newer package is available in the `backports` repos
 
 Debian
 
-```
+```shell
 sudo apt install gdb-arm-none-eabi binutils-arm-none-eabi
 ```
 
 Ubuntu
 
-```
+```shell
 sudo apt install gcc-multilib gdb-multiarch binutils-multiarch
 ```
 
-
 Arch
 
-```
+```shell
 sudo pacman -S arm-none-eabi-gdb arm-none-eabi-binutils
 ```
 
@@ -30,13 +29,13 @@ sudo pacman -S arm-none-eabi-gdb arm-none-eabi-binutils
 
 Debian/Ubuntu
 
-```
+```shell
 sudo apt install openocd
 ```
 
 Arch
 
-```
+```shell
 sudo pacman -S openocd
 ```
 
@@ -44,14 +43,15 @@ sudo pacman -S openocd
 
 Go to [https://rustup.rs/](https://rustup.rs/) and follow the instructions.
 
-then add the required ARM target:
+Then add the required ARM target:
 
-```
+```shell
 rustup target add thumbv7em-none-eabihf
 ```
 
 ## Cargo tools
-```
+
+```shell
 cargo install cargo-binutils
 rustup component add llvm-tools-preview
 ```
@@ -59,7 +59,7 @@ rustup component add llvm-tools-preview
 ### If running Rust beta/nightly
 
 Use instead
-```
+
+```shell
 rustup component add llvm-tools
 ```
-

src/ch2_02_windows_installation.md

 # Windows Toolchain setup
 
-### Native
+## Native
 
-#### GDB
+### GDB - Native
+
+Go to [mingw.org](http://www.mingw.org/), download and install MinGW.
+In the MinGW Installation Manager select ```All Packages``` then mark for installation:
 
-Go to [mingw.org](http://www.mingw.org/), download and install MinGW. In the MinGW Installation Manager select ```All Packages``` then mark for installation:
 - mingw32-gcc-g++
 - mingw32-gdb (bin)
 - mingw32-gdb (doc)
@@ -12,72 +14,115 @@ Go to [mingw.org](http://www.mingw.org/), download and install MinGW. In the Min
 - mingw32-gdb (lic)
 - mingw32-gdb (man)
 
-then in the Installation menu choose ```Apply Changes```, you should see at the bottom of the window that there is going to be several packages in ```new/upgraded packages will be installed``` if so then click ```Apply```.
+then in the Installation menu choose `Apply Changes`,
+you should see at the bottom of the window that there is going to be
+several packages in `new/upgraded packages will be installed`
+if so then click `Apply`.
 
-If everything went as expected then you should have the ```gdb.exe``` file is your MinGW install folder under /bin. However to effectively use gdb you need to set the environment variable.
-Go to the Control panel -> System and Security -> System -> Advanced system settings, click the ```Environment Variables...``` button. In this window in the System variables view click ```Edit...``` then ```New``` and type in the path to the gdb.exe file (should be something like ```C:\MinGW\bin```). Then click OK in all the windows.
+If everything went as expected then you should have the `gdb.exe` file is
+your MinGW install folder under `/bin`.
+However to effectively use gdb you need to set the environment variable.
 
-To check that everything went as expected open a new terminal with ```CTRL+r``` and type cmd then ```ENTER```.
-If you now type ```gdb``` you should be prompted with a text saying something like "GNU gdb (GDB) 7.6.1", gdb is now installed!
+Go to the Control panel -> System and Security -> System -> Advanced system settings,
+click the `Environment Variables...` button.
 
-#### OpenOCD
+In this window in the System variables view click `Edit...` then `New`
+and type in the path to the `gdb.exe` file
+(should be something like ```C:\MinGW\bin```).
+Then click OK in all the windows.
+
+To check that everything went as expected open a new terminal with
+`CTRL+r` and type cmd then `ENTER`.
+
+If you now type `gdb` you should be prompted with a text saying something like
+"GNU gdb (GDB) 7.6.1".
 
-Go to [openocd](http://gnutoolchains.com/arm-eabi/openocd/) and download the latest OpenOCD package.
-Extract the package somewhere where it is easy to find (i.e C:). 
+GDB is now installed!
 
+#### OpenOCD
+
+Go to [openocd](http://gnutoolchains.com/arm-eabi/openocd/) and download the
+latest OpenOCD package. Extract the package somewhere where it is easy to find.
+(i.e C:).
 
 /// TODO ///
 
-### Windows Subsystem for Linux (WSL) - Windows 10 ONLY
+## Windows Subsystem for Linux (WSL) - Windows 10 ONLY
 
-To install WSL check out: [https://docs.microsoft.com/en-us/windows/wsl/install-win10](https://docs.microsoft.com/en-us/windows/wsl/install-win10). We recommend the Ubuntu distro.
+To install WSL check out: [https://docs.microsoft.com/en-us/windows/wsl/install-win10][2].
+We recommend the Ubuntu distro.
 
-To open a distro terminal: Ctrl+r and write ```cmd``` and run. In the terminal type ```bash```, this will spawn a ubuntu terminal.
+[2]: https://docs.microsoft.com/en-us/windows/wsl/install-win10
+
+To open a distro terminal: Ctrl+r and write `cmd` and run.
+In the terminal type `bash`, this will spawn a ubuntu terminal.
 
 Using the terminal, update the distro:
 
-```sudo apt update```
+```shell
+sudo apt update
 
-```sudo apt install build-essential```
+sudo apt install build-essential
 
-```sudo apt install gdb```
+sudo apt install gdb
 
-```sudo apt upgrade```
+sudo apt upgrade
+```
 
-The ordinary C: drive will be found under /mnt/c
+The ordinary `C:` drive will be found under `/mnt/c`
 
-#### Rust
+### Rust
 
-Go to [https://rustup.rs/](https://rustup.rs/) and follow the instructions, run the command inside WSL.
+Go to [https://rustup.rs/](https://rustup.rs/) and follow the instructions,
+run the installation command inside WSL.
 
-then add the required ARM target:
+To add the required ARM target:
 
-```
+```shell
 rustup target add thumbv7em-none-eabihf
 ```
 
-##### Cargo tools
-```
+#### Cargo tools
+
+```shell
 cargo install cargo-binutils
 rustup component add llvm-tools
 ```
 
-#### GDB
+### GDB - WSL
 
 /// TODO ///
 
-#### OpenOCD
+### OpenOCD in WSL
 
 Is the same as for native Windows as OpenOCD doesn't (currently) work under WSL.
 
-#### Quality of life
+### Quality of life
 
-##### Shortcuts
+#### Shortcuts
 
-To be able to quickly get up and running I usually create a shortcut on the desktop with all flags I need for a certain project and with the configurations that I need. For example, if I have a project that uses OpenOCD, the STLink programmer and the target MCU is an STM32f4xx, I create a shortcut with the target:
+To be able to quickly get up and running I usually create a shortcut
+on the desktop with all flags I need for a certain project
+with the configurations that I need.
+
+For example, if I have a project that uses OpenOCD,
+the STLink programmer and the target MCU is an STM32f4xx.
+
+I would create a shortcut with the target:
+
+```text
+C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe .\openocd.exe -f ../share/openocd/scripts/interface/stlink.cfg -f ../share/openocd/scripts/target/stm32f4x.cfg
+```
 
-```C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe .\openocd.exe -f ../share/openocd/scripts/interface/stlink.cfg -f ../share/openocd/scripts/target/stm32f4x.cfg```
+and make it start in the openocd/bin folder i.e `C:\OpenOCD\bin`.
+If you want it to be really fancy then under layout you can change where the
+window should spawn as well as how it should look like.
 
-and make it start in the openocd/bin folder i.e ```C:\OpenOCD\bin```. And if you want to be really fancy then under layout you can change where the window should spawn as well as how it should look like.
+You can even make it spawn a WSL terminal to your liking, for example,
+if you have the target set as
+`C:\Windows\System32\bash.exe -c "tmux new-session \; split-window -h \; attach"`
+and to start in the folder where your rust projects are located.
 
-You can even make it spawn a WSL terminal to your liking, for example, if you have the target set as ```C:\Windows\System32\bash.exe -c "tmux new-session \; split-window -h \; attach"``` and to start in the folder where your rust projects are located. Then you will have a bash terminal in your project folder under WSL that starts up with tmux creating two panes splitting the terminal in two.
+Then you will have a bash terminal in your project folder under WSL that starts
+up with [tmux](https://github.com/tmux/tmux/wiki) creating two panes splitting
+the terminal in two.

src/ch2_03_testing_toolchain.md

@@ -5,27 +5,31 @@
 Connect your STM32F401 to the computer via a mini-USB cable.
 
 Start OpenOCD
-```
+
+```shell
 openocd -f interface/stlink.cfg -f target/stm32f4x.cfg
 ```
 
 ### Troubleshoot OpenOCD
 
-If OpenOCD reports no such device, double check with eg. `lsusb` on Linux if you have something like 
+If OpenOCD reports no such device, double check with eg. `lsusb`
+on Linux if you have something like:
 
-```
+```text
 0483:3752 STMicroelectronics ST-LINK/V2.1
 ```
 
-The firmware in the ST-Link can be too new for your currently installed version of OpenOCD.
+The firmware in the ST-Link can be too new
+for your currently installed version of OpenOCD.
 
 If this is the case, then you may have to install/compile the latest version of OpenOCD.
 
-See [OpenOCD git](https://sourceforge.net/p/openocd/code/ci/master/tree/) for complete instructions.
+See [OpenOCD git](https://sourceforge.net/p/openocd/code/ci/master/tree/)
+for complete instructions.
 
 tl;dr:
 
-```
+```shell
 git://git.code.sf.net/p/openocd/code
 ./bootstrap (when building from the git repository)
 ./configure
@@ -33,11 +37,11 @@ make
 sudo make install
 ```
 
-### If success!
+### If success
 
 The next step assumes you get the following output from OpenOCD:
 
-```
+```shell
 ➜ openocd -f interface/stlink.cfg -f target/stm32f4x.cfg
 Open On-Chip Debugger 0.10.0+dev-00973-g80f1a92bd (2019-12-01-00:09)
 Licensed under GNU GPL v2
@@ -54,36 +58,37 @@ Info : stm32f4x.cpu: hardware has 6 breakpoints, 4 watchpoints
 Info : Listening on port 3333 for gdb connections
 ```
 
-
 ## Software
 
-Fetch the following project [https://gitlab.henriktjader.com/pln/stm32-rtic5/tree/rtic_start](https://gitlab.henriktjader.com/pln/stm32-rtic5/tree/rtic_start) 
-and switch to the `rtic_start` branch.
-```
+Fetch the following project [3] and switch to the `rtic_start` branch.
+
+```shell
 git clone https://gitlab.henriktjader.com/pln/stm32-rtic5.git
 git checkout rtic_start
 ```
 
+[3]: https://gitlab.henriktjader.com/pln/stm32-rtic5/tree/rtic_start
+
 You can run the cargo test inside the firmware directory:
 
-```
+```shell
 cd firmware
 cargo test
 cd ..
 ```
-It will print that tests succeeded (hopefully).
 
+It will print that tests succeeded (hopefully).
 
 Inside the binary directory run `cargo run`:
 
-```
+```shell
 cd binary
 cargo run
 ```
 
 If everything went as expected you will see the following:
 
-```
+```shell
 cargo run
     Finished dev [optimized + debuginfo] target(s) in 0.06s
      Running `arm-none-eabi-gdb -q -x openocd.gdb target/thumbv7em-none-eabihf/debug/app`
@@ -109,4 +114,5 @@ Section .text, range 0x8000400 -- 0x80018e8: matched.
 Section .rodata, range 0x80018f0 -- 0x8001d8c: matched.
 (gdb)
 ```
+
 including some messages in the OpenOCD terminal.