Re: [xml] (no subject)

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

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?


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

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


      \|/            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
===-=-=--=---=---------------------------------- - - -  -    -

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]