Convert README to markdown.

This is more readable on the gitlab/github landing pages.

README → README.md

--------------------------------------------------------------------------
-             The Xiph.org Foundation's libtheora 1.2
--------------------------------------------------------------------------
+# The Xiph.org Foundation's libtheora 1.2
 
-*** What is Theora?
+### What is Theora?
 
 Theora is Xiph.Org's first publicly released video codec, intended
 for use within the Foundation's Ogg multimedia streaming system.
@@ -20,46 +18,41 @@ The 1.2 release features significant additional improvements in
 compression and performance. Files produced by newer encoders can
 be decoded by earlier releases.
 
-*** Where is Theora?
+### Where is Theora?
 
 Theora's main site is www.theora.org.  Theora and related libraries
 can be gotten from www.theora.org or the main Xiph.Org site at
 www.xiph.org.  Development source is kept in an open subversion
 repository, see http://theora.org/svn/ for instructions.
 
--------------------------------------------------------------------------
-Getting started with the code
--------------------------------------------------------------------------
+## Getting started with the code
 
-*** What do I need to build the source?
+### What do I need to build the source?
 
 Requirements summary:
 
-  For libtheora:
+For libtheora:
 
-      libogg 1.1 or newer.
+*   libogg 1.1 or newer.
 
-  For example encoder:
+For example encoder:
 
-      as above,
+*   as above,
+*   libvorbis and libvorbisenc 1.0.1 or newer.
+    (libvorbis 1.3.1 or newer for 5.1 audio)
 
-      libvorbis and libvorbisenc 1.0.1 or newer.
-      (libvorbis 1.3.1 or newer for 5.1 audio)
+For creating a source distribution package:
 
-  For creating a source distribution package:
+*   as above,
+*   Doxygen to build the API documentation,
+*   pdflatex and fig2dev to build the format specification
+    (transfig package in Ubuntu).
 
-      as above,
+For the player only:
 
-      Doxygen to build the API documentation,
-      pdflatex and fig2dev to build the format specification
-        (transfig package in Ubuntu).
-
-  For the player only:
-
-      as above,
-
-      SDL (Simple Direct media Layer) libraries and headers,
-      OSS audio driver and development headers.
+*   as above,
+*   SDL (Simple Direct media Layer) libraries and headers,
+*   OSS audio driver and development headers.
 
 The provided build system is the GNU automake/autoconf system, and
 the main library, libtheora, should already build smoothly on any
@@ -72,7 +65,7 @@ Project files for Apple XCode are included in the macosx directory.
 
 There is also a more limited scons build.
 
-*** How do I use the sample encoder?
+### How do I use the sample encoder?
 
 The sample encoder takes raw video in YUV4MPEG2 format, as used by
 lavtools, mjpeg-tools and other packages. The encoder expects audio,
@@ -93,12 +86,12 @@ as the input file name.
 There is also a 'png2theora' example which accepts a set of image
 files in that format.
 
-*** How do I use the sample player?
+### How do I use the sample player?
 
 The sample player takes an Ogg file on standard in; the file may be
 audio alone, video alone or video with audio.
 
-*** What other tools are available?
+### What other tools are available?
 
 The programs in the examples directory are intended as tutorial source
 for developers using the library. As such they sacrifice features and
@@ -110,13 +103,11 @@ from http://www.theora.org/. There is playback support in a number
 of common free players, and plugins for major media frameworks.
 Jan Gerber's ffmpeg2theora is an excellent encoding front end.
 
--------------------------------------------------------------------------
-Troubleshooting the build process
--------------------------------------------------------------------------
+## Troubleshooting the build process
 
-*** Compile error, such as:
+### Compile error, such as:
 
-encoder_internal.h:664: parse error before `ogg_uint16_t'
+encoder_internal.h:664: parse error before `ogg_uint16_t`
 
 This means you have version of libogg prior to 1.1. A *complete* new Ogg
 install, libs and headers is needed.
@@ -125,32 +116,31 @@ Also be sure that there aren't multiple copies of Ogg installed in
 /usr and /usr/local; an older one might be first on the search path
 for libs and headers.
 
-*** Link error, such as:
+### Link error, such as:
 
-undefined reference to `oggpackB_stream'
+undefined reference to `oggpackB_stream`
 
 See above; you need libogg 1.1 or later.
 
-*** Link error, such as:
+### Link error, such as:
 
-undefined reference to `vorbis_granule_time'
+undefined reference to `vorbis_granule_time`
 
 You need libvorbis and libvorbisenc from the 1.0.1 release or later.
 
-*** Link error, such as:
+### Link error, such as:
 
-/usr/lib/libSDL.a(SDL_esdaudio.lo): In function `ESD_OpenAudio':
-SDL_esdaudio.lo(.text+0x25d): undefined reference to `esd_play_stream'
+/usr/lib/libSDL.a(SDL_esdaudio.lo): In function `ESD_OpenAudio`:
+SDL_esdaudio.lo(.text+0x25d): undefined reference to `esd_play_stream`
 
 Be sure to use an SDL that's built to work with OSS.  If you use an
 SDL that is also built with ESD and/or ALSA support, it will try to
 suck in all those extra libraries at link time too.  That will only
 work if the extra libraries are also installed.
 
-*** Link warning, such as:
+### Link warning, such as:
 
-libtool: link: warning: library `/usr/lib/libogg.la' was moved.
-libtool: link: warning: library `/usr/lib/libogg.la' was moved.
+libtool: link: warning: library `/usr/lib/libogg.la` was moved.
+libtool: link: warning: library `/usr/lib/libogg.la` was moved.
 
 Re-run theora/autogen.sh after an Ogg or Vorbis rebuild/reinstall
-