Hi,

For me one of the hardest parts of maintaining a cURL language extension
is maintaining the cURL documentation for that language (well, ok, I
haven't done it that well, but that's because its hard). cURL has a ton
of options, and more are constantly being added (not that this is a bad
thing :), which makes keeping the documentation up a job that isn't that
fun... One of the other things that makes it even less appetizing, is
that the documentation should really be the same between all languages,
at least for the different options, the only thing that really changes
is the variable types. With some the mapping is quite simple: double ->
float, long -> int, char * -> string (in the case of php), and others
are a bit more complex: structure -> associative array, linked list ->
numerical array.

But the basic definition of each of the options is the same, the types
are the only thing that really changes. Therefore, I was thinking that
perhaps we could have some sort of simple xml (or other text format)
file that holds the cURL documentation, then it would be quite simple to
generate the docs for other languages, something like:

<option id="CURLOPT_URL">
 <name>CURLOPT_URL</name>
 <arg>
  <type id="zerocharstring"/>
  <name>url</name>
 </arg>
 <description>
  The actual URL to deal with.
  <ref type="memorymanagement">
   The string must remain present until curl no
   longer needs it, as it doesn't copy the string.
  </ref>
  <note>
   This option is (the only one) required to be set before
   <ref type="function">curl_easy_perform</function> is called.
  </note>
 </description>
</option>

Using this basic XML format, it would then be possible to generate the
cURL docs for a variety of different languages, in a variety of
different formats (preferably all of them output to docbook xml).

Looking at this, it does seem a bit complex for the task at hand, but I
don't see a better way of doing it, and I really think that it would be
beneficial if _every_ language extension could have a complete api
documentation for the cURL extension. I'd be willing to take a look at
making a script to do this, but I'd like comments, and other ideas
before I go ahead...

-Sterling

-- 
Sterling Hughes <sterling_at_bumblebury.com>
Did I help you? Consider a gift: http://wishlist.edwardbear.org/
-------------------------------------------------------
This sf.net emial is sponsored by: Influence the future 
of  Java(TM) technology. Join the Java Community 
Process(SM) (JCP(SM)) program now. 
http://ad.doubleclick.net/clk;4699841;7576298;k?http://www.sun.com/javavote