rewrite of OC branch difference docs; updates #463

following5 · following5 · commit d847f6face60 · 2018-11-24T16:05:02.000+01:00
diff --git a/okapi/services/caches/geocache/docs.xml b/okapi/services/caches/geocache/docs.xml
@@ -58,15 +58,16 @@
             <li><b>description</b> - inserts the OC team annotations into the
             description texts,</li>
             <li><b>separate</b> (recommended) - includes the <b>oc_team_annotation</b> field
-            instead.</li>
+            instead. You are REQUIRED to display its contents alongside with
+            the owner's cache listing.</li>
         </ul>
-        <p>Please note that you are REQUIRED to display OC team annotations
-        alongside with the owner's cache listing. In this they differ from
-        <i>OC team
-        <a href="%OKAPI:methodargref:services/logs/entry%">log entries</a></i>,
-        which will only be visible when logs are displayed.</p>
-        <p>OC team annotations so far are only in use at OCPL-based sites.
-        OCDE installations will ignore this parameter.</p>
+        <p>OC team annotations are not to be confused with "OC Team comment"
+        <a href='%OKAPI:methodargref:services/logs/entry%'>log entries</a>,
+        which have a similar purpose, but need not to be visible with the cache
+        description. OC team annotations will be deleted when obsolete, while
+        the log entries usually will stay.</p>
+        <p>Note that some OC installations do not implement team annotations. They will
+        ignore this parameter.</p>
     </opt>
     <opt name='lpc' default='10'>
         Log-entries per cache - the number of logs returned in the <b>latest_logs</b> field.
@@ -153,7 +154,8 @@
                 <ul>
                     <li><b>Own</b>, a moving geocache which is carried by the owner,</li>
                     <li><b>Podcast</b>, a geocache with attached MP3 file(s). The MP3
-                    data is not accessible via OKAPI.</li>
+                        data is not accessible via OKAPI. This type is only in use
+                        at Opencaching.US.</li>
                     <li>(Types may be added or removed. Your application MUST be
                         prepared for any new types and may handle them as "Other".)</li>
                 </ul>
@@ -174,8 +176,8 @@
                 known to be in poor condition, e.g. damaged. Usually there will be further
                 explanations in the log entries.</p>
 
-                <p>Please note that only OCDE-based Opencaching installations provide this
-                information. ODPL-based sites will always return <b>false</b> here.</p>
+                <p>Please note that some Opencaching installations don't provide
+                this information; they will always return <b>false</b>.</p>
             </li>
             <li><b>url</b> - URL of the cache's web page,</li>
             <li>
@@ -322,11 +324,13 @@
                 overall rating of the cache, or <b>null</b> when the geocache does not have a
                 sufficient amount of votes to have a rating.</p>
 
-                <p><b>Note:</b> Only OCPL-based Opencaching installations provide ratings for
-                their geocaches. On OCDE-based installations, this field will always contain
-                <b>null</b>.</p>
+                <p><b>Note:</b> Some installations don't provide ratings for
+                their geocaches; they will always return <b>null</b> for this
+                field. The <b>has_ratings</b> field of
+                <a href='%OKAPI:methodargref:services/caches/capabilities%'>services/caches/capabilities</a>
+                tells if ratings are available.</p>
 
-                <p><b>Note:</b> Currently OCPL exposes cache ratings as integers only.
+                <p><b>Note:</b> Currently OC sites expose cache ratings as integers only.
                 OKAPI used floats here for forward-compatibility only. In other words, currently
                 you can get 4.0 or 5.0 here, but not 4.5. This may change in the future though,
                 without notice.</p>
@@ -335,16 +339,17 @@
                 <p>%OKAPI:infotag:ocpl-specific% <b>rating_votes</b> - number of votes submitted
                 for the rating of this cache.</p>
 
-                <p><b>Note:</b> Only OCPL-based Opencaching installations provide ratings for
-                their geocaches. On OCDE-based installations, this field will always contain
-                <b>0</b>.</p>
+                <p><b>Note:</b> Some installations don't provide ratings for their geocaches;
+                they will always return <b>0</b> for this field. The <b>has_ratings</b> field of
+                <a href='%OKAPI:methodargref:services/caches/capabilities%'>services/caches/capabilities</a>
+                tells if ratings are available.</p>
             </li>
             <li>
                 <p>%OKAPI:infotag:ocpl-specific% <b>my_rating</b> - float (between 1 and 5),
                 the rating the user gave for this cache; <b>null</b> if the user did not rate.</p>
                 <p>This is private data. You will need Level 3 Authentication to access
                 this field.</p>
-                <p>See the notices on the <b>rating</b> field.</p>
+                <p>See the notes on the <b>rating</b> field.</p>
             </li>
             <li><b>recommendations</b> - number of recommendations for this cache,</li>
             <li>
@@ -414,10 +419,10 @@
                 </ul>
             </li>
             <li>
-                <p>%OKAPI:infotag:ocde-specific% <b>preview_image</b> - On OCDE-based
+                <p>%OKAPI:infotag:ocde-specific% <b>preview_image</b> - On some
                 installations, owners may select one of the <b>images</b>
                 (see above) as a preview image. You are encouraged to display it as a 'teaser'
-                for this cache. On OCPL-based installations this functionality is disabled and you
+                for this cache. On other installations this functionality is disabled and you
                 will always get the <b>null</b> value here.</p>
 
                 <p>The value of <b>preview_image</b> is either <b>null</b> or a dictionary describing
@@ -443,7 +448,8 @@
                 It will only partially respond to the <b>langpref</b> parameter and may
                 contain an arbitrary mixture of languages and differently localized data
                 (<a href='https://github.com/opencaching/okapi/issues/533'>why?</a>).
-                OCDE installations currently will always return an empty string.</p>
+                Some installations don't implement OC team annotations; they currently
+                always return an empty string for this field.</p>
             </li>
             <li>
                 <p><b>attribution_note</b> - the proper attribution note for the cache listing according
@@ -581,7 +587,7 @@
             <li>
                 <b>date_created</b> - date and time (ISO 8601) when the
                 geocache was listed at the Opencaching site. For OCDE-based installations
-                this is the date when it was published, while for ODPL installations it is the
+                this is the date when it was published, while for OCPL installations it is the
                 date when it was originally submitted. These dates differ if the
                 geocache is prepared and then published later.
             </li>
diff --git a/okapi/services/logs/edit/docs.xml b/okapi/services/logs/edit/docs.xml
@@ -74,7 +74,9 @@
     <opt name='rating' default='unchanged' infotags="ocpl-specific">
         <p>If the user rated the cache, the option <b>false</b> will withdraw
         that rating. Otherwise, it will be ignored (which includes
-        installations that do not provide geocache ratings).</p>
+        installations that do not provide geocache ratings; see the
+        <b>has_ratings</b> field of
+        <a href='%OKAPI:methodargref:services/caches/capabilities'>services/caches/capabilities</a>).</p>
     </opt>
     <opt name='langpref' default='en'>
         <p>Pipe-separated list of ISO 639-1 language codes. This indicates the
diff --git a/okapi/services/logs/entry/docs.xml b/okapi/services/logs/entry/docs.xml
@@ -157,7 +157,8 @@
                         state of the geocache listing.
                     </li>
                 </ul>
-                <p>Please note that OCPL-based installations will always return <b>null</b> here.</p>
+                <p>Please note that some OC installations do not implement this
+                flag and will always return <b>null</b>.</p>
             </li>
             <li><b>comment</b> - <a href='%OKAPI:docurl:html%'>HTML string</a>, text entered
                 with the log entry,
diff --git a/okapi/services/logs/submit/docs.xml b/okapi/services/logs/submit/docs.xml
@@ -95,14 +95,18 @@
     <opt name='rating' infotags="ocpl-specific">
         <p>An integer in range between 1 and 5 - user's optional rating of a found cache.</p>
         <p>Important: <b>logtype</b> has to be "Found it" or "Attended" in order to use
-        this argument.</p>
-        <p>Note: You should allow your user to <b>not</b> rate a found cache.</p>
-        <p>Note: Some OKAPI installations (OCDE codebase) currently do not support
-        cache ratings. On such installations user's rating will be <b>ignored</b>
-        (if you include the rating, log entry will be posted successfully, but
-        rating will be ignored). The <b>can_rate</b> field of
+        this argument. The rating may be rejected if the user already rated
+        this cache. You may consult the <b>can_rate</b> field of
         <a href="%OKAPI:methodargref:services/logs/capabilities%">services/logs/capabilities</a>
-        tells if <em>this</em> installation implements rating.</p>
+        to find out if the rating will be accepted.</p>
+
+        <p>Note: You should allow your user to <b>not</b> rate a found cache.</p>
+        <p>Note: Some OKAPI installations do not support cache ratings. On such
+        installations user's rating will always be <i>ignored</i> (if you include
+        the rating, log entry will be posted successfully, but rating will be
+        ignored). The <b>has_ratings</b> field of
+        <a href="%OKAPI:methodargref:services/caches/capabilities%">services/caches/capabilities</a>
+        tells if ratings are avaialble at this installation.</p>
     </opt>
     <opt name='recommend' default='false'>
         <p>Set to <b>true</b> if the user wants to recommend this cache.</p>
@@ -148,7 +152,7 @@
                 your user thinks that the cache's condition is fine.</p>
 
                 <p>Note: The <b>false</b> option currently is not evaluated by some
-                installation (OCPL-based sites). They will just ignore it.</p>
+                installations. They will just ignore it.</p>
             </li>
         </ul>
 
diff --git a/okapi/static/common.css b/okapi/static/common.css
@@ -20,7 +20,7 @@ body.api { background: #f5f1eb; }
 
 .infotag {
     display: inline-block;
-    background: #d9534f;
+    background: #5486b2;
     color: #fff !important;
     font-weight: normal;
     font-size: 68%;
@@ -63,6 +63,7 @@ a.infotag:hover {
 .article h1 .subh1 { font-size: 18px; font-weight: normal; color: #888; }
 .article h1 .subh1 b { font-weight: normal; color: #944; }
 .article h2 { clear: both; margin: 50px 0 10px 0; padding-top: 20px; font-weight: bold; font-style: italic; font-size: 22px; border-top: 2px dotted #aaf; }
+.article h3 { clear: both; margin: 20px 0 6px 0; font-weight: bold; font-style: italic; font-size: 18px }
 .article p { margin-bottom: 15px; }
 .article pre { margin-bottom: 15px; }
 .article ul { margin-bottom: 15px; margin-left: 35px; }
diff --git a/okapi/views/introduction/introduction.tpl.php b/okapi/views/introduction/introduction.tpl.php
@@ -475,40 +475,78 @@
 <div class='issue-comments' issue_id='117'></div>
 
 
-<h2 id='oc-branch-differences'>Differences between OCPL and OCDE branches</h2>
+<h2>Differences between Opencaching installations</h2>
 
-<p>Client developers should be aware that the are two primary Opencaching
-codebase branches. Some Opencaching installations are running the OCPL branch,
-some other are running the OCDE branch. (You can read more about this
-<a href='https://github.com/opencaching/opencaching-pl/wiki#brief-introduction-in-english'>here</a>.)</p>
+<p>Client developers should be aware that Opencaching sites provide different
+sets of features. E.g. Opencaching.US currently does not support OKAPI log
+image upload, and there is no geocache rating system at Opencaching.DE.
+OKAPI implements several mechanisms that either hide those differences -
+you don't need to care about them - or allows your application to automatically
+adjust to the Opencaching site's capabilities.</p>
 
-<p>In general, <b>OKAPI supports both of these branches via exactly the same
-API interface</b>, so you don't have to worry about the internal differences.
-However, you should be aware of the fact, that some things work a bit different
-on one branch, than they on the other. (Like, for example, OCDE doesn't have a
-cache rating system, so whenever you ask for the <b>rating</b> field of a
-geocache, you will get <b>null</b>.)</p>
+<h3>OKAPI versions</h3>
 
-<p>In order for you to easily notice methods, parameters and fields which are
-specific to only a single of these branches, we display the following "tags" in
-many places:</p>
+<p>Now and then, new features are added to OKAPI. They will be listed in the
+<a href="changelog.html">Changelog</a>, including version numbers. By comparing
+those numbers to the installation's current OKAPI version number, as returned by the 
+<a href='%OKAPI:methodargref:services/apisrv/installation%'>services/apisrv/installation</a>
+method, applications can detect if a new feature is available.</p>
+
+<h3 id='site-capabilities'>Site capabilities</h3>
+
+<p>OKAPI methods generally are designed to abstract from differences between OC
+installations. E.g. if some geocache or log property is not implemented, OKAPI
+will return <i>null</i> or <i>false</i> (as explained in the method docs).
+When submitting data, unsupported options are mostly ignored (as documented),
+or OKAPI will return an HTTP 200 result with the <i>success</i>=<i>false</i>
+field and a user-friendly explanation (as documented).</p>
+
+<p>However, when searching for caches or submitting content, there are a few
+exceptions where this can't be done. The docs then will refer to one of the
+following methods, that your application can call to find out what features
+are available:</p>
 
 <ul>
-    <li><span class='infotag infotag-ocpl-specific'>OCPL</span> - indicates
-    that a certain method, parameter or field was designed specificly for
-    OCPL-based Opencaching sites,</li>
+    <li><a href='services/attrs/attribute_index.html'>services/attrs/attribute_index</a>
+        - list of available cache attributes,</li>
+    <li><a href='services/caches/capabilities.html'>services/caches/capabilities</a>
+        - geocache capabilities,</li>
+    <li><a href='services/logs/capabilities.html'>services/logs/capabilities</a>
+        - logging capabilities, including the submission of cache
+        recommendations and ratings.</li>
+</ul>
+
+<p>This methods also return additional information, that allows to hide
+nonfunctional features from user interfaces. E.g. you may want to disable
+searching for geocaches by rating, if OKAPI will ignore the user's input
+(because the OC site does not implement rating).</p>
+
+<h3></h3>
+
+<h3 id='oc-branch-differences'>Branch tags</h3>
 
-    <li><span class='infotag infotag-ocde-specific'>OCDE</span> - indicates
-    that a certain method, parameter or field was designed specificly for
-    OCDE-based Opencaching sites.</li>
+<p>Throughout the OKAPI documentation, you will encounter options and fields
+that are tagged as "OCPL" or "OCDE". These tags have the following meaning:</p>
+
+<ul>
+    <li>
+        <span class='infotag infotag-ocde-specific'>OCDE</span> - This feature
+        currently is only in use at Opencaching sites that are based on the
+        OCDE software branch (currently Opencaching.DE/IT/FR). If your
+        application is NOT intended to be used with those sites, you may want
+        to skip this feature and not implement it.
+    </li>
+    <li>
+        <span class='infotag infotag-ocpl-specific'>OCPL</span> - This feature
+        currently is only in use at Opencaching sites that are based on the
+        OCPL software branch (currently Opencaching.PL, NL, US, UK, RO). If
+        your application is NOT intended to be used with those sites, you
+        may want to skip this feature and not implement it.
+    </li>
 </ul>
 
-<p>Please note, that <b>you still MAY use all such "marked" methods, parameters
-and fields on ALL OKAPI sites.</b> Our methods are designed in such a way that,
-even if they are not supported by the underlying Opencaching site, they still
-won't throw errors, etc. At worst, they will "fail silently", or return empty
-results. All these differences should be described in detail in the
-documentation of the affected methods, parameters and fields.</p>
+<p>In all other cases, you are recommended to ignore the branch tags. See above
+for more information on differences between Opencaching sites.</p>
 
 <p>If you have any questions about this, then ask them
 <a href="https://github.com/opencaching/okapi/issues/463">here</a>.</p>
