docs: update install_apt_debian guide

1 files changed, 41 insertions, 35 deletions

diff --git a/docs/install_apt_debian.md b/docs/install_apt_debian.md
index 0d39e3ae..65fe7092 100644
--- a/docs/install_apt_debian.md
+++ b/docs/install_apt_debian.md
@@ -5,13 +5,13 @@ title: "Installation: Debian"
 # Debian Installation
 
 Caffe packages are available for several Debian versions, as shown in the
-following chart
+following chart:
 
 ```
 Your Distro     |  CPU_ONLY  |  CUDA  |     Alias
 ----------------+------------+--------+-------------------
 Debian/stable   |     ✘      |   ✘    | Debian Jessie
-Debian/testing  |     ✔      |   ☐    | Debian Stretch/Sid
+Debian/testing  |     ✔      |   ✔    | Debian Stretch/Sid
 Debian/unstable |     ✔      |   ✔    | Debian Sid
 ```
 
@@ -19,30 +19,32 @@ Debian/unstable |     ✔      |   ✔    | Debian Sid
 
 * `✔ ` You can install caffe with a single command line following this guide.
 
-* `☐ ` The same with `✔ `. However it will not work any more when Debian/Stretch becomes the stable branch.
-
-Last update: 2017-01-05
+Last update: 2017-02-01
 
 ## Binary installation with APT
 
 Apart from the installation methods based on source, Debian/unstable
-and Debian/testing users can install pre-compiled Caffe packages via the official archive.
+and Debian/testing users can install pre-compiled Caffe packages from
+the official archive.
+
+Make sure that your `/etc/apt/sources.list` contains `contrib` and `non-free`
+sections if you want to install the CUDA version, for instance:
 
-Make sure that there is something like the follows in your `/etc/apt/sources.list`:
 ```
-deb http://MIRROR/debian CODENAME main contrib non-free
+deb http://ftp2.cn.debian.org/debian sid main contrib non-free
 ```
-where `MIRROR` is your favorate Debian mirror, and `CODENAME ∈ {testing,stretch,sid}`.
 
 Then we update APT cache and directly install Caffe. Note, the cpu version and
-the cuda version cannot be installed at the same time.
+the cuda version cannot coexist.
+
 ```
-# apt update
-# apt install [ caffe-cpu | caffe-cuda ]
-# caffe                                              # command line interface working
-# python3 -c 'import caffe; print(caffe.__path__)'   # python3 interface working
+$ sudo apt update
+$ sudo apt install [ caffe-cpu | caffe-cuda ]
+$ caffe                                              # command line interface working
+$ python3 -c 'import caffe; print(caffe.__path__)'   # python3 interface working
 ```
-It should work out of box.
+
+These Caffe packages should work for you out of box.
 
 #### Customizing caffe packages
 
@@ -50,46 +52,49 @@ Some users may need to customize the Caffe package. The way to customize
 the package is beyond this guide. Here is only a brief guide of producing
 the customized `.deb` packages. 
 
-Make sure that there is something like this in your `/etc/apt/sources.list`:
+Make sure that there is a `dec-src` source in your `/etc/apt/sources.list`,
+for instance:
+
 ```
 deb http://ftp2.cn.debian.org/debian sid main contrib non-free
 deb-src http://ftp2.cn.debian.org/debian sid main contrib non-free
 ```
 
 Then we build caffe deb files with the following commands:
+
 ```
 $ sudo apt update
-$ sudo apt install build-essential debhelper devscripts    # standard package building tools
-$ sudo apt build-dep [ caffe-cpu | caffe-cuda ]            # the most elegant way to pull caffe build dependencies
-$ apt source [ caffe-cpu | caffe-cuda ]               # download the source tarball and extract
+$ sudo apt install build-essential debhelper devscripts  # standard package building tools
+$ sudo apt build-dep [ caffe-cpu | caffe-cuda ]          # the most elegant way to pull caffe build dependencies
+$ apt source [ caffe-cpu | caffe-cuda ]                  # download the source tarball and extract
 $ cd caffe-XXXX
-[ ... optional, customize caffe code/build ... ]
-$ dch -llocal "Modified XXX in order to XXX"          # write your one-line changelog
-$ debuild -B -j4                                      # build caffe with 4 parallel jobs (similar to make -j4)
+[ ... optional, customizing caffe code/build ... ]
+$ dch --local "Modified XXX"                             # bump package version and write changelog
+$ debuild -B -j4                                         # build caffe with 4 parallel jobs (similar to make -j4)
 [ ... building ...]
-$ debc                                                # optional, if you want to check the package contents
-$ sudo debi                                           # optional, install the generated packages
+$ debc                                                   # optional, if you want to check the package contents
+$ sudo debi                                              # optional, install the generated packages
+$ ls ../                                                 # optional, you will see the resulting packages
 ```
-The resulting deb packages can be found under the parent directory of the source tree.
 
-Note, the `dch ...` command line above is for bumping the package version number
-and adding an entry to the package changelog. If you would like to write
-more than one changelog entry, use subsequent `dch` command (see `man 1 dch`)
-instead of manually modifing `debian/changelog` unless you know how to keep its format correct.
+It is a BUG if the package failed to build without any change.
 The changelog will be installed at e.g. `/usr/share/doc/caffe-cpu/changelog.Debian.gz`.
 
 ## Source installation
 
-Source installation under Debian/unstable is similar to that of Ubuntu, but
+Source installation under Debian/unstable and Debian/testing is similar to that of Ubuntu, but
 here is a more elegant way to pull caffe build dependencies:
+
 ```
 $ sudo apt build-dep [ caffe-cpu | caffe-cuda ]
 ```
+
 Note, this requires a `deb-src` entry in your `/etc/apt/sources.list`.
 
 #### Compiler Combinations
 
-Some users may find their favorate compiler doesn't work well with CUDA.
+Some users may find their favorate compiler doesn't work with CUDA.
+
 ```
 CXX compiler |  CUDA 7.5  |  CUDA 8.0  |
 -------------+------------+------------+-
@@ -144,12 +149,13 @@ and hack the packaging scripts, then build your customized package.
 * Where are the examples, the models and other documentation stuff?
 
 ```
-sudo apt install caffe-doc
-dpkg -L caffe-doc
+$ sudo apt install caffe-doc
+$ dpkg -L caffe-doc
 ```
 
 * Where can I find the Debian package status?
 
-https://tracker.debian.org/pkg/caffe  (for the CPU_ONLY version)
-
+```
+https://tracker.debian.org/pkg/caffe          (for the CPU_ONLY version)
 https://tracker.debian.org/pkg/caffe-contrib  (for the CUDA version)
+```