Re: [xml] [Proposal] How about write a book for LibXML2?

["Elvis Stansvik" <elvstone gmail com>]

2008/11/7 Elvis Stansvik <elvstone gmail com>:
> 2008/11/7 Daniel Veillard <veillard redhat com>:
> > On Thu, Oct 30, 2008 at 09:25:55AM +0800, Yang Songxiang-a22301 wrote:
> > > Hi, all,
> > >
> > > I used the libxml2 package recently, found it's a perfect XML parser.
> > > The example codes/document are good for a newcomer to use the LibXML2,
> > > but they lack of enough detail information. I had to dig into the
> > > sources code if I want more furthermore details. I think we can write a
> > > bible book, give a complete introduction for LibXML2 package, not only
> > > it's calling convention, but also including it's design framework.
> >
> >  I had been approached a few years ago about writing a libxml2 book,
> > but it's a lot of work, I didn't had the time (and not much more now)
> > and it was made relatively clear that financially that may not be very
> > interesting.
> >  I don't have much time, so when i have some for libxml2 I prefer to
> > focuse on bugs or improvements that other contributors are less likely
> > to provide.
> >
> > > My draft idea:
> > > 1) Generate a DocBook framework,
> > > 2) Anyone can select a chapter that he/she interested.
> > > 3) Organize all chapters into a complete LibXML2 bible book.
> > >
> > >
> > > I think this would help a lot for many C/C++ programmers who're the
> > > first time using LibXML2, and would make LibXML2 more popular in C/C++
> > > domain. Maybe the book can be published by O.Reilly if it's good enough.
> > > :)
> > >
> > > What's your opinions?
> >
> >  Sounds better than a wiki in my opinion, I'm fine adding this to CVS
> > and integrating patches to the docs as they come.
>
> I think personally a wiki would be better, and then content could be
> taken from that and integrated into a more "official" DocBook in CVS.
> I heard you had tried setting up a wiki some years ago but had
> problems with SPAM, but surely that's a problem that can be solved?
> E.g. by only allowing e-mail confirmed registered users. Anything else
> that speaks against a wiki? It would be easier to contribute, and
> easier to make small fixes with less maintenance than sending patches,
> IMHO.

Just to throw something out there, I sketched out a preliminary layout
that could be used (and of course improved upon) as a skeleton for a
DocBook or Wiki:

The libxml2 Library

Introduction
  History
  What is libxml2?
  What libxml2 Is Not
  libxml2 Architecture

Getting started
  Installing libxml2
    Binaries
      Linux
        Ubuntu / Debian
        OpenSUSE
        Fedora
        Gentoo
      FreeBSD
      OpenBSD
      Windows
      MacOS X
    Building from source
      Download libxml2
        Stable Version
        Subversion
      Configure Options
      Building
        Linux / BSD
        Windows
        MacOS X
  Quick Start
    Hello World
    Building Your Program

The libxml2 APIs
  Choosing the Right API
  The Tree API
    Introduction
    Basic Example
    Complex Example
    Common Problems
  The Reader API
    Introduction
    Basic Example
    Complex Example
    Common Problems
  The SAX2 API
    Introduction
    Basic Example
    Complex Example
    Common Problems
  The HTML API
    Introduction
    Basic Example
    Complex Example
    Common Problems
  XPath API
    Introduction
    Basic Example
    Complex Example
    Common Problems
  XPointer API
    Introduction
    Basic Example
    Complex Example
    Common Problems
  XInclude API
    Introduction
    Basic Example
    Complex Example
    Common Problems
  Utility APIs
    String Handling
    HTTP / FTP
    XML and SGML Catalogs
    String Dictionaries
    Hash Tables
  Putting It All Together
    (Some more complex "task oriented" examples exercising
     the various APIs and using XML found in the wild)

Validation
  Introduction
  DTDs
  XML Schemas
  RelaxNG
  Schematron

Namespaces
  Introduction
  Basic Example
  Complex Example
  Common Problems

Error Handling
  Introduction
  Basic Example
  Complex Example
  Common Problems

Threads
  Introduction
  Thread Safety
  Basic Example
  Complex Example
  Common Problems

Language Bindings
  Perl
  PHP
  Python
  Ruby

Appendix
  A See Also
  B Acknowledgements

As you can see the sections for the various APIs are pretty sparse and
repetitive, with just an introduction to each API along with some
examples, the idea being that the current examples on xmlsoft.org can
be taken and improved upon, and as people (hopefully) contribute more
hands on and anecdotal information, those sections could be fleshed
out.

Any comments? I've probably left something out.

Are you dead against giving a wiki a try again Daniel? Even a
"registration required" one? If so, I could arrange this skeleton into
a DocBook XML instead and send it over.

Regards,
Elvis

> > >  Best Regards
> > > -Scord
> > >
> > > Motorola Software Center
> > > [x] Public
> > > [ ] Internal
> > > [ ] Motorola Confidential Restricted
> >
> >  Heh, finally a smart non threatening way to label expected recipient
> > for mails issued by a corporation. Nice !
>
> Yea I jumped at that too! Finally! :)
>
> Regards,
> Elvis
>
> > Daniel
> >
> > --
> > Daniel Veillard      | libxml Gnome XML XSLT toolkit  http://xmlsoft.org/
> > daniel veillard com  | Rpmfind RPM search engine http://rpmfind.net/
> > http://veillard.com/ | virtualization library  http://libvirt.org/
> > _______________________________________________
> > xml mailing list, project page  http://xmlsoft.org/
> > xml gnome org
> > http://mail.gnome.org/mailman/listinfo/xml