Excellent comments Daniel!

May I suggest that we take this documentation effort
a step further, and use the XML files not only for generating
the documentation, but for generating the data structures as well?

We can use the XML schemas as the single source for the data structures.
The translation can then provide the multiple views required, whether
it be generated source code, generated man pages, or generated HTML.

This way, if the data structure changes, the documentation
is automatically updated as well.

If the structures are not generated from the XML they
will undoubtedly get out of date with the XML version.

So if we generate the structures from XML, each structure can
have a header and source file generated from it, and then we can just
include the header file into the main headers. These comments are
from a 'C' language point of view. However, it would not be
too difficult to create a separate XSL to support any other
language.

Perhaps we can collect all of these requirements, including Daniel's
comments in some sort of document (an XML document!?). We could use
this requirements document, written in XML, as a testbed for generating
documentation from it. Along with creating this requirements document,
we could create an XML file for one of the curl structures and test
generating the code and documentation from it.

Some things to consider:
- transformation engine; how about xalan-xerces? (http://xml.apache.org/)
- format of the requirements document
- format of the structures (already started by Sterling)

We can store the new files in CVS such as...
xml/schema
xml/stylesheets
xml/src (store the transformation engine here)

We can then use a temporary target directory for the generated
code and documentation until it's ready to be incorporated into libcurl.

Chris

Daniel Stenberg wrote:
> 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.
>

-------------------------------------------------------
This sf.net email 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
Received on 2002-10-23