Merge #142

142: Attempt to fix broken image links in Discovery book r=therealprof a=adamgreen

This PR pools together PRs #130 and #131 from @ChouzArt and adds 2 more commits that I created to correct other failing links missed by the first 2 and to modify the Travis verification steps to skip the checking of print.html - @ChouzArt has previously pointed out that rust-lang/mdBook#789 causes mdbook to generate an incorrect print.html file when relative links are used in the book content. Skipping verification of print.html during Travis runs means that we will still have a bad image links in print.html but the main Discovery book pages will have working images again and they will show up here on GitHub as well. I realize that this isn't a perfect solution but I thought that people might find it better than the current situation.

The main reason I am creating this PR is to:
* See if it will pass Travis.
* Get people's feedback on this **half** solution.

If we decide to take this PR then there are a few other things that need to be done:
* Create a new issue to track the fact that we should revert this ignoring of print.html during link checking once the mdbook issue is resolved.
* Make a similar change to the [Bookself version of the Travis script](https://github.com/rust-embedded/bookshelf/blob/master/ci/script.sh).

I should also point out that running a `sed` script on print.html can fix most of the link issues that it contains so that the images will at least show up in a printout. Something like:
```console
cp book/print.html print.html
sed 's: src="\.\./assets/: src="assets/:g' <print.html >book/print.html
rm print.html
```

Co-authored-by: Carlos <gsolracchz@gmail.com>
Co-authored-by: Adam Green <adamgreen@users.noreply.github.com>

Author: 3 people

ci/script.sh

@@ -4,13 +4,15 @@ main() {
     # test that building the book works
     mdbook build
 
-    linkchecker book
+    # mdbook doesn't handle relative links correctly in print.html so skip it.
+    linkchecker --ignore-url "print.html" book
 
     # now check this as a directory of the bookshelf
     rm -rf shelf
     mkdir shelf
     mv book shelf
-    linkchecker shelf
+    # Skipping bad relative link errors in print.html again here.
+    linkchecker --ignore-url "print.html" shelf
 
     mv shelf/book .
     rmdir shelf

src/02-requirements/README.md

@@ -25,7 +25,7 @@ Also, to follow this material you'll need the following hardware:
 [3]: http://www.ebay.com/sch/i.html?_nkw=stm32f3discovery
 
 <p align="center">
-<img title="STM32F3DISCOVERY" src="/assets/f3.jpg">
+<img title="STM32F3DISCOVERY" src="../assets/f3.jpg">
 </p>
 
 - OPTIONAL. A **3.3V** USB <-> Serial module. [This particular model][sparkfun] will be used
@@ -39,7 +39,7 @@ cheaper for you to get)
 [4]: https://www.aliexpress.com/wholesale?SearchText=CH340G
 
 <p align="center">
-<img title="A 3.3v USB <-> Serial module" src="/assets/serial.jpg">
+<img title="A 3.3v USB <-> Serial module" src="../assets/serial.jpg">
 </p>
 
 - OPTIONAL. A HC-05 Bluetooth module (with headers!). A HC-06 would work too.
@@ -51,14 +51,14 @@ cheaper for you to get)
 [6]: https://www.aliexpress.com/wholesale?SearchText=hc-05
 
 <p align="center">
-<img title="The HC-05 Bluetooth module" src="/assets/bluetooth.jpg">
+<img title="The HC-05 Bluetooth module" src="../assets/bluetooth.jpg">
 </p>
 
 - Two mini-B USB cables. One is required to make the STM32F3DISCOVERY board work. The other is only
   required if you have the Serial <-> USB module.
 
 <p align="center">
-<img title="mini-B USB cable" src="/assets/usb-cable.jpg">
+<img title="mini-B USB cable" src="../assets/usb-cable.jpg">
 </p>
 
 > **NOTE** These are **not** the USB cables that ship with pretty much every Android phone; those
@@ -75,7 +75,7 @@ cheaper for you to get)
 [9]: https://www.aliexpress.com/wholesale?SearchText=dupont+wire
 
 <p align="center">
-<img title="Jumper wires" src="/assets/jumper-wires.jpg">
+<img title="Jumper wires" src="../assets/jumper-wires.jpg">
 </p>
 
 > **FAQ**: Wait, why do I need this specific hardware?

src/03-setup/README.md

@@ -109,6 +109,6 @@ LLVM (http://llvm.org/):
 
 Now follow the instructions specific to the OS you are using:
 
-- [Linux](/03-setup/linux.html)
-- [Windows](/03-setup/windows.html)
-- [macOS](/03-setup/macos.html)
+- [Linux](linux.html)
+- [Windows](windows.html)
+- [macOS](macos.html)

src/03-setup/linux.md

@@ -115,4 +115,4 @@ If you had any board plugged to your laptop, unplug them and then plug them in a
 
 Now, go to the [next section].
 
-[next section]: /03-setup/verify.html
+[next section]: verify.md

src/03-setup/macos.md

@@ -15,4 +15,4 @@ Caskroom/tap` first and try again.
 
 That's all! Go to the [next section].
 
-[next section]: /03-setup/verify.html
+[next section]: verify.md

src/03-setup/verify.md

@@ -29,7 +29,7 @@ crw-rw-rw- 1 root root 189, 20 Sep 13 00:00 /dev/bus/usb/003/004
 The permissions should be `crw-rw-rw-`. If it's not ... then check your [udev
 rules] and try re-loading them with:
 
-[udev rules]: /03-setup/linux.html#udev%20rules
+[udev rules]: linux.md#udev-rules
 
 ``` console
 $ sudo udevadm control --reload-rules
@@ -104,7 +104,7 @@ Info : stm32f3x.cpu: hardware has 6 breakpoints, 4 watchpoints
 
 (If you don't ... then check the [general troubleshooting] instructions.)
 
-[general troubleshooting]: /appendix/1-general-troubleshooting/README.html
+[general troubleshooting]: ../appendix/1-general-troubleshooting/index.html
 
 `openocd` will block the terminal. That's fine.
 

src/03-setup/windows.md

@@ -47,4 +47,4 @@ instructions and make sure you install the right (32-bit or 64-bit) version of t
 
 That's all! Go to the [next section].
 
-[next section]: /03-setup/verify.html
+[next section]: verify.md

src/04-meet-your-hardware/README.md

@@ -5,7 +5,7 @@ Let's get familiar with the hardware we'll be working with.
 ## STM32F3DISCOVERY (the "F3")
 
 <p align="center">
-<img title="F3" src="/assets/f3.jpg">
+<img title="F3" src="../assets/f3.jpg">
 </p>
 
 We'll refer to this board as "F3" throughout this book.
@@ -46,7 +46,7 @@ What does this board contain?
 ## The Serial module
 
 <p align="center">
-<img title="Serial module" src="/assets/serial.jpg">
+<img title="Serial module" src="../assets/serial.jpg">
 </p>
 
 We'll use this module to exchange data between the microcontroller in the F3 and your laptop. This
@@ -55,7 +55,7 @@ module will be connected to your laptop using an USB cable. I won't say more at
 ## The Bluetooth module
 
 <p align="center">
-<img title="The HC-05 Bluetooth module" src="/assets/bluetooth.jpg">
+<img title="The HC-05 Bluetooth module" src="../assets/bluetooth.jpg">
 </p>
 
 This module has the exact same purpose as the serial module but it sends the data over Bluetooth

src/05-led-roulette/debug-it.md

@@ -39,7 +39,7 @@ mode, on the GDB shell enter the following command:
 > **NOTE** Apologies Windows users. The GDB shipped with the GNU ARM Embedded Toolchain doesn't
 > support this TUI mode `:-(`.
 
-![GDB session](/assets/gdb-layout-src.png "GDB TUI")
+![GDB session](../assets/gdb-layout-src.png "GDB TUI")
 
 At any point you can leave the TUI mode using the following command:
 
@@ -118,7 +118,7 @@ source code view later by issuing the `layout src` command again.
 (gdb) layout asm
 ```
 
-![GDB session](/assets/gdb-layout-asm.png "GDB disassemble")
+![GDB session](../assets/gdb-layout-asm.png "GDB disassemble")
 
 If you are not using the TUI mode, you can use the `disassemble /m` command to disassemble the
 program around the line you are currently at.

src/05-led-roulette/flash-it.md

@@ -29,7 +29,7 @@ $ openocd \
 > **NOTE** Older revisions of the board need to pass slightly different arguments to
 > `openocd`. Review [this section] for the details.
 
-[this section]: /03-setup/verify.html#First%20OpenOCD%20connection
+[this section]: ../03-setup/verify.md#first-openocd-connection
 
 The program will block; leave that terminal open.
 
@@ -44,7 +44,7 @@ and debug a microcontroller. The ST-LINK is connected to the "USB ST-LINK" port
 a USB device when you connect the F3 to your laptop.
 
 <p align="center">
-<img height=640 title="On-board ST-LINK" src="/assets/st-link.png">
+<img height=640 title="On-board ST-LINK" src="../assets/st-link.png">
 </p>
 
 

src/05-led-roulette/the-challenge.md

@@ -12,7 +12,7 @@ Here's the GIF again:
 Also, this may help:
 
 <p align="center">
-<img src="/assets/timing-diagram.png">
+<img src="../assets/timing-diagram.png">
 </p>
 
 This is a timing diagram. It indicates which LED is on at any given instant of time and for how long

src/06-hello-world/README.md

@@ -10,7 +10,7 @@
 [User Manual]: http://www.st.com/resource/en/user_manual/dm00063382.pdf
 
 <p align="center">
-<img height=640 title="Manual SWD connection" src="/assets/f3-swd.png">
+<img height=640 title="Manual SWD connection" src="../assets/f3-swd.png">
 </p>
 
 ---
@@ -46,7 +46,7 @@ To retrieve the original string, OpenOCD's output file will have to be parsed. W
 
 You should have already installed the `itmdump` program during the [installation chapter].
 
-[installation chapter]: /03-setup/README.html#itmdump
+[installation chapter]: ../03-setup/index.html#itmdump
 
 In a new terminal, run this command inside the `/tmp` directory, if you are using a *nix OS, or from
 within the `%TEMP%` directory, if you are running Windows. This should be the same directory from

src/10-serial-communication/README.md

@@ -47,5 +47,5 @@ will see the microcontroller as a virtual serial device.
 Now, let's get familiar with the serial module and the serial communication tools that your OS
 offers. Pick a route:
 
-- [*nix](/10-serial-communication/nix-tooling.html)
-- [Windows](/10-serial-communication/windows-tooling.html)
+- [*nix](nix-tooling.md)
+- [Windows](windows-tooling.md)

src/10-serial-communication/loopbacks.md

@@ -6,7 +6,7 @@ can send us some data ... or is there?
 Enter: loopbacks
 
 <p align="center">
-<img title="Serial module loopback" src="/assets/serial-loopback.png">
+<img title="Serial module loopback" src="../assets/serial-loopback.png">
 </p>
 
 You can send data to yourself! Not very useful in production but very useful for debugging.

src/10-serial-communication/nix-tooling.md

@@ -67,7 +67,7 @@ This tells `minicom` to open the serial device at `/dev/ttyUSB0` and set its bau
 A text-based user interface (TUI) will pop out.
 
 <p align="center">
-<img height="480" title="minicom" src="/assets/minicom.png">
+<img height="480" title="minicom" src="../assets/minicom.png">
 </p>
 
 You can now send data using the keyboard! Go ahead and type something. Note that the TUI *won't*

src/10-serial-communication/windows-tooling.md

@@ -16,7 +16,7 @@ on the list. That's the COM port assigned to the serial module.
 Now launch `putty`. A GUI will pop out.
 
 <p align="center">
-<img title="PuTTY settings" src="/assets/putty-settings.png">
+<img title="PuTTY settings" src="../assets/putty-settings.png">
 </p>
 
 On the starter screen, which should have the "Session" category open, pick "Serial" as the
@@ -35,7 +35,7 @@ that the serial port is configured as follows:
 Finally, click the Open button. A console will show up now:
 
 <p align="center">
-<img title="PuTTY console" src="/assets/putty-console.png">
+<img title="PuTTY console" src="../assets/putty-console.png">
 </p>
 
 If you type on this console, the TX (red) LED on the Serial module should blink. Each key stroke

src/11-usart/README.md

@@ -26,7 +26,7 @@ microcontroller's TX pin to the serial module's RX pin and the micro's RX pin to
 TX pin. The wiring diagram below shows all the necessary connections.
 
 <p align="center">
-<img height=640 title="F3 <-> Serial connection" src="/assets/f3-serial.png">
+<img height=640 title="F3 <-> Serial connection" src="../assets/f3-serial.png">
 </p>
 
 These are the recommended steps to connect the microcontroller and the serial module:

src/12-bluetooth-setup/README.md

@@ -11,7 +11,7 @@ The first thing we'll need to do is: turn on the Bluetooth module. We'll have to
 F3 power to it using the following connection:
 
 <p align="center">
-<img height=640 title="F3 <-> Bluetooth connection (power only)" src="/assets/f3-bluetooth-power-only.png">
+<img height=640 title="F3 <-> Bluetooth connection (power only)" src="../assets/f3-bluetooth-power-only.png">
 </p>
 
 The recommend steps to wire this up are:
@@ -33,4 +33,4 @@ is 1234.
 
 Linux users will have to follow (some of) [these instructions].
 
-[these instructions]: /12-bluetooth-setup/linux.html
+[these instructions]: linux.md

src/12-bluetooth-setup/at-commands.md

@@ -3,7 +3,7 @@
 > **NOTE** incomplete
 
 <p align="center">
-<img height=640 title="Bluetooth <-> Serial connection" src="/assets/bluetooth-serial.png">
+<img height=640 title="Bluetooth <-> Serial connection" src="../assets/bluetooth-serial.png">
 </p>
 
 Entering AT mode:

src/12-bluetooth-setup/linux.md

@@ -3,7 +3,7 @@
 If you have a graphical Bluetooth manager, you can use that to pair your laptop to the Bluetooth
 module and skip most of these steps. You'll probably still have to [this step] though.
 
-[this step]: /12-bluetooth-setup/linux.html#rfcomm%20device
+[this step]: #rfcomm-device
 
 ## Power up
 

src/12-bluetooth-setup/loopback.md

@@ -9,7 +9,7 @@ indicators for the transmission and reception events like the serial module did,
 module using a loopback connection:
 
 <p align="center">
-<img height=640 title="F3 <-> Bluetooth connection (loopback)" src="/assets/f3-bluetooth-loopback.png">
+<img height=640 title="F3 <-> Bluetooth connection (loopback)" src="../assets/f3-bluetooth-loopback.png">
 </p>
 
 Just connect the module's TXD pin to its RXD pin using a F/F wire.

src/13-serial-over-bluetooth/README.md

@@ -4,7 +4,7 @@ Now that we verify that the Bluetooth module works with minicom/PuTTY, let's con
 microcontroller:
 
 <p align="center">
-<img height=640 title="F3 <-> Bluetooth connection" src="/assets/f3-bluetooth.png">
+<img height=640 title="F3 <-> Bluetooth connection" src="../assets/f3-bluetooth.png">
 </p>
 
 Recommended steps to wire this up:
@@ -22,4 +22,4 @@ Recommended steps to wire this up:
 And that's it! You should be able to run all the programs you wrote in [section 11] without
 modification! Just make sure you open the right serial device / COM port.
 
-[section 11]: /11-usart/README.html
+[section 11]: ../11-usart/index.html

src/15-led-compass/README.md

@@ -11,7 +11,7 @@ but it reports back the *decomposition* of said field along *its axes*.
 See below, the magnetometer has three axes associated to it.
 
 <p align="center">
-<img height=480 title="Magnetometer axes" src="/assets/f3-lsm303dlhc.png">
+<img height=480 title="Magnetometer axes" src="../assets/f3-lsm303dlhc.png">
 </p>
 
 Only the X and Y axes are shown above. The Z axis is pointing "out" of your screen.

src/15-led-compass/calibration.md

@@ -101,7 +101,7 @@ plt.close
 ```
 
 <p align="center">
-<img title="Earth's magnetic field" src="/assets/emf.svg">
+<img title="Earth's magnetic field" src="../assets/emf.svg">
 </p>
 
 If you rotated the board on a flat horizontal surface, the Z component of the magnetic field should

src/15-led-compass/take-1.md

@@ -9,7 +9,7 @@ For example, what LED would you turn on in the following case. EMF stands for Ea
 and green arrow has the direction of the EMF (it points north).
 
 <p align="center">
-<img title="Quadrant I" src="/assets/quadrant-i.png">
+<img title="Quadrant I" src="../assets/quadrant-i.png">
 </p
 
 The `Southeast` LED, right?
@@ -21,7 +21,7 @@ If we only looked at the signs of the X and Y components we could determine to w
 magnetic field belongs to.
 
 <p align="center">
-<img title="Quadrants" src="/assets/quadrants.png">
+<img title="Quadrants" src="../assets/quadrants.png">
 </p>
 
 In the previous example, the magnetic field was in the first quadrant (x and y were positive) and it

src/16-punch-o-meter/README.md

@@ -11,7 +11,7 @@ can also be accessed using the I2C bus. It also has the same coordinate system a
 Here's the coordinate system again:
 
 <p align="center">
-<img height=480 title="Magnetometer axes" src="/assets/f3-lsm303dlhc.png">
+<img height=480 title="Magnetometer axes" src="../assets/f3-lsm303dlhc.png">
 </p>
 
 Just like in the previous unit, we'll be using a high level API to directly get the sensor readings

src/README.md

@@ -70,7 +70,7 @@ includes the list of [Frequently Asked Questions].
 
 <p align="center">
 <a href="http://integer32.com/">
-<img style="width: 50%" title="integer 32" src="/assets/integer32.svg">
+<img style="width: 50%" title="integer 32" src="assets/integer32.svg">
 </a>
 </p>
 

src/appendix/1-general-troubleshooting/README.md

@@ -27,8 +27,8 @@ in procedure 'ocd_bouncer'
 - Windows: You are probably missing the ST-LINK USB driver. Installation
   instructions [here].
 
-[these instructions]: /03-setup/linux.html#udev%20rules
-[here]: /03-setup/windows.html#ST-LINK%20USB%20driver
+[these instructions]: ../../03-setup/linux.md#udev-rules
+[here]: ../../03-setup/windows.md#st-link-usb-driver
 
 ### can't connect to OpenOCD - "Polling again in X00ms"