Experiment with a new readme layout.

README.md

@@ -11,17 +11,97 @@
 </p>
 
 <p align="center">
-    <a href="#features">Features</a> -
+    <a href="#examples">Examples</a> -
+    <a href="#documentation">Documentation</a> -
+    <a href="#major-features">Major Features</a> -
     <a href="#supported-platforms">Supported Platforms</a> -
     <a href="#backends">Backends</a> -
     <a href="#building">Building</a> -
-    <a href="#examples">Examples</a> -
-    <a href="#documentation">Documentation</a> -
     <a href="#unofficial-bindings">Unofficial Bindings</a>
 </p>
 
-Features
+Examples
 ========
+This example shows how to decode and play a sound.
+
+```c
+#define MINIAUDIO_IMPLEMENTATION
+#include "../miniaudio.h"
+
+#include <stdio.h>
+
+void data_callback(ma_device* pDevice, void* pOutput, const void* pInput, ma_uint32 frameCount)
+{
+    ma_decoder* pDecoder = (ma_decoder*)pDevice->pUserData;
+    if (pDecoder == NULL) {
+        return;
+    }
+
+    ma_decoder_read_pcm_frames(pDecoder, pOutput, frameCount);
+
+    (void)pInput;
+}
+
+int main(int argc, char** argv)
+{
+    ma_result result;
+    ma_decoder decoder;
+    ma_device_config deviceConfig;
+    ma_device device;
+
+    if (argc < 2) {
+        printf("No input file.\n");
+        return -1;
+    }
+
+    result = ma_decoder_init_file(argv[1], NULL, &decoder);
+    if (result != MA_SUCCESS) {
+        return -2;
+    }
+
+    deviceConfig = ma_device_config_init(ma_device_type_playback);
+    deviceConfig.playback.format   = decoder.outputFormat;
+    deviceConfig.playback.channels = decoder.outputChannels;
+    deviceConfig.sampleRate        = decoder.outputSampleRate;
+    deviceConfig.dataCallback      = data_callback;
+    deviceConfig.pUserData         = &decoder;
+
+    if (ma_device_init(NULL, &deviceConfig, &device) != MA_SUCCESS) {
+        printf("Failed to open playback device.\n");
+        ma_decoder_uninit(&decoder);
+        return -3;
+    }
+
+    if (ma_device_start(&device) != MA_SUCCESS) {
+        printf("Failed to start playback device.\n");
+        ma_device_uninit(&device);
+        ma_decoder_uninit(&decoder);
+        return -4;
+    }
+
+    printf("Press Enter to quit...");
+    getchar();
+
+    ma_device_uninit(&device);
+    ma_decoder_uninit(&decoder);
+
+    return 0;
+}
+```
+More examples can be found in the [examples](examples) folder or online here: https://miniaud.io/docs/examples/
+
+
+Documentation
+=============
+Online documentation can be found here: https://miniaud.io/docs/
+
+Documentation can also be found at the top of [miniaudio.h](https://raw.githubusercontent.com/dr-soft/miniaudio/master/miniaudio.h)
+which is always the most up-to-date and authoritive source of information on how to use miniaudio. All other
+documentation is generated from this in-code documentation.
+
+
+Major Features
+==============
 - Your choice of either public domain or [MIT No Attribution](https://github.com/aws/mit-0).
 - Entirely contained within a single file for easy integration into your source tree.
 - No external dependencies except for the C standard library and backend libraries.
@@ -66,6 +146,9 @@ Features
   - WAV
 - Lock free ring buffer (single producer, single consumer).
 
+Refer to the [Programming Manual](https://miniaud.io/docs/manual/) for a more complete description of
+available features in miniaudio.
+
 
 Supported Platforms
 ===================
@@ -117,87 +200,8 @@ single translation unit (AKA unity builds), you can just #include the .c file in
 Note that the split version is auto-generated using a tool and is based on the main file in the root directory.
 If you want to contribute, please make the change in the main file.
 
-
-Examples
-========
-This example shows how to decode and play a sound.
-
-```c
-#define MINIAUDIO_IMPLEMENTATION
-#include "../miniaudio.h"
-
-#include <stdio.h>
-
-void data_callback(ma_device* pDevice, void* pOutput, const void* pInput, ma_uint32 frameCount)
-{
-    ma_decoder* pDecoder = (ma_decoder*)pDevice->pUserData;
-    if (pDecoder == NULL) {
-        return;
-    }
-
-    ma_decoder_read_pcm_frames(pDecoder, pOutput, frameCount);
-
-    (void)pInput;
-}
-
-int main(int argc, char** argv)
-{
-    ma_result result;
-    ma_decoder decoder;
-    ma_device_config deviceConfig;
-    ma_device device;
-
-    if (argc < 2) {
-        printf("No input file.\n");
-        return -1;
-    }
-
-    result = ma_decoder_init_file(argv[1], NULL, &decoder);
-    if (result != MA_SUCCESS) {
-        return -2;
-    }
-
-    deviceConfig = ma_device_config_init(ma_device_type_playback);
-    deviceConfig.playback.format   = decoder.outputFormat;
-    deviceConfig.playback.channels = decoder.outputChannels;
-    deviceConfig.sampleRate        = decoder.outputSampleRate;
-    deviceConfig.dataCallback      = data_callback;
-    deviceConfig.pUserData         = &decoder;
-
-    if (ma_device_init(NULL, &deviceConfig, &device) != MA_SUCCESS) {
-        printf("Failed to open playback device.\n");
-        ma_decoder_uninit(&decoder);
-        return -3;
-    }
-
-    if (ma_device_start(&device) != MA_SUCCESS) {
-        printf("Failed to start playback device.\n");
-        ma_device_uninit(&device);
-        ma_decoder_uninit(&decoder);
-        return -4;
-    }
-
-    printf("Press Enter to quit...");
-    getchar();
-
-    ma_device_uninit(&device);
-    ma_decoder_uninit(&decoder);
-
-    return 0;
-}
-```
-
-More examples can be found in the [examples](examples) folder.
-
-
-Documentation
-=============
-Documentation can be found at the top of [miniaudio.h](https://raw.githubusercontent.com/dr-soft/miniaudio/master/miniaudio.h)
-which is always the most up-to-date and authoritive source of information on how to use miniaudio.
-
-
 Vorbis Decoding
-===============
+---------------
 Vorbis decoding is enabled via stb_vorbis. To use it, you need to include the header section of stb_vorbis
 before the implementation of miniaudio. You can enable Vorbis by doing the following: