fix spelling and formatting on the website

tenbaht · tenbaht · commit bd433436e05d · 2017-10-25T00:08:17.000+02:00
diff --git a/docs/about.md b/docs/about.md
@@ -1,4 +1,4 @@
-# About
+# About Sduino
 
 The idea is to smoothen the path towards your first successful STM8-based
 project.
@@ -16,7 +16,7 @@ detailed knowledge of the CPU internals. [compiling the SPL with
 SDCC](developer/spl.md)
 
 
-## Tools used
+### Tools used
 
 This project is based on free tools that are available for Linux, MacOS, and
 Windows.
@@ -34,7 +34,7 @@ The build process is controlled by a makefile based on the amazing
 
 
 
-## Project origin
+### Project origin
 
 For a customer I needed to port an existing project from an ATmega to a
 better suited (read: cheaper) platform. As the project was based on some
@@ -44,14 +44,14 @@ of days. Porting some of the more commonly used Arduino libraries was a fun
 project done in my spare time later.
 
 
-## About me
+### About me
 
 I am a freelance programmer for embedded systems and electronics developer
 based in Heidelberg, Germany. I work with embedded systems for more than
 25 years now.
 
 
-### Experiences
+#### Experiences
 
 **current CPU architectures**: AVR (ATmega, ATxmega), PIC, STM8, STM32, MCS51
 
diff --git a/docs/api/Mini_SSD1306.md b/docs/api/Mini_SSD1306.md
@@ -76,7 +76,7 @@ void loop()
 
 ## Hardware requirements
 
-These tiny displays communicate usually via I2C, but SPI version do exist.
+These tiny displays communicate usually via I2C, but SPI versions do exist.
 My display uses the I2C address 0x3C, but there are similar displays out
 there configured to use the address 0x3D.
 
@@ -89,6 +89,7 @@ of the screen:
 ![My 0.96" OLED display](oled-ssd1306.jpg)
 
 Technical data:
+
   * Driver chip SSD1306
   * Display resolution: 128x64
   * Power: 3.3V, approx. 20mA (5V possible)
@@ -109,13 +110,15 @@ Pin	|Function|STM8S103 pin	|sduino pin
 ## Further reading
 
 Technical information:
-  * Adafruit tutorial: https://learn.adafruit.com/monochrome-oled-breakouts
-  * SSD1306 datasheet: https://www.adafruit.com/datasheets/SSD1306.pdf
+
+  * [Adafruit tutorial](https://learn.adafruit.com/monochrome-oled-breakouts)
+  * [SSD1306 datasheet](https://www.adafruit.com/datasheets/SSD1306.pdf)
 
 Other libraries:
-  * Adafruit library: https://github.com/adafruit/Adafruit_SSD1306
-  * Old Arduino library u8glib: https://github.com/olikraus/u8glib
-  * newer library u8g2: https://github.com/olikraus/u8g2
+
+  * [Adafruit library](https://github.com/adafruit/Adafruit_SSD1306)
+  * [Old Arduino library u8glib](https://github.com/olikraus/u8glib)
+  * [newer library u8g2](https://github.com/olikraus/u8g2)
 
 
 ## Possible improvements
diff --git a/docs/api/Print.md b/docs/api/Print.md
@@ -0,0 +1,13 @@
+# Print
+
+Formatting functions for use with other output libraries. Involves serious
+preprocessor magic. See the [migration guidelines](../api/migration.md) and
+the [xmacro description](../developer/macro.md)
+
+This page is only a stub.
+
+
+## API
+## Example
+## Implementation details
+## Possible impovements
diff --git a/docs/api/migration.md b/docs/api/migration.md
@@ -124,7 +124,7 @@ structure. Typically, this is done in the `setup()`-function and this pointer
 is stored in a global variable to be used as a device descriptor.
 
 
-So far the [Stepper library](api/Stepper.md) is the only example:
+So far the [Stepper library](Stepper.md) is the only example:
 
 ```c
 #include <Stepper.h>
diff --git a/docs/developer/links.md b/docs/developer/links.md
@@ -8,11 +8,9 @@ metal programming of the STM8S CPUs. By far the best introduction I
 found so far. It would have helped me a lot if it would have around at the
 time when I started this project.
 
-[project documentation files](https://github.com/tenbaht/sduino/blob/master/docs/index.md)
-More in detail information about supported boards, tools and the API.
-
-[Quick introduction to the Arduino.mk makefile]
-(http://hackaday.com/2015/10/01/arduino-development-theres-a-makefile-for-that/)
+[Quick introduction to the Arduino.mk
+makefile](http://hackaday.com/2015/10/01/arduino-development-theres-a-makefile-for-that/)
+on hackaday.com
 
 [PM0051](http://www.st.com/resource/en/programming_manual/cd00191343.pdf):
 STM8AF Flash programming manual  
@@ -21,19 +19,22 @@ STM8 SWIM protocol and debug manual
 [AN2658](http://www.st.com/resource/en/application_note/cd00176594.pdf):
 Using the analog-to-digital converter of the STM8S microcontroller  
 
-Many examples and presentations about the STM8S:  
-https://github.com/VincentYChen/STM8teach  
-It contains the SPL examples from ST, the most useful resource on the STM8:  
-https://github.com/VincentYChen/STM8teach/tree/master/code/Project/STM8S_StdPeriph_Examples
+Many [examples and presentations about the
+STM8S](https://github.com/VincentYChen/STM8teach)
+
+It contains the [SPL examples from
+ST](https://github.com/VincentYChen/STM8teach/tree/master/code/Project/STM8S_StdPeriph_Examples),
+one of the most useful resources on the STM8.
 
-Hardware and pinouts of several ST-Link compatible flash tools:
-https://wiki.cuvoodoo.info/doku.php?id=jtag
+[Hardware and pinouts of several ST-Link compatible flash
+tools](https://wiki.cuvoodoo.info/doku.php?id=jtag)
 
-Using the ADC:  
-http://blog.mark-stevens.co.uk/2012/09/single-scan-adc-on-the-stm8s/  
+[Using the
+ADC](http://blog.mark-stevens.co.uk/2012/09/single-scan-adc-on-the-stm8s/)
+by Mark Stevens
 
-Example for RS-232 handling with SPL:  
-https://sourceforge.net/p/oggstreamer/oggs-stm8-firmware-001/ci/master/tree/rx_ringbuffer.c  
+[Example for RS-232 handling with
+SPL](https://sourceforge.net/p/oggstreamer/oggs-stm8-firmware-001/ci/master/tree/rx_ringbuffer.c)
 
 [AN3139](http://www.st.com/resource/en/application_note/cd00262293.pdf):
 Migration guideline within the STM8L familiy  
diff --git a/docs/developer/sdcc.md b/docs/developer/sdcc.md
@@ -5,37 +5,46 @@ http://www.cnx-software.com/2015/04/13/how-to-program-stm8s-1-board-in-linux/
 
 STM8-Support only started with Version 3.4 in Ubuntu 14.10. For Ubuntu 14.4:
 
+```bash
 	add-apt-repository ppa:laczik/ppa
 	apt-get update
 	apt-get install sdcc
+```
 
 But even this version is fairly old and contains some known bugs. Better
 download a current snapshot build from http://sdcc.sourceforge.net/ and
 unpack it to `/opt/sdcc`. This requires a current version of libstdc++6:
 
+```bash
 	add-apt-repository ppa:ubuntu-toolchain-r/test
 	apt-get update
 	apt-get install libstdc++6
+```
 
 If you prefer to compile stm8flash yourself instead of using the Linux
 binaries in the `tools` directory:
 
+```bash
 	git clone https://github.com/vdudouyt/stm8flash.git
 	cd stm8flash
 	make
 	sudo make install
+```
 
 Download some example code:
 
+```bash
 	git clone https://github.com/vdudouyt/sdcc-examples-stm8.git
 	cd sdcc-examples-stm8
+```
 
 The examples are meant for the STM8L, not the STM8S. This requires some
 changes to account for the different pinout and register addresses (see below).
 Finally upload the binary to the CPU:
 
+```bash
 	stm8flash -c stlinkv2 -p stm8s103?3 -w blinky.ihx
-
+```
 
 
 ### Mixing assembler code with C code
@@ -101,7 +110,7 @@ Make sure to use a recent snapshot build if you are planing to use simulator!
 
 #### Missing peephole optimisations
 
-See discussion of issue 14: https://github.com/tenbaht/sduino/issues/14
+See discussion of [issue #14](https://github.com/tenbaht/sduino/issues/14)
 
 
 
diff --git a/docs/developer/spl.md b/docs/developer/spl.md
@@ -1,19 +1,25 @@
-## ST Standard Library
+## ST Standard Peripherie Library
 
-Can be [downloaded from the ST website]
-(http://www.st.com/en/embedded-software/stsw-stm8069.html)
-(free registration required). Don't miss the Examples folder within the
-downloaded zip file. This is the most useful reference on using this library
-and programming the STM8 in general.
+The Library an be [downloaded from the ST
+website](http://www.st.com/en/embedded-software/stsw-stm8069.html) (free
+registration required). A slightly older version is part of the [STM8S_Teach
+presentation](https://github.com/VincentYChen/STM8teach/tree/master/code/Project/STM8S_StdPeriph_Examples),
+
+Don't miss the Examples folder within the downloaded
+zip file. This and [Lujji's
+blog](https://lujji.github.io/blog/bare-metal-programming-stm8/) is the most
+useful reference on using this library and programming the STM8 in general.
 
 For use with SDCC the library needs to be patched:
 
-	git clone https://github.com/g-gabber/STM8S_StdPeriph_Driver.git
-	git clone https://github.com/gicking/SPL_2.2.0_SDCC_patch.git
-	cp ../STM8S_SPL_2.2.0/Libraries/STM8S_StdPeriph_Driver/inc/stm8s.h .
-	patch -p1 < ../SPL_2.2.0_SDCC_patch/STM8_SPL_v2.2.0_SDCC.patch
-	cp -av  ../STM8S_StdPeriph_Lib/Project/STM8S_StdPeriph_Template/stm8s_conf.h .
-	cp -av  ../STM8S_StdPeriph_Lib/Project/STM8S_StdPeriph_Template/stm8s_it.h .
+```bash
+git clone https://github.com/g-gabber/STM8S_StdPeriph_Driver.git
+git clone https://github.com/gicking/SPL_2.2.0_SDCC_patch.git
+cp ../STM8S_SPL_2.2.0/Libraries/STM8S_StdPeriph_Driver/inc/stm8s.h .
+patch -p1 < ../SPL_2.2.0_SDCC_patch/STM8_SPL_v2.2.0_SDCC.patch
+cp -av  ../STM8S_StdPeriph_Lib/Project/STM8S_StdPeriph_Template/stm8s_conf.h .
+cp -av  ../STM8S_StdPeriph_Lib/Project/STM8S_StdPeriph_Template/stm8s_it.h .
+```
 
 SDCC uses .rel as the file extension for its object files.
 
@@ -82,16 +88,17 @@ The SPL folder in this archive contains a script `doit` to separate the
 functions before compilation.
 FIXME: description needed
 
-Erklärung wie zumindest die Interrupt-Vektoren in die eigene Datei kommen
-können:
+A suggestion how to move at least the IRQ vectors away from the libray into
+the own source files:
 http://richs-words.blogspot.de/2010/09/stm8s-interrupt-handling.html
 
 
 
 ### Interrupts
 
-Namen definiert in stm8s_itc.h
-Interrupt-Routine definieren:
+Interrupt names are defined in stm8s_itc.h
+
+Declaration of an interrupt function for SDCC:
 
 ```c
 /* UART1 TX */
@@ -100,15 +107,15 @@ void UART1_TX_IRQHandler(void) __interrupt(ITC_IRQ_UART1_TX)
 }
 ```
 
-Jetzt muss noch das passende IRQ-Enable-Flag gesetzt werden und Interrupt
-generell freigegeben werden, also hier:
+Set the matching IRQ enable flag and globally allow interrupts:
 
 ```c
 UART1_ITConfig(UART1_IT_TXE, ENABLE);
 enableInterrupts();
 ```
 
-Unklar ist, was die ITC-Prioritäten bewirken. Es geht jedenfalls auch ohne:
+Not sure about the meaning of the ITC priorities. It works even without
+them:
 
 ```c
 ITC_DeInit();
diff --git a/docs/hardware/esp14.md b/docs/hardware/esp14.md
@@ -20,7 +20,7 @@ Feature		| STM8S003	| STM8S103
 ------------	| -------------	| ------------
 EEPROM size	| 128 Bytes	| 640 Bytes
 
-I am not sure why the '003 is sold for half the price, or, to but it the
+I am not sure why the '003 is sold for half the price, or, to put it the
 other way around, why anybody should choose the '103 at all. Did I miss an
 important difference?
 
@@ -35,9 +35,9 @@ usual ESP AT-Firmware and is connected to the RX/TX pins of the STM8S.
 It feels like having a classic ATmega8-Arduino with a build-in ESP-01
 module. Using the [WiFiEsp library](https://github.com/bportaluri/WiFiEsp)
 we could have a programming experience very similar to using an Arduino with
-a Wifi-shield.
+a Wifi-shield or an Arduino Yun.
 
-Problem is the limited flash space of the '003. Even the very basic
+The main problem is the limited flash space of the '003. Even the very basic
 WebServer example that comes with the WiFiEsp library needs more then 14kB
 flash and more than 1kB RAM when compiled for an Arduino Uno. Even if the
 library could be carefully optimized to fit into the 8kB flash of an '003 -
diff --git a/docs/hardware/stm8blue.md b/docs/hardware/stm8blue.md
@@ -27,7 +27,9 @@ perfect for breadboards).
 My breakout boards came preprogrammed with a blink program and with active
 write protection bits. For unlocking before first use:
 
-	stm8flash -cstlinkv2 -pstm8s103?3 -u
+```bash
+stm8flash -cstlinkv2 -pstm8s103?3 -u
+```
 
 
 
diff --git a/docs/hardware/stm8sdiscovery.md b/docs/hardware/stm8sdiscovery.md
@@ -1,11 +1,11 @@
 # STM8S Discovery
 
-A widespread evaluation board made by ST. All CPU pin are easily accessible
+A widespread evaluation board made by ST. All CPU pins are easily accessible
 on 2x6 pin headers. It costs only $9 and includes a ST-Link/v1 flash
 programmer on board.
 
-It should work now, but the support is very fresh and not thoroughly tested. 
-At least Blink.c is known to work already.
+It should work now, but the support is not thoroughly tested. At least
+Blink.c is known to work already.
 
 STM8S105C6T6 microcontroller, 32 KB Flash, 2 KB RAM, 1 KB EEPROM 
 
@@ -39,20 +39,27 @@ hole board useless. You need to make modprobe to ignore it by adding this
 line to /etc/modprobe.conf or by adding a file
 /etc/modprobe.d/stdiscovery.conf with this line:
 
+```bash
 	options usb-storage quirks=0483:3744:i
+```
 
 Unplug the Discovery board and unload the usb mass storage driver with
 
+```bash
 	modprobe -r uas usb_storage
+```
 
 If you can't unload the usb_storage drive because it is in use with other
 devices you can temporary trigger the same effect by this line:
 
+```bash
 	echo "0483:3744:i" >/sys/module/usb_storage/parameters/quirks
+```
 
 The second step is to add a new udev rule in order to access the USB port.
 Save this as root in in `/etc/udev/rules.d/99-stlink.rules`:
 
+```bash
 	# ST-Link/V2 programming adapter
 
 	# ST-Link V1, if using a STM8S discovery board
@@ -61,10 +68,12 @@ Save this as root in in `/etc/udev/rules.d/99-stlink.rules`:
 
 	# ST-Link/V2, the china adapter with the green plastic housing
 	ATTR{idVendor}=="0483", ATTR{idProduct}=="3748", MODE="0666", GROUP="plugdev"
+```
 
 Finally, it is time to (re-) connect the board. Now dmesg should show that
 the mass storage device of the Discovery board is ignored:
 
+```bash
 	[  815.228928] usbcore: deregistering interface driver uas
 	[  815.229201] usbcore: deregistering interface driver usb-storage
 	[  823.001086] usb 1-3: new full-speed USB device number 7 using xhci_hcd
@@ -77,10 +86,13 @@ the mass storage device of the Discovery board is ignored:
 	[  823.748299] usb-storage 1-3:1.0: device ignored
 	[  823.748453] usbcore: registered new interface driver usb-storage
 	[  823.771094] usbcore: registered new interface driver uas
+```
 
 Let's read the preinstalled firmware of the STM8S105:
 
+```bash
 	stm8flash -cstlink "-pstm8s105?6" -r flash.img
+```
 
 
 ## Further reading
diff --git a/docs/index.md b/docs/index.md
diff --git a/docs/usage/status-todo.md b/docs/usage/status-todo.md
diff --git a/docs/usage/update-to-manual.md b/docs/usage/update-to-manual.md
diff --git a/docs/usage/why-stm8.md b/docs/usage/why-stm8.md
diff --git a/mkdocs.yml b/mkdocs.yml
