Re: [xml] (no subject)

[Stefan Kost <kost imn htwk-leipzig de>]

Hi Daniel,

Most of us are fammiliar with the situation, as we develop software ourselfs.
Here comes my personal opinion and an offer :

When do I ask on the list about a problem. I definitely browse the API docs, 
check examples (greping thru sources), try to understand the specs and since we 
can do this now search on xmlsoft.org.
1.) Currently I miss a alpahbetical index in the local api docs. It is sometimes 
hard to find a function there.
2.) Refenrences. Can pages such as
  doc/html/libxml-notes.html
  doc/html/libxml-xpath.html
  have a short introductionary sentence what this is about along with a few
  links to the specs?
3.) The documentation is not very xref'ed and sometimes the description is just 
the function name converted to a minimal english sentence. Example :
--- current doc ---
xmlXPathNewContext ()

xmlXPathContextPtr xmlXPathNewContext       (xmlDocPtr doc);

Create a new xmlXPathContext

doc : the XML document
Returns : the xmlXPathContext just allocated. The caller will need to free it.
---
--- better doc ---
xmlXPathNewContext ()

xmlXPathContextPtr xmlXPathNewContext       (xmlDocPtr doc);

Prepare a new xmlXPathContext which can be used to execute xpath queries (e.g. 
via xmlXPathCompiledEval()). You need to register at least one name space with
xmlXPathRegisterNs()

doc : the XML document you perform queries against
Returns : the xmlXPathContext just allocated. The caller will need to free it
          using xmlXPathFreeContext ()
----

Now my offer/suggestion. What about, if we send patches, which are purely about 
enhancing the docs? If you invite us to do so, just one question: Do we need 
special markup to say that something should link to the documentation of e.g. a 
function or does the gtk-doc stuff automatically creates links to now targets?

Ciao
  Stefan

> On Wed, Oct 30, 2002 at 02:42:20PM +0100, Peter Jacobi wrote:
>
> >Hi Daniel,
> >
> >
> >>  I am doomed to answer on my free time to users who just don't want
> >>  to spend the time to read the documentation ???
> >
> >Perhaps the "welcome" message to the mailing list should contain the UTF-8
> >answer?
>
>
>   Honnestly, I don't know how to get people to behave in a less
> egoist fashion. Everybody wants its question answered now and
> without having the hassles of looking for the answers or reading
> what's available. I'm afraid of having valuable contributors be
> burnt out by this, I'm afraid of getting burnt out myself. Should
> I hide the address of the list (or make it available only at the
> end of a search query answer) ?
>   I honnestly don't know what to do. The two mail received today
> were both complete FAQ, covered in the recent weeks, the XPath
> question is actually simply due to the fact that people don't even
> try to understand the XPath specification because libxml2 behaviour
> directly derives from the spec normative text.
>
>   That's simply depressing :-(
>
> Daniel


--
      \|/            Stefan Kost
     <@ @>           private            business
+-oOO-(_)-OOo------------------------------------------------------ - - -  -   -
|       __  Address  Simildenstr. 5     HTWK Leipzig, Fb IMN, Postfach 300066
|      ///           04277 Leipzig      04277 Leipzig
| __  ///            Germany            Germany
| \\\///    Phone    +49341 2253538     +49341 30766101
|  \__/     EMail    st_kost gmx net    kost imn htwk-leipzig de
|           WWW      www.sonicpulse.de  www.imn.htwk-leipzig.de/~kost/about.html
===-=-=--=---=---------------------------------- - - -  -    -