Re: [xml] Bug or User Error

[John Fleck <jfleck inkstain net>]

On Fri, 2004-01-30 at 01:28, Christopher J. Grayce wrote:
> With all due respect, Daniel, I kind of agree with some of this.  I've
> been using libxml2 for quite a while, and I've done my best to study
> the documentation, the tutorials, the mailing list archive, and I've
> pored over the source code myself, walked through it with the debugger
> step by step, et cetera, and I *still* get snagged by features or
> "features" which, no doubt, are clear to you when you built them,
> but which catch me by surprise.  
>
> I'm not a fool, either.  I've been writing large production scientific
> code for 18 years, all on Multics/Unix/Linux systems and generally with
> open software and GNU tools.  
>
> Unfortunately, the documentation for libxml2 is just not especially
> well-organized and decidedly incomplete.  I'm not complaining about
> that -- you've done great work on the library itself, it *is* an
> open-source project, and anyone who doesn't like it is free to do a
> better job.

The important thing to do, then, is when you find a place where the code
snags you, where the documentation is decidedly incomplete, work out how
it does work, write it down, and contribute it as documentation.

Daniel makes contributing documentation quite simple. The API docs are
generated from comments in the code - the format is obvious. This makes
contributing patches easy. Daniel also has tried to encourage people to
contribute example code, but with very little actual contribution
flowing in.

The entire documentation system is in CVS, so anyone can easily submit a
patch.

I agree that the documentation could be significantly better, which is
why I have spent a great deal of time on the documentation. This is
perhaps not the best approach, as I am a not a programmer, just a writer
who found Daniel's library useful, saw that he needed help, and tried to
contribute.

C'mon, guys and gals. This is free software. This isn't something Daniel
does for us, it's something we do together for mutual benefit. Let's
give Daniel a little more help here.

Cheers,
John