From 48e8ba2b69db78b4124a2031ee14f61848b5f38f Mon Sep 17 00:00:00 2001 From: Tim Bunce Date: Mon, 22 Nov 2010 20:38:15 +0000 Subject: Convert =items to =head3 where appropriate --- spec/spore_description.pod | 56 ++++++++++++++++++---------------------------- 1 file changed, 22 insertions(+), 34 deletions(-) diff --git a/spec/spore_description.pod b/spec/spore_description.pod index 7cbbeea..0918d6e 100644 --- a/spec/spore_description.pod +++ b/spec/spore_description.pod @@ -49,15 +49,13 @@ I've noted the obvious cases (lists) but the others also need changing to add do This part describes the API itself: -=over 4 - -=item B (optional) +=head3 B (optional) A simple name to describe the specification "name" : "CouchDB" -=item B (optional) +=head3 B (optional) A list of authors for this specification @@ -67,7 +65,7 @@ A list of authors for this specification XXX should be renamed to be plural? -=item B (optional) +=head3 B (optional) If the API has a fixed URL @@ -75,7 +73,7 @@ If the API has a fixed URL Should not including a trailing slash. -=item B (optional) +=head3 B (optional) A list of supported formats @@ -86,7 +84,7 @@ A list of supported formats XXX what does "supported format" actually mean? What's the effect? -=item B (optional) +=head3 B (optional) The version number of the current description, expressed as a string @@ -94,13 +92,13 @@ The version number of the current description, expressed as a string XXX Any semantics or just for documentation? -=item B (optional) +=head3 B (optional) A boolean to specify if this API requires authentication for all the methods "authentication" : 1 -=item B (required) +=head3 B (required) Specifies the methods to be defined. @@ -108,8 +106,6 @@ Specifies the methods to be defined. See L. -=back - The desciption B contain a list of at least one method =head2 METHOD DESCRIPTION @@ -118,15 +114,13 @@ A method must have a name, which is the key in the C hash described abo "public_timeline" : { ... } -=over 4 - -=item B (required) +=head3 B (required) An HTTP method "method" : "GET" -=item B (required) +=head3 B (required) Path for the given method. The path can contain I. A placeholder B begin with a <:>: @@ -136,7 +130,7 @@ B begin with a <:>: 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? -=item B (optional) +=head3 B (optional) A list of I parameters (contrast with C). This list will be used to replace value in placeholders, @@ -147,7 +141,7 @@ and if not used in the path, will be added to the query. "include_entities" ] -=item B (optional) +=head3 B (optional) A list of I parameters (contrast with C). This list will be used to replace value in placeholders, @@ -159,7 +153,7 @@ Parameters that are required B be repeated in the B field "format" ] -=item B (optional) +=head3 B (optional) A list of accepted HTTP status for this method @@ -170,20 +164,20 @@ A list of accepted HTTP status for this method An exception will be thrown if some other status is returned. -=item B (optional) +=head3 B (optional) A 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" -=item B (optional) +=head3 B (optional) A boolean to specify if this method requires authentication "authentication" : 0 -=item B (optional) +=head3 B (optional) Specify an url for this method, if different to C @@ -193,7 +187,7 @@ 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. -=item B (optional) +=head3 B (optional) A list of supported formats for this method, if different to C: @@ -202,15 +196,13 @@ A list of supported formats for this method, if different to C: "xml" ] -=item B (optional) +=head3 B (optional) A complete documentation for the given 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." -=back - -=head3 SAMPLE +=head2 SAMPLE A description for the twitter API (only the API description part and the first method): @@ -232,20 +224,16 @@ A description for the twitter API (only the API description part and the first m } } -=head3 CALLS +=head2 CALLS -=head1 CHANGELOGS +XXX -0.1: 2010.10.xx +=head1 CHANGELOGS -=over 4 - -=item * +=head2 0.1 - 2010.10.xx Initial version. -=back - =head1 ACKNOWLEDGEMENTS Some parts of this specification are adopted from the following specifications. -- cgit v1.2.3