docs: Update the README file

Use the appropriate Markdown syntax (with GitHub extensions) for code
blocks and preformatted bits, and update the build instructions and
dependencies for Meson and Ninja.

README.md

@@ -1,11 +1,10 @@
 Epoxy is a library for handling OpenGL function pointer management for
 you.
 
-It hides the complexity of ```dlopen()```, ```dlsym()```,
+It hides the complexity of `dlopen()`, `dlsym()`, `glXGetProcAddress()`,
-```glXGetProcAddress()```, ```eglGetProcAddress()```, etc. from the
+`eglGetProcAddress()`, etc. from the app developer, with very little
-app developer, with very little knowledge needed on their part.  They
+knowledge needed on their part.  They get to read GL specs and write
-get to read GL specs and write code using undecorated function names
+code using undecorated function names like `glCompileShader()`.
-like ```glCompileShader()```.
 
 Don't forget to check for your extensions or versions being present
 before you use them, just like before!  We'll tell you what you forgot
@@ -14,34 +13,34 @@ to check for instead of just segfaulting, though.
 Features
 --------
 
-* Automatically initializes as new GL functions are used.
+  * Automatically initializes as new GL functions are used.
-* GL 4.4 core and compatibility context support.
+  * GL 4.4 core and compatibility context support.
-* GLES 1/2/3 context support.
+  * GLES 1/2/3 context support.
-* Knows about function aliases so (e.g.) ```glBufferData()``` can be
+  * Knows about function aliases so (e.g.) `glBufferData()` can be
-  used with ```GL_ARB_vertex_buffer_object``` implementations, along
+    used with `GL_ARB_vertex_buffer_object` implementations, along
-  with GL 1.5+ implementations.
+    with GL 1.5+ implementations.
-* EGL, GLX, and WGL support.
+  * EGL, GLX, and WGL support.
-* Can be mixed with non-epoxy GL usage.
+  * Can be mixed with non-epoxy GL usage.
 
 Building
 --------
 
-    ./autogen.sh
+```sh
-    make
+mkdir _build && cd _build
-    sudo make install
+meson
+ninja
+sudo ninja install
+```
 
-Dependencies for debian:
+Dependencies for Debian:
 
-* automake
+  * meson
-* libegl1-mesa-dev
+  * libegl1-mesa-dev
-* xutils-dev
 
-Dependencies for OS X (macports):
+Dependencies for macOS (using MacPorts): 
 
-* automake
+  * pkgconfig
-* autoconf
+  * meson
-* xorg-util-macros
-* pkgconfig
 
 The test suite has additional dependencies depending on the platform.
 (X11, EGL, a running X Server).
@@ -51,27 +50,31 @@ Switching your code to using epoxy
 
 It should be as easy as replacing:
 
-    #include <GL/gl.h>
+```cpp
-    #include <GL/glx.h>
+#include <GL/gl.h>
-    #include <GL/glext.h>
+#include <GL/glx.h>
+#include <GL/glext.h>
+```
 
 with:
 
-    #include <epoxy/gl.h>
+```cpp
-    #include <epoxy/glx.h>
+#include <epoxy/gl.h>
+#include <epoxy/glx.h>
+```
 
 As long as epoxy's headers appear first, you should be ready to go.
 Additionally, some new helpers become available, so you don't have to
 write them:
 
-```int epoxy_gl_version()``` returns the GL version:
+`int epoxy_gl_version()` returns the GL version:
 
-* 12 for GL 1.2
+  * 12 for GL 1.2
-* 20 for GL 2.0
+  * 20 for GL 2.0
-* 44 for GL 4.4
+  * 44 for GL 4.4
 
-```bool epoxy_has_gl_extension()``` returns whether a GL extension is
+`bool epoxy_has_gl_extension()` returns whether a GL extension is
-available (```GL_ARB_texture_buffer_object```, for example).
+available (`GL_ARB_texture_buffer_object`, for example).
 
 Note that this is not terribly fast, so keep it out of your hot paths,
 ok?
@@ -81,17 +84,17 @@ Why not use libGLEW?
 
 GLEW has several issues:
 
-* Doesn't know about aliases of functions (There are 5 providers of
+  * Doesn't know about aliases of functions (There are 5 providers of
-  glPointParameterfv, for example, and you don't want to have to
+    `glPointParameterfv()`, for example, and you don't want to have to
-  choose which one to call when they're all the same).
+    choose which one to call when they're all the same).
-* Doesn't support GL 3.2+ core contexts
+  * Doesn't support GL 3.2+ core contexts
-* Doesn't support GLES.
+  * Doesn't support GLES.
-* Doesn't support EGL.
+  * Doesn't support EGL.
-* Has a hard-to-maintain parser of extension specification text
+  * Has a hard-to-maintain parser of extension specification text
-  instead of using the old .spec file or the new .xml.
+    instead of using the old .spec file or the new .xml.
-* Has significant startup time overhead when ```glewInit()```
+  * Has significant startup time overhead when `glewInit()`
-  autodetects the world.
+    autodetects the world.
-* User-visible multithreading support choice for win32.
+  * User-visible multithreading support choice for win32.
 
 The motivation for this project came out of previous use of libGLEW in
 [piglit](http://piglit.freedesktop.org/).  Other GL dispatch code
@@ -104,17 +107,16 @@ meant replacing every single piece of GLEW, so we built
 piglit-dispatch from scratch.  And since we wanted to reuse it in
 other GL-related projects, this is the result.
 
-win32 issues
+Known issues when running on Windows
-------------
+------------------------------------
 
 The automatic per-context symbol resolution for win32 requires that
-epoxy knows when ```wglMakeCurrent()``` is called, because
+epoxy knows when `wglMakeCurrent()` is called, because `wglGetProcAddress()`
-wglGetProcAddress() return values depend on the context's device and
+returns values depend on the context's device and pixel format.  If
-pixel format.  If ```wglMakeCurrent()``` is called from outside of
+`wglMakeCurrent()` is called from outside of epoxy (in a way that might
-epoxy (in a way that might change the device or pixel format), then
+change the device or pixel format), then epoxy needs to be notified of
-epoxy needs to be notified of the change using the
+the change using the `epoxy_handle_external_wglMakeCurrent()` function.
-```epoxy_handle_external_wglMakeCurrent()``` function.
+
-
+The win32 `wglMakeCurrent()` variants are slower than they should be,
-The win32 wglMakeCurrent() variants are slower than they should be,
 because they should be caching the resolved dispatch tables instead of
 resetting an entire thread-local dispatch table every time.