Convert the README to markdown syntax (#96)

Currently the README's formatting shows up rather poorly on GitHub, as
the file isn't written as a Markdown document but GitHub tries to render
it as one due to the symlink from README.md to README. This commit
reformats the file as a Markdown document, preserving the original
content with two exceptions:

1. The platform support list has been converted to a Markdown table.

2. The severely outdated information regarding libexecinfo on FreeBSD
   has been amended and the note about FreeBSD 8.0 removed.

1 files changed, 99 insertions, 105 deletions

diff --git a/README b/README
index f7845252..5befeec6 100644
--- a/README
+++ b/README
@@ -1,53 +1,56 @@
--*- mode: Outline -*-
+# libunwind
 
 [![Build Status](https://travis-ci.org/libunwind/libunwind.svg?branch=master)](https://travis-ci.org/libunwind/libunwind)
 
 This is version 1.3 of the unwind library.  This library supports
 several architecture/operating-system combinations:
 
- Linux/x86-64:	Works well.
- Linux/x86:	Works well.
- Linux/ARM:	Works well.
- Linux/IA-64:	Works well.
- Linux/PARISC:	Works well, but C library missing unwind-info.
- HP-UX/IA-64:	Mostly works but known to have some serious limitations.
- MIPS:          Newly added.
- Linux/AArch64:	Works well.
- Linux/PPC64:	Newly added.
- Linux/SuperH:	Newly added.
- FreeBSD/i386:	Works well.
- FreeBSD/x86-64: Newly added (FreeBSD architecture is known as amd64).
- Linux/Tilegx:  Newly added (64-bit mode only).
-
-* General Build Instructions
+| System  | Architecture | Status |
+| :------ | :----------- | :----- |
+| Linux   | x86-64       | ✓      |
+| Linux   | x86          | ✓      |
+| Linux   | ARM          | ✓      |
+| Linux   | AArch64      | ✓      |
+| Linux   | PPC64        | ✓      |
+| Linux   | SuperH       | ✓      |
+| Linux   | IA-64        | ✓      |
+| Linux   | PARISC       | Works well, but C library missing unwind-info |
+| Linux   | Tilegx       | 64-bit mode only |
+| Linux   | MIPS         | Newly added |
+| HP-UX   | IA-64        | Mostly works, but known to have serious limitations |
+| FreeBSD | x86-64       | ✓      |
+| FreeBSD | x86          | ✓      |
+| FreeBSD | AArch64      | ✓      |
+
+## General Build Instructions
 
 In general, this library can be built and installed with the following
 commands:
 
-	$ ./autogen.sh # Needed only for building from git. Depends on libtool.
-	$ ./configure
-	$ make
-	$ make install prefix=PREFIX
+    $ ./autogen.sh # Needed only for building from git. Depends on libtool.
+    $ ./configure
+    $ make
+    $ make install prefix=PREFIX
 
-where PREFIX is the installation prefix.  By default, a prefix of
-/usr/local is used, such that libunwind.a is installed in
-/usr/local/lib and unwind.h is installed in /usr/local/include.  For
-testing, you may want to use a prefix of /usr/local instead.
+where `PREFIX` is the installation prefix.  By default, a prefix of
+`/usr/local` is used, such that `libunwind.a` is installed in
+`/usr/local/lib` and `unwind.h` is installed in `/usr/local/include`.  For
+testing, you may want to use a prefix of `/usr/local` instead.
 
 
-* Building with Intel compiler
+### Building with Intel compiler
 
-** Version 8 and later
+#### Version 8 and later
 
 Starting with version 8, the preferred name for the IA-64 Intel
-compiler is "icc" (same name as on x86).  Thus, the configure-line
+compiler is `icc` (same name as on x86).  Thus, the configure-line
 should look like this:
 
     $ ./configure CC=icc CFLAGS="-g -O3 -ip" CXX=icc CCAS=gcc CCASFLAGS=-g \
-		LDFLAGS="-L$PWD/src/.libs"
+        LDFLAGS="-L$PWD/src/.libs"
 
 
-* Building on HP-UX
+### Building on HP-UX
 
 For the time being, libunwind must be built with GCC on HP-UX.
 
@@ -55,14 +58,13 @@ libunwind should be configured and installed on HP-UX like this:
 
     $ ./configure CFLAGS="-g -O2 -mlp64" CXXFLAGS="-g -O2 -mlp64"
 
-Caveat: Unwinding of 32-bit (ILP32) binaries is not supported
-	at the moment.
+Caveat: Unwinding of 32-bit (ILP32) binaries is not supported at the moment.
 
-** Workaround for older versions of GCC
+### Workaround for older versions of GCC
 
-GCC v3.0 and GCC v3.2 ship with a bad version of sys/types.h.  The
+GCC v3.0 and GCC v3.2 ship with a bad version of `sys/types.h`.  The
 workaround is to issue the following commands before running
-"configure":
+`configure`:
 
     $ mkdir $top_dir/include/sys
     $ cp /usr/include/sys/types.h $top_dir/include/sys
@@ -70,138 +72,130 @@ workaround is to issue the following commands before running
 GCC v3.3.2 or later have been fixed and do not require this
 workaround.
 
-* Building for PowerPC64 / Linux
+### Building for PowerPC64 / Linux
 
 For building for power64 you should use:
 
-  $ ./configure CFLAGS="-g -O2 -m64" CXXFLAGS="-g -O2 -m64"
+    $ ./configure CFLAGS="-g -O2 -m64" CXXFLAGS="-g -O2 -m64"
 
 If your power support altivec registers:
-  $ ./configure CFLAGS="-g -O2 -m64 -maltivec" CXXFLAGS="-g -O2 -m64 -maltivec"
+
+    $ ./configure CFLAGS="-g -O2 -m64 -maltivec" CXXFLAGS="-g -O2 -m64 -maltivec"
 
 To check if your processor has support for vector registers (altivec):
+
     cat /proc/cpuinfo | grep altivec
+
 and should have something like this:
+
     cpu             : PPC970, altivec supported
 
 If libunwind seems to not work (backtracing failing), try to compile
-it with -O0, without optimizations. There are some compiler problems
+it with `-O0`, without optimizations. There are some compiler problems
 depending on the version of your gcc.
 
-* Building on FreeBSD
-
-General building instructions apply. To build and execute several tests,
-you need libexecinfo library available in ports as devel/libexecinfo.
+### Building on FreeBSD
 
-Development of the port was done of FreeBSD 8.0-STABLE. The library
-was build with the system compiler that is modified version of gcc 4.2.1,
-as well as the gcc 4.4.3.
+General building instructions apply. To build and execute several tests
+on older versions of FreeBSD, you need libexecinfo library available in
+ports as devel/libexecinfo. This port has been removed as of 2017 and is
+indeed no longer needed.
 
-* Regression Testing
+## Regression Testing
 
 After building the library, you can run a set of regression tests with:
 
-	$ make check
+    $ make check
 
-** Expected results on IA-64 Linux
+### Expected results on IA-64 Linux
 
 Unless you have a very recent C library and compiler installed, it is
 currently expected to have the following tests fail on IA-64 Linux:
 
-	Gtest-init		(should pass starting with glibc-2.3.x/gcc-3.4)
-	Ltest-init		(should pass starting with glibc-2.3.x/gcc-3.4)
-	test-ptrace		(should pass starting with glibc-2.3.x/gcc-3.4)
-	run-ia64-test-dyn1	(should pass starting with glibc-2.3.x)
+* `Gtest-init` (should pass starting with glibc-2.3.x/gcc-3.4)
+* `Ltest-init` (should pass starting with glibc-2.3.x/gcc-3.4)
+* `test-ptrace` (should pass starting with glibc-2.3.x/gcc-3.4)
+* `run-ia64-test-dyn1` (should pass starting with glibc-2.3.x)
 
 This does not mean that libunwind cannot be used with older compilers
 or C libraries, it just means that for certain corner cases, unwinding
 will fail.  Since they're corner cases, it is not likely for
 applications to trigger them.
 
-Note: If you get lots of errors in Gia64-test-nat and Lia64-test-nat, it's
-      almost certainly a sign of an old assembler.  The GNU assembler used
-      to encode previous-stack-pointer-relative offsets incorrectly.
-      This bug was fixed on 21-Sep-2004 so any later assembler will be
-      fine.
+Note: If you get lots of errors in `Gia64-test-nat` and `Lia64-test-nat`, it's
+almost certainly a sign of an old assembler.  The GNU assembler used
+to encode previous-stack-pointer-relative offsets incorrectly.
+This bug was fixed on 21-Sep-2004 so any later assembler will be
+fine.
 
-** Expected results on x86 Linux
+### Expected results on x86 Linux
 
 The following tests are expected to fail on x86 Linux:
 
-	test-ptrace
+* `test-ptrace`
 
-** Expected results on x86-64 Linux
+### Expected results on x86-64 Linux
 
 The following tests are expected to fail on x86-64 Linux:
 
-	run-ptrace-misc	(see http://gcc.gnu.org/bugzilla/show_bug.cgi?id=18748
-			 and http://gcc.gnu.org/bugzilla/show_bug.cgi?id=18749)
+* `run-ptrace-misc` (see <http://gcc.gnu.org/bugzilla/show_bug.cgi?id=18748>
+  and <http://gcc.gnu.org/bugzilla/show_bug.cgi?id=18749>)
 
-** Expected results on PARISC Linux
+### Expected results on PARISC Linux
 
 Caveat: GCC v3.4 or newer is needed on PA-RISC Linux.  Earlier
 versions of the compiler failed to generate the exception-handling
-program header (GNU_EH_FRAME) needed for unwinding.
+program header (`GNU_EH_FRAME`) needed for unwinding.
 
 The following tests are expected to fail on x86-64 Linux:
 
-	Gtest-bt   (backtrace truncated at kill() due to lack of unwind-info)
-	Ltest-bt   (likewise)
-	Gtest-resume-sig  (Gresume.c:my_rt_sigreturn() is wrong somehow)
-	Ltest-resume-sig  (likewise)
-	Gtest-init (likewise)
-	Ltest-init (likewise)
-	Gtest-dyn1 (no dynamic unwind info support yet)
-	Ltest-dyn1 (no dynamic unwind info support yet)
-	test-setjmp		(longjmp() not implemented yet)
-	run-check-namespace	(toolchain doesn't support HIDDEN yet)
+* `Gtest-bt` (backtrace truncated at `kill()` due to lack of unwind-info)
+* `Ltest-bt` (likewise)
+* `Gtest-resume-sig` (`Gresume.c:my_rt_sigreturn()` is wrong somehow)
+* `Ltest-resume-sig` (likewise)
+* `Gtest-init` (likewise)
+* `Ltest-init` (likewise)
+* `Gtest-dyn1` (no dynamic unwind info support yet)
+* `Ltest-dyn1` (no dynamic unwind info support yet)
+* `test-setjmp` (`longjmp()` not implemented yet)
+* `run-check-namespace` (toolchain doesn't support `HIDDEN` yet)
 
-** Expected results on HP-UX
+### Expected results on HP-UX
 
-"make check" is currently unsupported for HP-UX.  You can try to run
+`make check` is currently unsupported for HP-UX.  You can try to run
 it, but most tests will fail (and some may fail to terminate).  The
 only test programs that are known to work at this time are:
 
-     tests/bt
-     tests/Gperf-simple
-     tests/test-proc-info
-     tests/test-static-link
-     tests/Gtest-init
-     tests/Ltest-init
-     tests/Gtest-resume-sig
-     tests/Ltest-resume-sig
+* `tests/bt`
+* `tests/Gperf-simple`
+* `tests/test-proc-info`
+* `tests/test-static-link`
+* `tests/Gtest-init`
+* `tests/Ltest-init`
+* `tests/Gtest-resume-sig`
+* `tests/Ltest-resume-sig`
 
-** Expected results on PPC64 Linux
+### Expected results on PPC64 Linux
 
-"make check" should run with no more than 10 out of 24 tests failed.
+`make check` should run with no more than 10 out of 24 tests failed.
 
 
-* Performance Testing
+## Performance Testing
 
 This distribution includes a few simple performance tests which give
 some idea of the basic cost of various libunwind operations.  After
 building the library, you can run these tests with the following
 commands:
 
- $ cd tests
- $ make perf
-
-* Contacting the Developers
-
-Please direct all questions regarding this library to:
-
-	libunwind-devel@nongnu.org
-
-You can do this by sending a mail to libunwind-request@nongnu.org with
-a body of:
-
-	subscribe libunwind-devel
+    $ cd tests
+    $ make perf
 
-or you can subscribe and manage your subscription via the
-web-interface at:
+## Contacting the Developers
 
-	https://savannah.nongnu.org/mail/?group=libunwind
+Please direct all questions regarding this library to <libunwind-devel@nongnu.org>.
 
-Or interact at the github page:
+You can do this by sending an email to <libunwind-request@nongnu.org> with
+a body of "subscribe libunwind-devel", or you can subscribe and manage your
+subscription via the web-interface at <https://savannah.nongnu.org/mail/?group=libunwind>.
 
-   	https://github.com/libunwind/libunwind
+You can also interact on our GitHub page: <https://github.com/libunwind/libunwind>.