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

["Elvis Stansvik" <elvstone gmail com>]

2008/11/8 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:

I have now taken the liberty and set up a MediaWiki installation and
started adding some content. It's available at:

http://libxml2wiki.dose.se

I'm blocking search engine robots in robots.txt at the moment.

As you can see I've styled the wiki to look similar to xmlsoft.org. If
you want the regular MonoBook skin, just change it in the preferences.

I have started to reconsider the structure of the main content (yet to
be written). Maybe it should be more task oriented and not sectioned
by the different APIs?

I also added created a tag extension so you can use e.g.
<api>xmlNode</api> and it will turn into a link to the libxml2 API
documentation. This extension uses information from the
libxml2-api.xml generated from libxml2 2.7.2 at the moment. I'm also
planning on patching the syntax highlighting extension I'm using to
automatically identify libxml2 symbols within <source /> tags and turn
them into API documentation links.

If anyone feel like helping out, just register and edit away! A simple
thing is to add installation instructions for your platform, as I've
only added it for the platforms I'm familar with.

Hope to get some response on this!

Daniel, what is xmlsoft.org running on? Would you consider again
making a wiki.xmlsoft.org for this? I'd be willing to maintain the
MediaWiki installation and handle security updates to it, as well as
combat any SPAM problems that might arise. The server I'm running this
on now is on a dynamic IP DSL line in Sweden, which is not really
optimal.

Regards,
Elvis

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