simple clarity/organization edits

1 files changed, 69 insertions, 37 deletions

diff --git a/spec.md b/spec.md
index 2c8fbe1..4b032f5 100644
--- a/spec.md
+++ b/spec.md
@@ -1,7 +1,7 @@
 # [REST API for Music Collections (RAMC)](http://git.zx2c4.com/ramc-spec/about)
 ### by Jason A. Donenfeld (<Jason@zx2c4.com>) and Adrian Sampson (<adrian@radbox.org>)
 
-RAMC (pronounced "ram-see", like the Pharaoh) is a simple REST API for accessing music collections in a standard unified way. Servers implement RAMC, and various clients -- web pages, smartphone apps, desktop programs -- talk RAMC with servers. It is currently in use by [ZX2C4 Music](http://git.zx2c4.com/zmusic-ng/about) and [Beets](http://beets.radbox.org/), with many more apps to come.
+RAMC (REST API for Music Collections; pronounced "ram-see", like the Pharaoh) is a simple REST API for accessing music collections in a standard unified way. Servers implement RAMC, and various clients -- web pages, smartphone apps, desktop programs -- talk RAMC with servers. It is currently in use by [ZX2C4 Music](http://git.zx2c4.com/zmusic-ng/about) and [Beets](http://beets.radbox.org/), with many more apps to come.
 
 ![RAMC Logo](http://git.zx2c4.com/ramc-spec/plain/logo.png)
 
@@ -11,18 +11,20 @@ This *draft* standard will be codified into version 1.0 on February 28th, 2013.
 
 ## Endpoints
 
-All API endpoints that return a value return JSON, unless otherwise noted.
+All API endpoints that return a value return a JSON object unless otherwise noted.
 
 ### <a name="query"></a> Query
 
-#### `GET /query/<object type>/<search query>`
-#### `GET /query/<object type>`
+**`GET /query/<object type>/<search query>`**  
+**`GET /query/<object type>`**
 
-* [Requires authentication](#authentication)
+[Requires authentication.](#authentication)
 
-The `query` request returns a listing of songs, albums, or artists based on the specified `<search query>`.
+The `query` request returns a listing of songs, albums, or artists (as specified by `<object type>`) matching the specified `<search query>`. If the query is omitted, returns all objects in the system.
 
-Each word of `<search query>` is matched as a substring against the artist, album, and title of each song. Prefixes of `artist:`, `album:`, and `title:`, _or of any other metadata attribute_, can be used to match exact strings against the respective metadata keys. `*` can be used as a wildcard when matches are exact. All matches, exact or inexact, are case-insensitive. Posix shell-style quoting and escaping is honored. Example searches:
+#### The Query String
+
+Each word of `<search query>` in the request URL is matched as a substring against the artist, album, and title of each song. Prefixes of `artist:`, `album:`, and `title:`, _or of any other metadata attribute_, can be used to match exact strings against the respective metadata keys. `*` can be used as a wildcard when matches are exact. All matches, exact or inexact, are case-insensitive. Posix shell-style quoting and escaping is honored. Example searches:
 
 * `charles ming`
 * `changes mingus`
@@ -33,17 +35,48 @@ Each word of `<search query>` is matched as a substring against the artist, albu
 
 If no `<search query>` is provided, all items are matched.
 
-Two optional query strings, `offset` and `limit` provide pagination functionality. `offset` begins listings for the `<object type>` at a 0-based record offset. `limit` limits the number of `<object type>` entries to a given length. Each returned object contains a key `total` containing the total number of records, as if `limit` nor `offset` were not specified, as well as an `offset` key containing the same value as provided via the `offset` query string parameter.
+#### Optional Parameters
+
+These endpoints support some optional parameters, which are passed as GET parameters (i.e., `?key=value`).
+
+* **`offset` and `limit`**: These parameters provide pagination functionality. `offset` begins listings at a zero-based record offset. `limit` specifies the maximum number of records to return. The returned object contains a key `total` containing the total number of records, irrespective of `limit` and `offset`, as well as an `offset` key containing the same value as provided via the `offset` query string parameter. If `limit` is zero, then no limit is used (the default behavior).
+
+* **`sort`**: By default, items returned are sorted by artist, then year, then album, then disc, then track, and then title. Alternative sorting can be provided with the `sort` query string parameter which takes a space-delimited list of metadata keys by which to sort. Each key is sorted in ascending order by default. To sort a key in a descending order, prefix it with `-`. All sorting is case-insensitive.
+
+#### Returned Value
+
+The JSON object returned at this endpoint has the following structure:
+
+    {
+        "total": <integer>,
+        "offset": <integer>,
+        "<object type>": [
+            <object>,
+            <object>,
+            ...
+        ]
+    }
 
-By default, items returned are sorted by artist, then year, then album, then disc, then track, and then title. Alternative sorting can be provided with the `sort` query string parameter which takes a space-delimited list of metadata keys by which to sort. Each key is sorted in ascending order. To sort a key in a descending order, prefix it with `-`. All sorting is case-insensitive.
+The keys of each object in the list depends on the type of object requested. The allowed object types are `songs`, `albums`, and `artists`.
 
-This endpoint is specialized by `<object type>`:
+##### <a name="songs"></a> Songs: `GET /query/songs/<search query>`
 
-#### <a name="songs"></a> Songs: `GET /query/songs/<search query>`
+Each song object (in the `songs` array of the result object) contains at least these keys:
 
-The return value is an object containing the pagination parameters, and an array assigned to the key `songs`. Each item in the array is an object containing, at the least, the a unique identifier, `id`, the original [`mimetype`](#mimetypes) of the song's file, and a `title`. It should contain an arbitrary amount of additional metadata, including `album`, `artist`, `length` (in seconds, as a floating point number), `track`, `genre`, `year`, etc.
+* `id`: A unique identifier of any scalar JSON type.
+* `mimetype`: The [MIME type](#mimetypes) of the underlying file.
+* `title`: The title of the song.
 
-##### `GET /query/songs/hendrix`
+Other keys may also be included; for example:
+
+* `album`
+* `artist`
+* `length`
+* `track`
+* `genre`
+* `year`
+
+**`GET /query/songs/hendrix`**
 
 	{
 		"total": 311,
@@ -71,11 +104,13 @@ The return value is an object containing the pagination parameters, and an array
 		]
 	}
 
-#### <a name="artists"></a> Artists: `GET /query/artists/<search query>`
+##### <a name="artists"></a> Artists: `GET /query/artists/<search query>`
 
-The return value is an object containing the pagination parameters and an array assigned to the key `artists` of objects containing the name of the artist in the `artist` key.
+Each artist object must contain at least the `artist` key, a string naming the artist.
 
-##### `GET /query/artists/title:Red+House`
+Two `include` terms are available: `songs` and `albums`. When either is used alone, each artist objects contain that key mapping to a list of all objects of that type associated with the artist. When both keys are used, the artist object contains only an `albums` key, which itself contains a `songs` key.
+
+**`GET /query/artists/title:Red+House`**
 
 	{
 		"total": 3,
@@ -94,9 +129,7 @@ The return value is an object containing the pagination parameters and an array
 	}
 	
 
-The `include` query string parameter is a space separated list of additional objects to include. `songs` and `albums` are acceptable keys. The response adds respective objects to each existing artist object:
-
-##### `GET /query/artists/title:Red+House?include=albums`
+**`GET /query/artists/title:Red+House?include=albums`**
 
 	{
 		"total": 3,
@@ -132,7 +165,7 @@ The `include` query string parameter is a space separated list of additional obj
 		]
 	}
 
-##### `GET /query/artists/title:Red+House?include=songs`
+**`GET /query/artists/title:Red+House?include=songs`**
 
 	{
 		"total": 3,
@@ -155,7 +188,7 @@ The `include` query string parameter is a space separated list of additional obj
 		]
 	}
 
-##### `GET /query/artists/title:Red+House?include=songs+albums`
+**`GET /query/artists/title:Red+House?include=songs+albums`**
 
 	{
 		"total": 3,
@@ -185,11 +218,13 @@ The `include` query string parameter is a space separated list of additional obj
 		]
 	}
 
-#### <a name="albums"></a> Albums: `GET /query/albums/<search query>`
+##### <a name="albums"></a> Albums: `GET /query/albums/<search query>`
 
-The return value is an object containing the pagination parameters and an array assigned to the key `albums` of objects containing the name of each album in the `album` key, and any additional metadata about each album.
+Each album object must contain at least the `album` key, the title of the object. Other keys might include per-album metadata such as `year` and `genre`.
 
-##### `GET /query/albums/title:Red+Ho*`
+Two `include` terms are available: `songs` and `artists`.
+
+**`GET /query/albums/title:Red+Ho*`**
 
 	{
 		"total": 3,
@@ -210,10 +245,7 @@ The return value is an object containing the pagination parameters and an array
 		]
 	}
 	
-
-The `include` query string parameter is a space separated list of additional objects to include. `songs` and `artists` are acceptable keys. The response adds respective objects to each existing album object:
-
-##### `GET /query/albums/title:Red+Ho*?include=songs`
+**`GET /query/albums/title:Red+Ho*?include=songs`**
 
 	{
 		"total": 3,
@@ -247,7 +279,7 @@ The `include` query string parameter is a space separated list of additional obj
 		]
 	}
 
-##### `GET /query/albums/title:Red+Ho*?include=artists`
+**`GET /query/albums/title:Red+Ho*?include=artists`**
 
 	{
 		"total": 3,
@@ -269,7 +301,7 @@ The `include` query string parameter is a space separated list of additional obj
 		"artists": [ "Albert King", "G3", "Jimi Hendrix" ]
 	}
 
-##### `GET /query/albums/title:Red+House?include=songs+artists`
+**`GET /query/albums/title:Red+House?include=songs+artists`**
 
 	{
 		"total": 3,
@@ -308,12 +340,12 @@ Note: the `artists` object for the `include` query string is superfluous, and ex
 
 ### <a name="files"></a>Song Files
 
-#### `GET /song/<id>.<ext>`
-#### `GET /song/<id>`
+**`GET /song/<id>.<ext>`**  
+**`GET /song/<id>`**
 
-* [Requires authentication](#authentication)
+[Requires authentication.](#authentication)
 
-Returns the data in the music file specified by `<id>` in the format given by `<ext>`. `<ext>` may be the original format's [preferred extension](#mimetypes), or a [transcodable extension](#mimetypes). If the second form is used, which lacks the `<ext>` parameter, the original format will be returned, unless the HTTP `Accepts:` header provides a [transcodable mimetype](#mimetype). If a format is requested that is not the song's original format, the server will transcode it. Use of original formats by clients is preferred, to cut down on server load and to preserve quality.
+Returns the data in the music file specified by `<id>` in the format given by `<ext>`. `<ext>` may be the original format's [preferred extension](#mimetypes), or a [transcodable extension](#mimetypes). If the second form is used, which lacks the `<ext>` parameter, the original format will be returned, unless the HTTP `Accept:` header provides a [transcodable mimetype](#mimetype). If a format is requested that is not the song's original format, the server will transcode it. Use of original formats by clients is preferred, to cut down on server load and to preserve quality.
 
 * If the requested format or id is unable to be returned, an `HTTP 404 Not Found` response shall be returned.
 * The `Content-Range` HTTP header and support for `HTTP 206 Partial Response` are recommended, at least for non-transcoded responses. 
@@ -323,9 +355,9 @@ Returns the data in the music file specified by `<id>` in the format given by `<
 
 ### <a name="zip"></a> Zip Bundles
 
-#### `POST /zip`
+**`POST /zip`**
 
-* [Requires authentication](#authentication)
+[Requires authentication.](#authentication)
 
 Takes arbitrary number of form parmeters with the key of `id` and returns a zip file containing each song using a reasonable filename containing at least the `title` of each song, as well as the [correct extension](#mimetypes).
 
@@ -465,7 +497,7 @@ Returns an object containing an array of song downloads and zip downloads, with
 
 ## <a name="authentication"></a>Authentication
 
-All endpoints that require authentication may authenticate through one of the following methods:
+A server may require authentication to access some indicated endpoints. To authenticate a request, a client can provide one of three styles of credentials:
 
 * A correct username and password to `username` and `password` query strings, respectively.
 * A [valid token](#login) to the `token` query string parameter.