On 21 Oct 2002, Sterling Hughes wrote:

> 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).

Yeps. And most other bindings have this same problem too.

> 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).

I wouldn't have a problem with such a format, but I'd have a few conditions
before I'd say yes to this approach:

1. It must be able to generate nice man pages, in a similar style as they
   look today. That way, we can generate the HTML versions just like today
   (and also the PDF versions that upcoming releases are planned to include).

2. The tools needed to convert this XML format into man pages (and other
   formats) need to be easy enough to (install and) run. This is where
   Docbook tools fail miserably (I've not yet been able to install enough of
   it to make it run fine on my Solaris host).

3. We need a tool that generates this format from the existing man pages, so
   that the initial step over to this format doesn't create too much manual
   labour.

> 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 think every user of a curl binding will agree to that.

-- 
 Daniel Stenberg -- curl, cURL, Curl, CURL. Groks URLs.
-------------------------------------------------------
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://ads.sourceforge.net/cgi-bin/redirect.pl?sunm0002en