Document future plans for API cleanup.

1 files changed, 39 insertions, 6 deletions

diff --git a/www/future.html b/www/future.html
index 94a3ac6b..d720f0c1 100644
--- a/www/future.html
+++ b/www/future.html
@@ -62,9 +62,9 @@ Future of the GPS project
           alt="Valid XHTML 1.0!" height="31" width="88" /></a>
 </div>
 <div id="Content">
-<p>This page is our roadmp for future features and releases.</p>
+<p>This page is our roadmap for future features and releases.</p>
 
-<h2>The new GPSD protocol</h2>
+<h2 id="new_protocol">The new GPSD protocol</h2>
 
 <p>2.90 has shipped, and with it the redesign of GPSD's wire protocol.
 While this brings many benefits (including, immediately, the ability
@@ -78,16 +78,49 @@ new protocol.</a>. See that document is our tentative release schedule:</p>
 <p>For more on specific tasks planned for upcoming releases, see our
 <a href="TODO">file</a>.</p>
 
-<h2>Changing hosting sites</h2>
+<h2 id="hosting">Changing hosting sites</h2>
 
 <p>We're presently (March 2010) hosted at <a
 href="http://developer.berlios.de">berlios.de</a>, but find that it
 has become extremely flaky of late (logins failing due to broken SSL
-certs is the most recent symptom).  We plan to change sitessomewtime
+certs is the most recent symptom).  We plan to change sites some time
 in 2010.</p>
 
+<h2 id="api_cleanup">Client API cleanup</h2>
+
+<p>This is not a near-term project.</p>
+
+<p>The client API has some historical baggage, unfortunate naming, and
+scar tissue in it.  At some point we're going to bump the API major
+version number to 5 and make the following changes:<p>
+
+<ul>
+<li><p>gps_open_r() will be renamed to gps_open(). The existing
+gps_open() will go away.</p></li>
+
+<li><p>The 'waiting' and 'buffer' members of privdata will move into
+the public part of gps.h</p></li>
+
+<li><p>gps_set_raw_hook() will be removed. Instead, clients will simply
+be able to look at the packet buffer directly. (Of course, this is
+only recommended when the PACKET_SET flag is up.)</p></li>
+
+<li><p>gps_poll() will be renamed to gps_read().</p></li>
+
+<li><p>There will be a new gps_poll() entry point that will perform
+a nonblocking poll of the daemon, using the (now experimental) ?POLL
+command).</p></li>
+</ul>
+
+<p>Client API users will have the API_MAJOR_VERSION symbol available to
+conditionalize their code so it will work with any version.</p>
+
+<p>What is most likely to trigger this change is the restoration of
+polling as a fully-supported mode in the wire protocol (it is
+presently experimental and buggy and <b>not recommended</b> for production
+use). At that point, the skew between what ?POLL does and what and
+gps_poll() does will become severe.</p>
+
 </div>
-<hr/>
-<script language="JavaScript" src="datestamp.js" type='text/javascript'></script>
 </body>
 </html>