ev3dev · dlech · Dec 30, 2015 · Dec 29, 2015 · Dec 29, 2015 · Dec 29, 2015
diff --git a/_includes/breadcrumbs.html b/_includes/breadcrumbs.html
@@ -1,4 +1,4 @@
-{% assign parent_dirs=page.url | replace_first: '/', '' | split: '/' %}
+{% assign parent_dirs=page.url | replace_first: '/', '' | split: '/' %}
 {% assign link='/' %}
 <ol class="breadcrumb" vocab="http://schema.org" typeof="BreadcrumbList">
     {% assign position = 1 %}

diff --git a/_includes/icon.html b/_includes/icon.html
@@ -0,0 +1,9 @@
+{% comment %}
+
+This template provides icons to match bootstrap alerts.
+
+Parameters:
+
+type: A name that matches an alert. Valid values are "success", info", "warning" and "danger".
+
+{% endcomment %}{% assign name = include.type %}{% if name == "success" %}{% assign name = "ok" %}{% elsif name == "info" %}{% assign name = "info-sign" %}{% elsif name == "warning" %}{% assign name = "alert" %}{% elsif name == "danger" %}{% assign name = "exclamation-sign" %}{% endif %}<span class="glyphicon glyphicon-{{ name }}" aria-hidden="true"></span>
diff --git a/_includes/screenshot.html b/_includes/screenshot.html
@@ -1 +1,10 @@
-<span class="screenshot"><a href="{{ site.github.url }}{{ include.source }}"><img src="{{ site.github.url }}{{ include.source }}" /></a>{% if include.caption %}<p><small>{{ include.caption }}</small></p>{% endif %}</span>
+{% comment %}
+
+Used to format a screenshot.
+
+Parameters:
+
+source: The url of the image
+caption: (optional) A caption that is displayed under the image.
+
+{% endcomment %}<span class="screenshot"><a href="{{ site.github.url }}{{ include.source }}"><img src="{{ site.github.url }}{{ include.source }}" class="img-responsive" /></a>{% if include.caption %}<p><small>{{ include.caption }}</small></p>{% endif %}</span>
diff --git a/_includes/youtube-embed.html b/_includes/youtube-embed.html
@@ -1,4 +1,4 @@
-{% if page.youtube_video_id %}
+{% if page.youtube_video_id %}
     {% assign video_id = page.youtube_video_id %}
 {% elsif include.youtube_video_id %}
     {% assign video_id = include.youtube_video_id %}

diff --git a/_layouts/docs.html b/_layouts/docs.html
@@ -2,13 +2,14 @@
 layout: page
 ---
 
+<hr />
 <div class="nav-dropdown-arrow">
     <div>
         {% include breadcrumbs.html %}
     </div>
     {% if page.kernel_version %}
         <div class="alert alert-info">
-            <span class="glyphicon glyphicon-info-sign"></span>
+            {% include icon.html type="info" %}
             This docs page is for kernel version <code>{{ page.kernel_version }}</code>
         </div>
     {% endif %}

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -16,18 +16,26 @@ First, here are the things you need before starting:
   on the EV3. **All cards larger than 32GB will not work with the EV3!**
 * A computer with an adapter for the SD card. You will need administrator user
   permissions on this computer.
-* A way to communicate. For the EV3, this can be one of the following:
-    * USB cable (the one that comes with the EV3)
-    * USB WiFi dongle
-    * USB Ethernet (wired) dongle
-    * Bluetooth
+* A way to communicate.
+
+  For the EV3, this can be one of the following:
+
+  * USB cable (the one that comes with the EV3)
+  * USB WiFi dongle
+  * USB Ethernet (wired) dongle
+  * Bluetooth
+
   For Raspberry Pi you will need to use the wired Ethernet connection first.
+  With PiStorms the EV3 options will work too since you have a screen to configure
+  them on.
 
-<div class="alert alert-warning">
-    <span class="glyphicon glyphicon-alert"></span>
-    The instructions on this page only apply to releases dated September
-2015 or later. Older releases are no longer supported.
-</div>
+
+{% include icon.html type="warning" %}
+The instructions on this page only apply to releases dated December
+2015 or later. Older releases are no longer supported. There are many major changes
+in the December release, so if something seems broken or the documentation seems incorrect,
+please [open an issue on GitHub]({{ site.github.url }}/support){: .alert-link}.
+{: .alert .alert-warning}
 
 ## Step 1: Download the latest ev3dev image file
 
@@ -44,7 +52,7 @@ decompress it (such as [7-Zip] on Windows).
 ## Step 2: Copy the image on to the SD card
 
 <div class="alert alert-danger">
-    <span class="glyphicon glyphicon-exclamation-sign"></span>
+    {% include icon.html type="danger" %}
     This will erase everything on your SD card! Backup your files
     If you do not want to lose them!
 </div>
@@ -55,20 +63,38 @@ sounds the easiest to you:
 * **Linux**
     * [Command Line](../tutorials/writing-sd-card-image-linux-command-line)
     * [Ubuntu (graphical interface)](../tutorials/writing-sd-card-image-ubuntu-disk-image-writer)
-* **Mac OS X**
-    * [Command Line](../tutorials/writing-sd-card-image-mac-command-line)
+* **OS X**
+    * [Command Line](../tutorials/writing-sd-card-image-osx-command-line)
+    * [Apple Pi Baker (graphical interface)](../tutorials/writing-sd-card-image-osx-apple-pi-baker)
 * **Windows**
     * [Win32DiskImager (graphical interface)](../tutorials/writing-sd-card-image-win32diskimager)
 
 <br/>
 
 <div class="alert alert-info">
-    <span class="glyphicon glyphicon-info-sign"></span>
+    {% include icon.html type="info" %}
     For more detailed information and more alternatives, check out
    <a class="alert-link" href="http://elinux.org/RPi_Easy_SD_Card_Setup">this page for RaspberryPi</a>. Much
 of the information there is applicable to ev3dev.
 </div>
 
+<div class="panel panel-warning">
+<div class="panel-heading">
+{% include icon.html type="warning" %}
+<strong>Raspberry Pi Only!</strong>
+</div>
+<div class="panel-body" markdown="1">
+You must make some changes to `config.txt` to enable support for BrickPi or
+PiStorms before you put your SD card in your Raspberry Pi.
+
+You may have to remove the SD card from your host computer and plug it back in
+after flashing it in order for it to be detected. In your file browser, open
+up `EV3DEV_BOOT`. This contains a file named `config.txt`. Open `config.txt`
+in your favorite text editor and follow the instructions in the file to enable
+either BrickPi or PiStorms.
+</div>
+</div>
+
 {% include inline-screenshot.html source="/images/brickman/main-menu.png" caption="When the boot is complete, the LEDs will turn green and you will see something like this on the screen" %}
 
 ## Step 3: Boot ev3dev
@@ -81,11 +107,12 @@ LEDs indicate disk (SD card) activity.
 **Note:** If you are using Raspberry Pi hardware without a screen, just wait for
 the Activity LED to stop flashing, then go to the next step.
 
-After one or two minutes, the screen will go blank. This happens on the first boot
-only. The first boot takes a little longer than subsequent boots because the EV3
+After about one minute, the screen will go blank. This happens on the first boot
+only. The first boot takes longer than subsequent boots because the EV3
 has to create a unique SSH host ids and take care of a few other housekeeping
 items. After another minute or two, you will see the *brickman loading...* screen.
-
+If nothing has happened after five minutes, something is not right - check the
+troubleshooting tips below.
 
 You will notice the number in the battery in the upper right corner. This
 displays the remaining voltage of the power supply. It is not possible to
@@ -95,118 +122,88 @@ data may be lost. Keep in mind, that is may take a much longer time from 8V to
 6.5V than from 6.5V down to 5V!
 
 <div class="panel panel-info">
-    <div class="panel-heading">
-        Troubleshooting tips if your EV3 won't boot
-    </div>
-    <div class="panel-body">
-        <ul>
-            <li>Make sure nothing is plugged into the EV3 (USB/sensors/motors/etc.)</li>
-            <li>Try writing the image to the SD card again.</li>
-            <li>You may have a bad/incompatible SD card - try a different SD card.</li>
-            <li>Check the condition of the EV3 batteries.</li>
-        </ul>
-    </div>
+<div class="panel-heading">
+{% include icon.html type="info" %}
+Troubleshooting tips if your EV3 won't boot
+</div>
+<div class="panel-body" markdown="1">
+* Make sure nothing is plugged into the EV3 (USB/sensors/motors/etc.)
+* Try writing the image to the SD card again.
+* You may have a bad/incompatible SD card - try a different SD card.
+* Check the condition of the EV3 batteries.
+</div>
 </div>
 
 ## Step 4: Setup a network connection
 
 There are lots of choices here. Your choice depends on what type of connection
 you want to use and on the OS of your host computer, so pick the one that applies:
 
-* Ethernet over USB (just requires the USB cable that comes with the EV3)
+* __Ethernet over USB__ (just requires the USB cable that comes with the EV3)
     * [Connecting to the Internet](../tutorials/connecting-to-the-internet-via-usb) tutorial
-* USB Ethernet dongle (as in the kind with an RJ45 connector)
-    * If your network has a DHCP server, this will "just work". See (non-existent) brickman
-      docs for more info.
-* USB WiFi Dongle
+* __USB Ethernet dongle__ (as in the kind with an RJ45 connector)
+    * If your network has a DHCP server, this will "just work".
+* __USB WiFi Dongle__
     * Hopefully you can figure it out. I'm putting off writing detailed docs
       until brickman is a bit more stable.
-* Bluetooth
+* __Bluetooth__
     * Note: Bluetooth may not work on the first boot. Please reboot if you see "???"
        after you power on Bluetooth.
     * [Connecting to the Internet](../tutorials/connecting-to-the-internet-via-bluetooth) tutorial
 
-**Note:** For Raspberry Pi you must use the wired Ethernet port to connect for the
-first time. The default host name is `ev3dev-rpi` or `ev3dev-rpi2` depending
-on which model you have. You can setup additional connections using the
+{% include icon.html type="info" %}
+For Raspberry Pi with no display, you must use the wired Ethernet port
+to connect for the first time. You can setup additional connections using the
 `connmanctl` command.
+{: class="alert alert-info"}
 
 ## Step 5: First things to do with ev3dev
 
 Here are some suggestions of some things you should do to get ev3dev setup.
+These commands are run on the EV3 in a terminal window. See the networking
+tutorials above if you don't know how to open terminal window and connect via SSH.
 
-### Change your root password
+### Change your password
 
-The default root password is r00tme - those are zeros, not "Ohs".
+The default password is `maker`.
 
-    root@ev3dev:~# passwd
+    robot@ev3dev:~$ passwd
     Enter new UNIX password: 
     Retype new UNIX password: 
     passwd: password updated successfully
 
-### Set up a new user
-
-Replace `user` with your actual user name and `First Last` with your real name
-(if you want it on the EV3 - you can leave it blank too). Don't miss the
-command to assign groups hiding at the end.
-
-    root@ev3dev:~# adduser user
-    Adding user `user' ...
-    Adding new group `user' (1001) ...
-    Adding new user `user' (1001) with group `user' ...
-    Creating home directory `/home/user' ...
-    Copying files from `/etc/skel' ...
-    Enter new UNIX password: 
-    Retype new UNIX password: 
-    passwd: password updated successfully
-    Changing the user information for user
-    Enter the new value, or press ENTER for the default
-    	Full Name []: First Last
-    	Room Number []:    
-    	Work Phone []: 
-    	Home Phone []: 
-    	Other []: 
-    Is the information correct? [Y/n] y
-    root@ev3dev:~# usermod -a -G sudo,ev3dev,plugdev,audio,video,input,bluetooth,i2c user
-
 ### Set the time zone
 
-    root@ev3dev:~# dpkg-reconfigure tzdata
+    robot@ev3dev:~$ sudo dpkg-reconfigure tzdata
 
 Then just follow the instructions on the screen.
 
-**NOTE:** The EV3 does not have a battery backup for the realtime clock.
+{% include icon.html type="info" %}
+The EV3 and Raspberry Pi do not have a battery backup for the realtime clock.
 Whenever you remove the batteries, the clock will be reset. If the EV3 is
 connected to the Internet, the clock will be automatically set via NTP,
 otherwise, you can manually set the date/time with the `date` command.
-
+{: class="alert alert-info"}
 
 ### Set the locale
 
 You can skip this if en-US is OK.
 
-    root@ev3dev:~# dpkg-reconfigure locales
+    robot@ev3dev:~$ sudo dpkg-reconfigure locales
 
 ### Update packages
 
-<div class="alert alert-danger">
-    <span class="glyphicon glyphicon-exclamation-sign"></span>
-    If you are a beginner with Linux and/or Debian, you should skip updating packages
-    for now. We are working on some major changes and things will be inconsisent with the
-    documentation if you upgrade.
-</div>
-
 Make sure your EV3 is connected to the Internet first. 
 Updating the packages for the first time will take minutes.
 The duration depends on the speed class of the SD card and on the updates involved.
 
-    root@ev3dev:~# apt-get update
-    root@ev3dev:~# apt-get upgrade
-    root@ev3dev:~# apt-get dist-upgrade
+    robot@ev3dev:~$ sudo apt-get update
+    robot@ev3dev:~$ sudo apt-get upgrade
+    robot@ev3dev:~$ sudo apt-get dist-upgrade
 
 If a new kernel package is installed, you will need to reboot.
 
-    root@ev3dev:~# reboot
+    robot@ev3dev:~$ sudo reboot
 
 ## Step 6: Do something awesome
 
@@ -244,7 +241,7 @@ hang of it, you can even write your own interface library and have it listed her
 When you are ready to wish your EV3 goodnight, turn if off by pressing the
 *back* button from the main menu in brickman or pressing and holding the *back*
 button from any screen in brickman. This will open a dialog where you can select
-*Power Off* to turn off the EV3.
+*Power Off* to turn off the EV3. (Running `sudo poweroff` in a terminal works too.)
 
 [microSD]: https://en.wikipedia.org/wiki/Secure_Digital#SD
 [microSDHC]: https://en.wikipedia.org/wiki/Secure_Digital#SDHC

diff --git a/docs/index.html b/docs/index.html
@@ -5,7 +5,7 @@
 
 <div class="panel panel-info">
     <div class="panel-heading">
-        <span class="glyphicon glyphicon-info-sign"></span>
+        {% include icon.html type="info" %}
         ev3dev is a community-maintained project that relies on people's contributions.
     </div>
     <div class="panel-body">