diff --git a/README.md b/README.md
index 11e0c34e..fabc5a1c 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,4 @@
-libco
------
+# libco
libco is a cooperative multithreading library written in C89.
@@ -21,7 +20,10 @@ It currently includes backends for:
* POSIX platforms (setjmp)
* Windows platforms (fibers)
-License
-=======
+See [doc/targets.md] for details.
+
+See [doc/usage.md] for documentation.
+
+## License
libco is released under the ISC license.
diff --git a/doc/style.css b/doc/style.css
deleted file mode 100644
index ab070256..00000000
--- a/doc/style.css
+++ /dev/null
@@ -1,12 +0,0 @@
-body {
- background: #333;
- color: #fff;
-}
-
-code {
- background: #444;
-}
-
-a {
- color: #aaf;
-}
diff --git a/doc/targets.html b/doc/targets.html
deleted file mode 100644
index d6211a15..00000000
--- a/doc/targets.html
+++ /dev/null
@@ -1,89 +0,0 @@
-
-
-
-
-
-
-
-Supported targets:
-
-Note that supported targets are only those that have been tested and confirmed
-working. It is quite possible that libco will work on more processors, compilers
-and operating systems than those listed below.
-
-
-libco.x86
-Overhead: ~5x
-Supported processor(s): 32-bit x86
-Supported compiler(s): any
-Supported operating system(s):
-
Windows
-
Mac OS X
-
Linux
-
BSD
-
-
-
-libco.amd64
-Overhead: ~10x (Windows), ~6x (all other platforms)
-Supported processor(s): 64-bit amd64
-Supported compiler(s): any
-Supported operating system(s):
-
-
-
-
diff --git a/doc/targets.md b/doc/targets.md
new file mode 100644
index 00000000..29400c48
--- /dev/null
+++ b/doc/targets.md
@@ -0,0 +1,68 @@
+# Supported targets
+In the following lists, supported targets are only those that have been tested
+and confirmed working. It is quite possible that libco will work on more
+processors, compilers and operating systems than those listed below.
+
+The "Overhead" is the cost of switching co-routines, as compared to an ordinary
+C function call.
+
+## libco.x86
+* **Overhead:** ~5x
+* **Supported processor(s):** 32-bit x86
+*** Supported compiler(s**): any
+* **Supported operating system(s):**
+ * Windows
+ * Mac OS X
+ * Linux
+ * BSD
+
+## libco.amd64
+* **Overhead:** ~10x (Windows), ~6x (all other platforms)
+* **Supported processor(s):** 64-bit amd64
+*** Supported compiler(s**): any
+* **Supported operating system(s):**
+ * Windows
+ * Mac OS X
+ * Linux
+ * BSD
+
+## libco.ppc
+* **Overhead:** ~20x
+* **Supported processor(s):** 32-bit PowerPC, 64-bit PowerPC
+* **Supported compiler(s):** GNU GCC
+* **Supported operating system(s):**
+ * Mac OS X
+ * Linux
+ * BSD
+ * Playstation 3
+
+**Note:** this module contains compiler flags to enable/disable FPU and Altivec
+support.
+
+## libco.fiber
+This uses Windows' "fibers" API.
+* **Overhead:** ~15x
+* **Supported processor(s):** Processor independent
+* **Supported compiler(s):** any
+* **Supported operating system(s):**
+ * Windows
+
+## libco.sjlj
+This uses the C standard library's `setjump`/`longjmp` APIs.
+* **Overhead:** ~30x
+* **Supported processor(s):** Processor independent
+* **Supported compiler(s):** any
+* **Supported operating system(s):**
+ * Mac OS X
+ * Linux
+ * BSD
+ * Solaris
+
+## libco.ucontext
+This uses the POSIX "ucontext" API.
+* **Overhead:** ***~300x***
+* **Supported processor(s):** Processor independent
+* **Supported compiler(s):** any
+* **Supported operating system(s):**
+ * Linux
+ * BSD
diff --git a/doc/usage.html b/doc/usage.md
similarity index 53%
rename from doc/usage.html
rename to doc/usage.md
index 994072f9..cb0d1929 100644
--- a/doc/usage.html
+++ b/doc/usage.md
@@ -1,108 +1,130 @@
-
-
-
-
-
-
-
-License:
+# License
libco is released under the ISC license.
-
-Foreword:
+# Foreword
libco is a cross-platform, permissively licensed implementation of
cooperative-multithreading; a feature that is sorely lacking from the ISO C/C++
-standard.
+standard.
+
The library is designed for maximum speed and portability, and not for safety or
features. If safety or extra functionality is desired, a wrapper API can easily
-be written to encapsulate all library functions.
+be written to encapsulate all library functions.
+
Behavior of executing operations that are listed as not permitted below result
in undefined behavior. They may work anyway, they may cause undesired / unknown
-behavior, or they may crash the program entirely.
+behavior, or they may crash the program entirely.
+
The goal of this library was to simplify the base API as much as possible,
implementing only that which cannot be implemented using pure C. Additional
functionality after this would only complicate ports of this library to new
platforms.
-
-Porting:
+# Porting
This document is included as a reference for porting libco. Please submit any
ports you create to me, so that libco can become more useful. Please note that
since libco is permissively licensed, you must submit your code as a work of the
public domain in order for it to be included in the official distribution.
+
Full credit will be given in the source code of the official release. Please
do not bother submitting code to me under any other license -- including GPL,
LGPL, BSD or CC -- I am not interested in creating a library with multiple
different licenses depending on which targets are used.
-
-Synopsis:
-
-typedef void* cothread_t;
-
-cothread_t co_active();
-cothread_t co_create(unsigned int heapsize, void (*coentry)(void));
-void co_delete(cothread_t cothread);
-void co_switch(cothread_t cothread);
-
-
+Note that there are a variety of compile-time options in `settings.h`,
+so if you want to use libco on a platform where it is not supported by default,
+you may be able to configure the implementation appropriately without having
+to make a whole new port.
-Usage:
-
+# Synopsis
+```c
+typedef void* cothread_t;
-typedef void* cothread_t;
-Handle to cothread.
-Handle must be of type void*.
-A value of null (0) indicates an uninitialized or invalid
-handle, whereas a non-zero value indicates a valid handle.
-
+cothread_t co_active();
+cothread_t co_create(unsigned int heapsize, void (*coentry)(void));
+void co_delete(cothread_t cothread);
+void co_switch(cothread_t cothread);
+```
-cothread_t co_active();
-Return handle to current cothread. Always returns a valid handle, even when
-called from the main program thread.
-
+# Usage
+## cothread_t
+```c
+typedef void* cothread_t;
+```
+Handle to cothread.
-cothread_t co_derive(void* memory, unsigned int heapsize, void (*coentry)(void));
-Initializes new cothread.
-This function is identical to co_create, only it attempts to use the provided
+Handle must be of type `void*`.
+
+A value of `null` (0) indicates an uninitialized or invalid handle, whereas a non-zero value indicates a valid handle.
+
+## co_active
+```c
+cothread_t co_active();
+```
+Return handle to current cothread.
+
+Always returns a valid handle, even when called from the main program thread.
+
+## co_derive
+```c
+cothread_t co_derive(void* memory,
+ unsigned int heapsize,
+ void (*coentry)(void));
+```
+Initializes new cothread.
+
+This function is identical to `co_create`, only it attempts to use the provided
memory instead of allocating new memory on the heap. Please note that certain
implementations (currently only Windows Fibers) cannot be created using existing
memory, and as such, this function will fail.
-
-cothread_t co_create(unsigned int heapsize, void (*coentry)(void));
-Create new cothread.
-Heapsize is the amount of memory allocated for the cothread stack, specified
+## co_create
+```c
+cothread_t co_create(unsigned int heapsize,
+ void (*coentry)(void));
+```
+Create new cothread.
+
+`heapsize` is the amount of memory allocated for the cothread stack, specified
in bytes. This is unfortunately impossible to make fully portable. It is
-recommended to specify sizes using `n * sizeof(void*)'. It is better to err
+recommended to specify sizes using `n * sizeof(void*)`. It is better to err
on the side of caution and allocate more memory than will be needed to ensure
compatibility with other platforms, within reason. A typical heapsize for a
-32-bit architecture is ~1MB.
+32-bit architecture is ~1MB.
+
When the new cothread is first called, program execution jumps to coentry.
This function does not take any arguments, due to portability issues with
passing function arguments. However, arguments can be simulated by the use
-of global variables, which can be set before the first call to each cothread.
-coentry() must not return, and should end with an appropriate co_switch()
-statement. Behavior is undefined if entry point returns normally.
+of global variables, which can be set before the first call to each cothread.
+
+`coentry()` must not return, and should end with an appropriate `co_switch()`
+statement. Behavior is undefined if entry point returns normally.
+
Library is responsible for allocating cothread stack memory, to free
the user from needing to allocate special memory capable of being used
-as program stack memory on platforms where this is required.
-User is always responsible for deleting cothreads with co_delete().
-Return value of null (0) indicates cothread creation failed.
-
+as program stack memory on platforms where this is required.
-void co_delete(cothread_t cothread);
-Delete specified cothread.
-Null (0) or invalid cothread handle is not allowed.
-Passing handle of active cothread to this function is not allowed.
-Passing handle of primary cothread is not allowed.
-
+User is always responsible for deleting cothreads with `co_delete()`.
+
+Return value of `null` (0) indicates cothread creation failed.
+
+## co_delete
+```c
+void co_delete(cothread_t cothread);
+```
+Delete specified cothread.
+
+`null` (0) or invalid cothread handle is not allowed.
-void co_switch(cothread_t cothread);
-Switch to specified cothread.
-Null (0) or invalid cothread handle is not allowed.
Passing handle of active cothread to this function is not allowed.
-
-
-
+Passing handle of primary cothread is not allowed.
+
+## co_switch
+```c
+void co_switch(cothread_t cothread);
+```
+Switch to specified cothread.
+
+`null` (0) or invalid cothread handle is not allowed.
+
+Passing handle of active cothread to this function is not allowed.