README.md: updates to the information; more Markdown

README.md

@@ -1,23 +1,21 @@
 MKVToolNix 7.8.0
 ================
 
-Table of contents
+# Table of contents
------------------
 
 1. Introduction
 2. Installation
   1. Requirements
   2. Optional components
-  3. Building libmatroska and libebml
+  3. Building libEBML and libMatroska
   4. Building MKVtoolNix
   5. Notes for compilation on (Open)Solaris
   6. Unit tests
-3. Examples
+3. Reporting bugs
-4. Reporting bugs
 
+-----------------
 
-1. Introduction
+# 1. Introduction
----------------
 
 With these tools one can get information about (mkvinfo) Matroska
 files, extract tracks/data from (mkvextract) Matroska files and create
@@ -35,9 +33,8 @@ This code comes under the GPL v2 (see www.gnu.org or the file COPYING).
 Modify as needed.
 
 The icons are based on the work of Alexandr Grigorcea and modified by
-Eduard Geier. They're licensed under the terms of the Creative Commons
+Eduard Geier. They're licensed under the terms of the
-Attribution 3.0 Unported license (see
+[Creative Commons Attribution 3.0 Unported license](http://creativecommons.org/licenses/by/3.0/).
-http://creativecommons.org/licenses/by/3.0/).
 
 The newest version can always be found at
 https://www.bunkus.org/videotools/mkvtoolnix/
@@ -45,8 +42,7 @@ https://www.bunkus.org/videotools/mkvtoolnix/
 Moritz Bunkus <moritz@bunkus.org>
 
 
-2. Installation
+# 2. Installation
----------------
 
 If you want to compile the tools yourself then you must first decide
 if you want to use a 'proper' release version or the current
@@ -55,20 +51,22 @@ development there might be features available in the git repository
 that are not available in the releases. On the other hand the git
 repository version might not even compile.
 
-### 2.1. Requirements
+## 2.1. Requirements
 
 In order to compile MKVToolNix you need a couple of libraries. Most of
 them should be available pre-compiled for your distribution. The
 programs and libraries you absolutely need are:
 
 - A C++ compiler that supports several features of the C++11 standard:
-  initializer lists, range-based 'for' loops, right angle brackets,
+  initializer lists, range-based »for« loops, right angle brackets,
-  the 'auto' keyword and lambda functions. For GCC this means at least
+  the 'auto' keyword, lambda functions, the »nullptr« key word, tuples
-  v4.6.0.
+  and alias declarations. For GCC this means at least v4.7.0; for
+  clang v3.3 or later.
 
-- libEBML v1.3.1 or later and libMatroska v1.4.2 or later for
+- [libEBML v1.3.1](http://dl.matroska.org/downloads/libebml/) or later
-  low-level access to Matroska files. Instructions on how to compile
+  and [libMatroska v1.4.2](http://dl.matroska.org/downloads/libmatroska/)
-  them are a bit further down in this file.
+  or later for low-level access to Matroska files. Instructions on how to
+  compile them are a bit further down in this file.
 
 - [libOgg](http://downloads.xiph.org/releases/ogg/) and
   [libVorbis](http://downloads.xiph.org/releases/vorbis/) for access to Ogg/OGM
@@ -91,7 +89,7 @@ Installing "drake" is simple. As root run the following command:
 
     gem install drake
 
-### 2.2. Optional components
+## 2.2. Optional components
 
 Other libraries are optional and only limit the features that are
 built. These include:
@@ -103,10 +101,10 @@ built. These include:
 - [libFLAC](http://downloads.xiph.org/releases/flac/) for FLAC
   support (Free Lossless Audio Codec)
 
-- [lzo](http://www.oberhumer.com/opensource/lzo/) and bzip2 (
+- [lzo](http://www.oberhumer.com/opensource/lzo/) and
-  http://www.bzip.org/ ) are compression libraries. These are the
+  [bzip2](http://www.bzip.org/) are compression libraries. These are
-  least important libraries as almost no application supports Matroska
+  the least important libraries as almost no application supports
-  content that is compressed with either of these libs. The
+  Matroska content that is compressed with either of these libs. The
   aforementioned zlib is what every program supports.
 
 - [libMagic](http://www.darwinsys.com/file/) from the "file" package
@@ -114,41 +112,35 @@ built. These include:
 
 - [libcurl](http://curl.haxx.se/) for online update checks
 
-### 2.3. Building libmatroska and libebml
+## 2.3. Building libEBML and libMatroska
 
 This is optional as MKVToolNix comes with its own set of the
 libraries. It will use them if no version is found on the system.
 
-Start with the two libraries. Either get libebml 1.3.1 from
+Start with the two libraries. Either download releases of
-http://dl.matroska.org/downloads/libebml/ and libmatroska 1.4.2 from
+[libEBML 1.3.1](http://dl.matroska.org/downloads/libebml/) and
-http://dl.matroska.org/downloads/libmatroska/ or a fresh copy from the
+[libMatroska 1.4.2](http://dl.matroska.org/downloads/libmatroska/) or
-git repository:
+get a fresh copy from the git repository:
 
     git clone https://github.com/Matroska-Org/libebml.git
     git clone https://github.com/Matroska-Org/libmatroska.git
 
-Change to "libebml/make/linux" and run `make staticlib`. If you have
+First change to libEBML's directory and run `./configure` followed by
-root-access then run `make install_headers install_staticlib` as
+`make`. Now install libEBML by running `make install` as root
-"root" in order to install the files. Change to
+(e.g. via `sudo`). Change to libMatroska's directory and go through
-"libmatroska/make/linux". Once more run `make staticlib`. If you have
+the same steps: first `./configure` followed by `make` as a normal
-root-access then run `make install_headers install_staticlib` as
+user and lastly `make install` as root.
-"root" in order to install the files.
 
-Note that if you don't want the libraries to be installed in
+## 2.4. Building MKVtoolNix
-/usr/local/lib and the headers in /usr/local/include then you can
-alter the prefix (which defaults to /usr/local) by adding an argument
-`prefix=/usr` to the install `make` command. Example:
-
-    make prefix=/usr install_headers install_staticlib
-
-### 2.4. Building MKVtoolNix
 
 Either download the current release from
-https://www.bunkus.org/videotools/mkvtoolnix/ and unpack it or get a
+[the MKVToolNix home page](https://www.bunkus.org/videotools/mkvtoolnix/)
-development snapshot from my Git repository.
+and unpack it or get a development snapshot from my Git repository.
 
-- Getting and building a development snapshot (ignore this subsection
+### 2.4.1. Getting and building a development snapshot
-  if you want to build from a release tarball)
+
+You can ignore this subsection if you want to build from a release
+tarball.
 
 All you need for Git repository access is to download a Git client
 from the Git homepage at http://git-scm.com/. There are clients
@@ -162,9 +154,11 @@ development snapshot from my Git repository.
 `./autogen.sh` which will generate the "configure" script. You need
 the GNU "autoconf" utility for this step.
 
+### 2.4.2. Configuration and compilation
+
 If you have run `make install` for both libraries then `configure`
 should automatically find the libraries' position. Otherwise you need
-to tell `configure` where the "libebml" and "libmatroska" include and
+to tell `configure` where the libEBML and libMatroska include and
 library files are:
 
     ./configure \
@@ -173,7 +167,7 @@ library files are:
 
 Now run `rake` and, as "root", `rake install`. If you don't have
 "rake" installed yourself then use the version bundled with
-MKVToolNix: `./rake.d/bin/drake` and `./rake.d/bin/drake install`.
+MKVToolNix: `./drake` and `./drake install`.
 
 If you want to use all available CPU cores for building then you have
 to use `drake` instead of `rake`. `drake` knows the parameter `-j`
@@ -188,7 +182,7 @@ or
     export DRAKETHREADS=4
     ./drake
 
-### 2.5. Notes for compilation on (Open)Solaris
+## 2.5. Notes for compilation on (Open)Solaris
 
 You can compile mkvtoolnix with Sun's sunstudio compiler, but you need
 additional options for `configure`:
@@ -199,7 +193,7 @@ additional options for `configure`:
       --with-extra-includes=/where/i/put/libebml\;/where/i/put/libmatroska \
       --with-extra-libs=/where/i/put/libebml/make/linux\;/where/i/put/libmatroska/make/linux
 
-### 2.6. Unit tests
+## 2.6. Unit tests
 
 Building and running unit tests is completely optional. If you want to
 do this then you have to follow these steps:
@@ -213,7 +207,7 @@ do this then you have to follow these steps:
   1. Either extract the framework inside the "lib" sub-folder and
      rename the resulting folder "gtest-1.6.0" to "gtest"
 
-     OR...
+     or…
 
   2. Extract the archive somewhere and create a symbolic link to it
      inside the "lib" folder called or create a symbolic link called
@@ -226,8 +220,7 @@ do this then you have to follow these steps:
         ./drake tests:unit
 
 
-3. Reporting bugs
+# 3. Reporting bugs
------------------
 
 If you're sure you've found a bug -- e.g. if one of my programs crashes
 with an obscur error message, or if the resulting file is missing part
@@ -235,11 +228,11 @@ of the original data, then by all means submit a bug report.
 
 I use [GitHub's issue system](https://github.com/mbunkus/mkvtoolnix/issues)
 as my bug database. You can submit your bug reports there. Please be as
-verbose as possible -- e.g. include the command line, if you use Windows
+verbose as possible – e.g. include the command line, if you use Windows
 or Linux etc.pp.
 
 If at all possible please include sample files as well so that I can
 reproduce the issue. If they are larger than 1M then please upload
-them somewhere (e.g. to my FTP server: host name `ftp.bunkus.org`,
+them somewhere and post a link in the issue. You can also upload them
-user name `upload`, password `only`) and post a link or note in the bug
+to my FTP server. Details on how to connect can be found in the
-report.
+[MKVToolNix FAQ](https://github.com/mbunkus/mkvtoolnix/wiki/FTP-server).