Make the first few sections of 'bbb_setup' more readable and, to a greater extent, link to third party websites that work reasonably well without running non-free JS code.

1 files changed, 17 insertions, 27 deletions

diff --git a/docs/src/install/bbb_setup.texi b/docs/src/install/bbb_setup.texi
index 78dc1265..27571107 100644
--- a/docs/src/install/bbb_setup.texi
+++ b/docs/src/install/bbb_setup.texi
@@ -24,7 +24,7 @@
 @node How to program an SPI flash chip with the BeagleBone Black
 @chapter How to program an SPI flash chip with the BeagleBone Black
 @anchor{#how-to-program-an-spi-flash-chip-with-the-beaglebone-black}
-This document exists as a guide for reading from or writing to an SPI flash chip with the BeagleBone Black, using the @uref{http://flashrom.org/Flashrom,flashrom} software. BeagleBone Black rev. C was used when creating this guide, but earlier revisions may also work.
+This document exists as a guide for reading from or writing to an SPI flash chip with the BeagleBone Black, using the @uref{http://flashrom.org/Flashrom,flashrom} software.  A BeagleBone Black, rev. C was used when creating this guide, but earlier revisions may also work.
 
 @uref{index.html,Back to previous index}
 
@@ -35,46 +35,36 @@ Shopping list (pictures of this hardware is shown later):
 
 @itemize
 @item
-External SPI programmer: @strong{BeagleBone Black} (rev. C) is highly recommended. Sometimes referred to as 'BBB'. @uref{http://beagleboard.org/black,This page} contains a list of distributors. farnell sells them - @uref{http://farnell.com/,http://farnell.com/} - If you can't get a BBB, there are other programmers listed on flashrom.org, but not all of them will be suitable for libreboot's purpose. (some may also require blobs. all BBs and BBBs though can be used without blobs). There are also some programmers not listed on flashrom.org, that can also work. A BB (original beaglebone) should work as well, though you might have to replace the distro that it came with.
+A @uref{http://flashrom.org,Flashrom}-compatible external SPI programmer: @strong{BeagleBone Black}, sometimes referred to as 'BBB', (rev. C) is highly recommended.  You can buy one from @uref{https://www.adafruit.com,Adafruit} (USA), @uref{http://electrokit.com,Electrokit} (Sweden) or any of the distributors listed @uref{http://beagleboard.org/black,here} (look below 'Purchase').  We recommend this product because we know that it works well for our purposes and doesn't require any non-free software.
 @item
-Electrical/insulative tape: cover the entire bottom surface of the BBB (the part that rests on a surface). This is important, when placing the BBB on top of a board so that nothing shorts. - easy to find in most hardware/electronics stores
+Electrical/insulative tape: cover the entire bottom surface of the BBB (the part that rests on a surface).  This is important, when placing the BBB on top of a board so that nothing shorts.  Most hardware/electronics stores have this.  Optionally, you can use the bottom half of a @uref{http://www.hammondmfg.com/1593HAM.htm#BeagleBoneBlack,hammond plastic enclosure}.
 @item
-Clip for connecting to the flash chip: if you have a SOIC-16 flash chip (16 pins), you will need the @strong{Pomona 5252} or equivalent. For SOIC-8 flash chips (8 pins), you will need the @strong{Pomona 5250} or equivalent. Do check which chip you have, before ordering a clip. Also, make sure to buy at least two clips (they break easily). - Farnell sells these, and ships to many countries. @uref{http://farnell.com/,http://farnell.com/} - Some people find these difficult to get, especially in South America. If you have more links to suppliers, please contact the libreboot project with the relevant information. - @strong{if you can't get a pomona clip, some other clips might work (eg 3M) but are not always reliable. You can also directly solder the wires to the chip, if that suits you. The clip is just for convenience, really.}
+Clip for connecting to the flash chip: if you have a SOIC-16 flash chip (16 pins), you will need the @strong{Pomona 5252} or equivalent.  For SOIC-8 flash chips (8 pins), you will need the @strong{Pomona 5250} or equivalent.  Do check which chip you have, before ordering a clip.  Also, you might as well buy two clips or more since they break easily.  @uref{http://farnell.com/,Farnell element 14} sells these and ships to many countries.  Some people find these clips difficult to get hold of, especially in South America.  If you know of any good suppliers, please contact the libreboot project with the relevant information.  @strong{If you can't get hold of a pomona clip, some other clips might work, e.g. 3M, but they are not always reliable.  You can also directly solder the wires to the chip, if that suits you; the clip is just for convenience, really.}
 @item
-@strong{External 3.3V DC power supply}, for powering the flash chip. An ATX power supply / PSU (common on Intel/AMD desktop computers) will work for this. A lab PSU (DC) will also work (adjusted to 3.3V). Etc.
+@strong{External 3.3V DC power supply}, for powering the flash chip: an ATX power supply / PSU (common on Intel/AMD desktop computers) will work for this.  A lab PSU (DC) will also work (adjusted to 3.3V).
 @itemize
 @item
-Getting a multimeter might be worthwhile, to verify that it's supplying 3.3V
+Getting a multimeter might be worthwhile, to verify that it's supplying 3.3V.
 @end itemize
 
 @item
-@strong{External 5V DC power supply} (barrel connector), for powering the BBB. The BeagleBone can have power supplied via USB, but a dedicated power supply is recommended. These should be easy to find in most places that sell electronics. - @strong{OPTIONAL. Only needed if not powering with the USB cable, or if you want to use @uref{bbb_ehci.html,EHCI debug}}
+@strong{External 5V DC power supply} (barrel connector), for powering the BBB: the latter can have power supplied via USB, but a dedicated power supply is recommended.  These should be easy to find in most places that sell electronics.  @strong{OPTIONAL. Only needed if not powering with the USB cable, or if you want to use @uref{bbb_ehci.html,EHCI debug}}.
 @item
-@strong{Pin header / jumper cables} (2.54mm / 0.1" headers) You should get male-male, male-female and female-female cables in 10cm size. Just get a load of them. other possible names for these cables:
+@strong{Pin header / jumper cables} (2.54mm / 0.1" headers): you should get male--male, male--female and female--female cables in 10cm size.  Just get a load of them.  Other possible names for these cables/wires/leads are
 @itemize
 @item
 flying leads
 @item
-dupont (this is just one possible brand name)
+dupont (or other brand names)
 @item
-Often used on breadboards, so they might be called breadboard cables
-@item
-Maybe they are called @strong{wires} instead of cables or leads
-@item
-They are also the same cables used on the GPIOs on the RPi
-@item
-@strong{adafruit.com} sells them, and there are others
-@item
-@strong{Some people find these difficult to buy. Contact the libreboot project if you have more links to sellers.}
-@item
-You might also be able to make these cables yourself.
+breadboard cables (since they are often used on breadboards).
 @end itemize
 
-For PSU connections, long cables (e.g. 20cm) is fine, and you can extend it longer than that if needed.
+@uref{https://www.adafruit.com,Adafruit} sell them, as do many others.  @strong{Some people find them difficult to buy.  Please contact the libreboot project if you know of any good sellers.}  You might also be able to make these cables yourself.  For PSU connections, using long cables, e.g. 20cm, is fine, and you can extend them longer than that if needed.
 @item
-@strong{Mini USB A-B cable} (the BeagleBone probably already comes with one.) - @strong{OPTIONAL - only needed for @uref{bbb_ehci.html,EHCI debug} or for serial/ssh access without ethernet cable (g_multi kernel module)}
+@strong{Mini USB A-B cable}: the BBB probably already comes with one.  @strong{OPTIONAL---only needed for @uref{bbb_ehci.html,EHCI debug} or for serial/SSH access without ethernet cable (g_multi kernel module)}.
 @item
-@strong{FTDI TTL cable or debug board}, for accessing the serial console on your BBB. @uref{http://elinux.org/Beagleboard:BeagleBone_Black_Serial,This page} contains a list. - @strong{OPTIONAL - only needed for serial console on the BBB, if not using SSH via ethernet cable}
+@strong{FTDI TTL cable or debug board}: used for accessing the serial console on the BBB.  @uref{http://elinux.org/Beagleboard:BeagleBone_Black_Serial,This page} contains a list.  @strong{OPTIONAL---only needed for serial console on the BBB, if not using SSH via ethernet cable.}
 @end itemize
 
 @ref{#pagetop,Back to top of page.}
@@ -82,11 +72,11 @@ For PSU connections, long cables (e.g. 20cm) is fine, and you can extend it long
 @node Setting up the 33V DC PSU
 @chapter Setting up the 3.3V DC PSU
 @anchor{#setting-up-the-3.3v-dc-psu}
-ATX PSU pinouts are on @uref{https://en.wikipedia.org/wiki/Power_supply_unit_%28computer%29#Wiring_diagrams,wikipedia}
+ATX PSU pinouts can be read on @uref{https://en.wikipedia.org/wiki/Power_supply_unit_%28computer%29#Wiring_diagrams,this Wikipedia page}.
 
-You can use pin 1 or 2 (orange wire) on a 20-pin or 24-pin ATX PSU for 3.3V, and any of the ground/earth sources (black cables) for ground. Short PS_ON# / Power on (green wire. pin 16 on 24-pin ATX PSU, or pin 14 on a 20-pin ATX PSU) to a ground (black. there is one right next to it) using a wire/paperclip/jumper then power on the PSU by grounding PS_ON# (this is also how an ATX motherboard turns on a PSU).
+You can use pin 1 or 2 (orange wire) on a 20-pin or 24-pin ATX PSU for 3.3V, and any of the ground/earth sources (black cables) for ground.  Short PS_ON# / Power on (green wire; pin 16 on 24-pin ATX PSU, or pin 14 on a 20-pin ATX PSU) to a ground (black; there is one right next to it) using a wire/paperclip/jumper, then power on the PSU by grounding PS_ON# (this is also how an ATX motherboard turns on a PSU).
 
-@strong{DO **NOT** use pin 4, 6, do **NOT** use pin 19 or 20 (on a 20-pin ATX PSU), and DO **NOT** use pin 21, 22 or 23 (on a 24-pin ATX PSU). Those wires (the red ones) are 5V, and they **WILL** kill your flash chip. ***NEVER*** supply more than 3.3V to your flash chip. (that is, if it's a 3.3V flash chip. 5V and 1.8V SPI flash chips do exist, but they are rare. always check what voltage your chip takes. most take 3.3V)}
+@strong{DO **NOT** use pin 4, 6, do **NOT** use pin 19 or 20 (on a 20-pin ATX PSU), and DO **NOT** use pin 21, 22 or 23 (on a 24-pin ATX PSU).  Those wires (the red ones) are 5V, and they **WILL** kill your flash chip.  ***NEVER*** supply more than 3.3V to your flash chip (that is, if it's a 3.3V flash chip; 5V and 1.8V SPI flash chips do exist, but they are rare.  Always check what voltage your chip takes.  Most of them take 3.3V).}
 
 You only need one 3.3V supply and one ground for the flash chip, after grounding PS_ON#.
 
@@ -271,7 +261,7 @@ See this image: @uref{http://i.imgur.com/qHGxKpj.jpg,http://i.imgur.com/qHGxKpj.
 He was able to flash at 50MHz (lower speeds are also fine).
 @end itemize
 
-Copyright © 2014, 2015 Francis Rowe <info@@gluglug.org.uk>@* Copyright © 2015 Patrick "P. J." McDermott <pj@@pehjota.net>@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be found at @uref{../resources/licenses/gfdl-1.3.txt,gfdl-1.3.txt}
+Copyright © 2014, 2015 Francis Rowe <info@@gluglug.org.uk>@* Copyright © 2015 Patrick "P. J." McDermott <pj@@pehjota.net>@* Copyright © 2015 Albin Söderqvist@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be found at @uref{../resources/licenses/gfdl-1.3.txt,gfdl-1.3.txt}
 
 Updated versions of the license (when available) can be found at @uref{https://www.gnu.org/licenses/licenses.html,https://www.gnu.org/licenses/licenses.html}