Simplify the element titles to make them easy to link to.Plus other refinements.

1 files changed, 50 insertions, 40 deletions

diff --git a/spec/spore_description.pod b/spec/spore_description.pod
index 0918d6e..cd702c7 100644
--- a/spec/spore_description.pod
+++ b/spec/spore_description.pod
@@ -49,15 +49,15 @@ I've noted the obvious cases (lists) but the others also need changing to add do
 
 This part describes the API itself:
 
-=head3 B<name> (optional)
+=head3 name
 
-A simple name to describe the specification
+An optional simple name to describe the specification
 
     "name" : "CouchDB"
 
-=head3 B<author> (optional)
+=head3 author
 
-A list of authors for this specification
+An optional list of authors for this specification
 
     "author" : [
       "franck cuny <franck@lumberjaph.net>"
@@ -65,17 +65,17 @@ A list of authors for this specification
 
 XXX should be renamed to be plural?
 
-=head3 B<api_base_url> (optional)
+=head3 api_base_url
 
-If the API has a fixed URL
+An optional base fixed URL for this API
 
     "api_base_url" : "http://api.twitter.com/1"
 
 Should not including a trailing slash.
 
-=head3 B<api_format> (optional)
+=head3 api_format
 
-A list of supported formats
+An optional list of supported formats
 
     "api_format" : [
       "json"
@@ -84,55 +84,63 @@ A list of supported formats
 
 XXX what does "supported format" actually mean? What's the effect?
 
-=head3 B<version> (optional)
+=head3 version
 
-The version number of the current description, expressed as a string
+An optional version number for the current description, expressed as a string
 
     "version" : "0.1"
 
 XXX Any semantics or just for documentation?
 
-=head3 B<authentication> (optional)
+=head3 authentication
 
-A boolean to specify if this API requires authentication for all the methods
+An optional boolean to specify if this API requires authentication for all the methods
 
     "authentication" : 1
 
-=head3 B<methods> (required)
+The default is false.
 
-Specifies the methods to be defined.
-
-    "methods" : { ... }
+=head3 methods
 
+A mandatory hash of method descriptions.
 See L</METHOD DESCRIPTION>.
 
-The desciption B<MUST> contain a list of at least one method
+    "methods" : { ... }
+
+The C<methods> hash B<MUST> contain at least one method.
 
 =head2 METHOD DESCRIPTION
 
-A method must have a name, which is the key in the C<methods> hash described above:
+A method must have a name, which is the key in the L</methods> hash
 
-    "public_timeline" : { ... }
+    "methods" : {
+        "public_timeline" : { ... }
+    }
 
-=head3 B<method> (required)
+=head3 method
 
-An HTTP method
+The mandatory C<method> attribute specifies the HTTP method to use for this call
 
     "method" : "GET"
 
-=head3 B<path> (required)
+=head3 path
+
+The mandatory C<path> attribute specifies the URI path for this method.
 
-Path for the given method. The path can contain I<placeholders>. A placeholder
+    "path" : "/login"
+
+The path can contain I<placeholders>. A placeholder
 B<MUST> begin with a <:>:
 
     "path" : "/statuses/public_timeline.:format"
 
 XXX How can non-placeholder :foo's be included in the path? ie is there an escape mechanism?
-What happens in this example if 'format' isn't listed in params?
+XXX What happens in this example if 'format' isn't listed in params/required?
+XXX What happens if a parameter needs to be followed by a word character? ie can something like :{format}foo be used?
 
-=head3 B<params> (optional)
+=head3 params
 
-A list of I<optional> parameters (contrast with C<required>).
+An optional list of I<optional> parameters (contrast with L</required>).
 This list will be used to replace value in placeholders,
 and if not used in the path, will be added to the query.
 
@@ -141,9 +149,9 @@ and if not used in the path, will be added to the query.
       "include_entities"
     ]
 
-=head3 B<required> (optional)
+=head3 required
 
-A list of I<required> parameters (contrast with C<params>).
+An optional list of I<required> parameters (contrast with L</params>).
 This list will be used to replace value in placeholders,
 and if not used in the path, will be added to the query.
 
@@ -153,9 +161,9 @@ Parameters that are required B<MUST NOT> be repeated in the B<params> field
       "format"
     ]
 
-=head3 B<expected> (optional)
+=head3 expected
 
-A list of accepted HTTP status for this method
+An optional list of valid HTTP response status values for this method
 
     "expected" : [
       200,
@@ -164,22 +172,24 @@ A list of accepted HTTP status for this method
 
 An exception will be thrown if some other status is returned.
 
-=head3 B<description> (optional)
+=head3 description
 
-A simple description for the method. This should not be considered as
+An optional simple description for the method. This should not be considered as
 documentation.
 
     "description" : "Returns the 20 most recent statuses, including retweets if they exist, from non-protected users"
 
-=head3 B<authentication> (optional)
+=head3 authentication
 
-A boolean to specify if this method requires authentication
+An optional boolean to specify if this method requires authentication
 
     "authentication" : 0
 
-=head3 B<base_url> (optional)
+The default is false.
+
+=head3 base_url
 
-Specify an url for this method, if different to C<api_base_url>
+An optional base url for this method, if different to L</api_base_url>
 
     "base_url" : "http://api.twitter.com/1"
 
@@ -187,18 +197,18 @@ Should not including a trailing slash.
 
 XXX would be nice to be able to express this as a relative url (relative to api_base_url) That could be handled at build time.
 
-=head3 B<format> (optional)
+=head3 format
 
-A list of supported formats for this method, if different to C<api_format>:
+An optional list of supported formats for this method, if different to L</api_format>:
 
     "format" : [
       "json",
       "xml"
     ]
 
-=head3 B<documentation> (optional)
+=head3 documentation
 
-A complete documentation for the given method
+Optional complete documentation text for the method
 
     "documentation" : "The public timeline is cached for 60 seconds. Requesting more frequently than that will not return any more data, and will count against your rate limit usage."