You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@apr.apache.org by Tom Bradford <br...@gmail.com> on 2006/04/24 21:12:58 UTC
Documentation Project
Greetings, I have a few questions after having been subscribed to
this list for a few days.
1) I see that there's not a lot of activity on this list. What is
the current active status of the project?
2) I notice that there is a database interface, but even though
SQLite is supported, the exposed APIs resemble DBM-style interfaces.
Is there a plan to create a super-simple rowset style interface for
backends that support it?
3) The documentation is scarce or non-existent. Everything I've
learned thus far has been from Inoue Seiichiro's tutorial. Are there
any official documentation project's active or planned?
I'm currently using APR for a commercial router project, and am
learning as I go. I'm rather impressed with the elegance and clean
use of incomplete types for a more, dare I say it, 'object oriented'
approach to C APIs.
If there is no documentation project currently active, I can attempt
to document what I'm learning as I go, and donate it back to the
project.
Thanks,
Tom
--
Tom Bradford - http://www.tbradford.org/
Re: Documentation Project
Posted by Nick Kew <ni...@webthing.com>.
On Monday 24 April 2006 20:12, Tom Bradford wrote:
> Greetings, I have a few questions after having been subscribed to
> this list for a few days.
>
> 1) I see that there's not a lot of activity on this list. What is
> the current active status of the project?
Activity is variable. Check the archives.
> 2) I notice that there is a database interface, but even though
> SQLite is supported, the exposed APIs resemble DBM-style interfaces.
> Is there a plan to create a super-simple rowset style interface for
> backends that support it?
Not sure what you mean there?
> 3) The documentation is scarce or non-existent. Everything I've
> learned thus far has been from Inoue Seiichiro's tutorial. Are there
> any official documentation project's active or planned?
That tutorial is probably the only one of its kind. There are some
more at www.apachetutor.org, but they are oriented to the webserver
(though the pools one at least is just as relevant to the APR in its
own right). My book (tba) has a complete chapter on the APR.
Coincidentally, I've just written an article about the APR. It's an
overview rather than a tutorial or documentation, but may be of
interest.
> If there is no documentation project currently active, I can attempt
> to document what I'm learning as I go, and donate it back to the
> project.
Great! There's ample scope for new documentation that duplicates
neither the API docs nor the existing tutorials.
Now, why don't we have any mention of it on the APR pages?
At the very least, a link to Inoue Seiichiro would be in order.
--
Nick Kew
Re: Documentation Project
Posted by INOUE Seiichiro <in...@ariel-networks.com>.
> > >> 3) The documentation is scarce or non-existent. Everything I've
> > >> learned thus far has been from Inoue Seiichiro's tutorial. Are there
> > >> any official documentation project's active or planned?
[snip]
Hi all,
As nobody have written URLs, I paste URLs.
It seems I haven't updated for a while, but I still have a will to keep updating.
And I wish I could describe whole areas of APR (e.g. It lacks some areas, such as buckets).
+ http://dev.ariel-networks.com/apr/apr-tutorial/html/apr-tutorial.html (HTML)
+ http://dev.ariel-networks.com/apr/apr-tutorial/sample/ (sample code)
+ http://dev.ariel-networks.com/apr/apr-tutorial-20050829.tar.gz (archive)
+ http://dev.ariel-networks.com/apr/ (everything)
Anyway, if an official APR documentation project starts, I'm happy to contribute to it.
I say, you can reuse my tutorial as the starting point,
or I could have a time to help adding new chapters.
Thanks.
- INOUE Seiichiro <in...@ariel-networks.com>
Re: Documentation Project
Posted by Bojan Smojver <bo...@rexursive.com>.
On Mon, 2006-04-24 at 16:13 -0400, Tom Bradford wrote:
> Sorry, but Doxygen and a slideshow with little to no actual
> information (both of which I've already seen) do not a suite of
> documentation make.Doxygen is as valuable in the grand scheme of
> things as is Javadoc, and that's not much because neither are able to
> paint an overall picture of contextual or global cohesion.
Actually, pages like this:
http://apr.apache.org/docs/apr/
should contain the glue you're looking for. Probably the most
straightforward thing to do is to write up plain text files and include
them verbatim on this page during doc generation, like this:
http://httpd.apache.org/apreq/docs/libapreq2/
but a lot more detailed, of course. Doxygen can be bent to deliver not
just API documentation, but also any other document we want to put in
it. The benefit would be obvious - potential, novice and expert users
can use one and only documentation system for APR/APU, from tutorials,
philosophy and organisation to a full API reference.
But I do get your point. I found myself that many times I wasn't quite
clear on how things were supposed to hang together in APR/APU and the
only way to really find out was to look at the source.
--
Bojan
Re: Documentation Project
Posted by Tom Bradford <br...@gmail.com>.
On Apr 24, 2006, at 4:54 PM, Davi Arnaut wrote:
> IMHO, Inoue Seiichiro's tutorial goes out of scope (eg, describing
> what
> a thread is, et cetera). What kind of documentation you're most
> interested
> in ? Guides, how-to, tutorial..
Describing what a thread is, how a socket works, etc, are all part of
a greater whole wherein you give a reader a proper context in which
to work and learn. Presenting a threading API to someone who doesn't
know the fundamentals of threads provides absolutely no value. On
the other hand, providing a few extra paragraphs to serve as a
foundation for the simplified threading APIs that one is about to
learn goes a long way toward 'selling' your project to a much broader
audience.
For example... reading the doxygen docs, I saw the words 'bucket
brigade', and my first inclination is to ask 'what the hell is a
bucket brigade?'. I knew what a bucket it is, but my understanding
of a bucket was from a very broad perspective, so giving a foundation
for these things rather than the pure technical mumbo-jumbo will
afford you a much larger audience by reducing the learning curve,
which in my experience (partly with Apache Xindice, but also with
other projects) is a major stopping point for projects such as these.
Maximum return for minimal investment.
--
Tom Bradford - http://www.tbradford.org/
Re: Documentation Project
Posted by Davi Arnaut <da...@haxent.com.br>.
On Mon, 24 Apr 2006 16:13:38 -0400
Tom Bradford <br...@gmail.com> wrote:
> On Apr 24, 2006, at 3:54 PM, Davi Arnaut wrote:
> >> 2) I notice that there is a database interface, but even though
> >> SQLite is supported, the exposed APIs resemble DBM-style interfaces.
> >> Is there a plan to create a super-simple rowset style interface for
> >> backends that support it?
> >
> > I don't know, what does Google say ?
>
> Well, I was hoping that an actual representative of the project could
> speak to what is planned for the project proper, rather than try to
> infer what may or may not be happening to the project at some point
> in the future.
>
> >> 3) The documentation is scarce or non-existent. Everything I've
> >> learned thus far has been from Inoue Seiichiro's tutorial. Are there
> >> any official documentation project's active or planned?
> >
> > http://apr.apache.org/docs/apr/modules.html
> > http://apr.apache.org/apr2_0intro/apr2_0intro.htm
>
> Sorry, but Doxygen and a slideshow with little to no actual
> information (both of which I've already seen) do not a suite of
> documentation make. Doxygen is as valuable in the grand scheme of
> things as is Javadoc, and that's not much because neither are able to
> paint an overall picture of contextual or global cohesion. As I was
> saying, Inoue Seiichiro's tutorial is by the far the best
> documentation I've found for APR, and the fact that nothing made
> available by the APR project itself even comes close is somewhat
> disconcerting.
IMHO, Inoue Seiichiro's tutorial goes out of scope (eg, describing what
a thread is, et cetera). What kind of documentation you're most interested
in ? Guides, how-to, tutorial..
> Let me reiterate. I' very impressed with the API, and I see broad
> developmental usage for APR outside of the Apache project proper, but
> the major hurdle at this point is the very real lack of
> documentation. Not need to get defensive about it, especially since
> I'm offering my assistance.
>
Fair enough. Welcome aboard.
--
Davi Arnaut
Re: Documentation Project
Posted by Tom Bradford <br...@gmail.com>.
On Apr 24, 2006, at 3:54 PM, Davi Arnaut wrote:
>> 2) I notice that there is a database interface, but even though
>> SQLite is supported, the exposed APIs resemble DBM-style interfaces.
>> Is there a plan to create a super-simple rowset style interface for
>> backends that support it?
>
> I don't know, what does Google say ?
Well, I was hoping that an actual representative of the project could
speak to what is planned for the project proper, rather than try to
infer what may or may not be happening to the project at some point
in the future.
>> 3) The documentation is scarce or non-existent. Everything I've
>> learned thus far has been from Inoue Seiichiro's tutorial. Are there
>> any official documentation project's active or planned?
>
> http://apr.apache.org/docs/apr/modules.html
> http://apr.apache.org/apr2_0intro/apr2_0intro.htm
Sorry, but Doxygen and a slideshow with little to no actual
information (both of which I've already seen) do not a suite of
documentation make. Doxygen is as valuable in the grand scheme of
things as is Javadoc, and that's not much because neither are able to
paint an overall picture of contextual or global cohesion. As I was
saying, Inoue Seiichiro's tutorial is by the far the best
documentation I've found for APR, and the fact that nothing made
available by the APR project itself even comes close is somewhat
disconcerting.
Let me reiterate. I'm very impressed with the API, and I see broad
developmental usage for APR outside of the Apache project proper, but
the major hurdle at this point is the very real lack of
documentation. Not need to get defensive about it, especially since
I'm offering my assistance.
--
Tom Bradford - http://www.tbradford.org/
Re: Documentation Project
Posted by Davi Arnaut <da...@haxent.com.br>.
On Mon, 24 Apr 2006 15:12:58 -0400
Tom Bradford <br...@gmail.com> wrote:
> Greetings, I have a few questions after having been subscribed to
> this list for a few days.
>
> 1) I see that there's not a lot of activity on this list. What is
> the current active status of the project?
Hint: http://www.apache.org/dist/apr/ [CHANGES*]
> 2) I notice that there is a database interface, but even though
> SQLite is supported, the exposed APIs resemble DBM-style interfaces.
> Is there a plan to create a super-simple rowset style interface for
> backends that support it?
I don't know, what does Google say ?
> 3) The documentation is scarce or non-existent. Everything I've
> learned thus far has been from Inoue Seiichiro's tutorial. Are there
> any official documentation project's active or planned?
http://apr.apache.org/docs/apr/modules.html
http://apr.apache.org/apr2_0intro/apr2_0intro.htm
> I'm currently using APR for a commercial router project, and am
> learning as I go. I'm rather impressed with the elegance and clean
> use of incomplete types for a more, dare I say it, 'object oriented'
> approach to C APIs.
>
> If there is no documentation project currently active, I can attempt
> to document what I'm learning as I go, and donate it back to the
> project.
>
--
Davi Arnaut
Re: Documentation Project
Posted by Tom Bradford <br...@gmail.com>.
On Apr 24, 2006, at 4:27 PM, William A. Rowe, Jr. wrote:
> Documentation discussions do belong on dev@apr, since the docs need
> the
> eyeballs of the authors who designed the interfaces. Thank you for
> the
> offer, as all contributions, code, docs, beer are welcome.
Very good. I'll work on areas as I'm utilizing them in my own
projects, so things may tend to be sporadic initially, but I'll try
to ties things together as I completion sections. Effectively, what
I'd like to see result from my efforts is a piece of work similar to
'APR in a Nutshell', where major areas of the system are discussed
from an introductory standpoint, and they are backed up by fleshing
out the doxygen code more thoroughly.
--
Tom Bradford - http://www.tbradford.org/
Re: Documentation Project
Posted by "William A. Rowe, Jr." <wr...@rowe-clan.net>.
Tom Bradford wrote:
> Greetings, I have a few questions after having been subscribed to this
> list for a few days.
>
> 1) I see that there's not a lot of activity on this list. What is the
> current active status of the project?
apr tends to grow in fits and spurts. So you may see the list quite quiet
for a time (-especially- when alot of the main contributors are hiding over
at httpd, svn or other projects trying to get to some end goal). On the
other hand, prepare for 20-30 mail deluge some afternoon, you've been warned :)
> 3) The documentation is scarce or non-existent. Everything I've
> learned thus far has been from Inoue Seiichiro's tutorial. Are there
> any official documentation project's active or planned?
The documentation can -certainly- use improvement, mostly from the perspective
of 'new to apr, how do I get started?' along with some of the more cryptic bits
of collective knowledge.
> I'm currently using APR for a commercial router project, and am
> learning as I go. I'm rather impressed with the elegance and clean use
> of incomplete types for a more, dare I say it, 'object oriented'
> approach to C APIs.
Glad to hear it looks suited to your project!
> If there is no documentation project currently active, I can attempt to
> document what I'm learning as I go, and donate it back to the project.
Documentation discussions do belong on dev@apr, since the docs need the
eyeballs of the authors who designed the interfaces. Thank you for the
offer, as all contributions, code, docs, beer are welcome.
Bill
Re: Documentation Project
Posted by Tom Bradford <br...@gmail.com>.
On Apr 24, 2006, at 5:17 PM, Bojan Smojver wrote:
> On Mon, 2006-04-24 at 17:07 -0400, Tom Bradford wrote:
>
>> By DBM-style, I mean you're effectively talking about the storage of
>> key/value pairs where the atom representation of a value is
>> effectively a void pointer, rather than tuples, which is how SQLite
>> and other RDBMS' inherently operate.
>
> I think you're probably reading DBM docs and thinking of DBD -
> something
> that was recently fixed (i.e. DBD documentation was not generated for
> some versions of APU). The actual DBD support for SQLite2/3 is SQL
> orientated (i.e. you do things like select/query and then fetch
> rows/values). This should be fixed in the future Doxygen docs.
Yes, this looks like the case from the generated docs that I have. I
tend to look at the docs first as the clearing house of all knowledge
for a package, as having to investigate others' source can be a
potentially harrowing experience.
--
Tom Bradford - http://www.tbradford.org/
Re: Documentation Project
Posted by Bojan Smojver <bo...@rexursive.com>.
On Mon, 2006-04-24 at 17:07 -0400, Tom Bradford wrote:
> By DBM-style, I mean you're effectively talking about the storage of
> key/value pairs where the atom representation of a value is
> effectively a void pointer, rather than tuples, which is how SQLite
> and other RDBMS' inherently operate.
I think you're probably reading DBM docs and thinking of DBD - something
that was recently fixed (i.e. DBD documentation was not generated for
some versions of APU). The actual DBD support for SQLite2/3 is SQL
orientated (i.e. you do things like select/query and then fetch
rows/values). This should be fixed in the future Doxygen docs.
However, we should mention that DBD uses APU style SQL (yes, there is
such a thing :-), where in prepared statements %s, %d and similar are
used in place of $1, $2 (PGSQL) or ? (MySQL) parameters to make them
uniform across database types. In fact I should probably document
this :-(
--
Bojan
Re: Documentation Project
Posted by Garrett Rooney <ro...@electricjellyfish.net>.
On 4/24/06, Tom Bradford <br...@gmail.com> wrote:
> On Apr 24, 2006, at 4:47 PM, Garrett Rooney wrote:
> > Umm, what do you mean by "DBM-style"? The dbd stuff doesn't seem very
> > similar to DBM apis to me. If you have alternate APIs you'd like to
> > see feel free to propose them on this list.
>
> By DBM-style, I mean you're effectively talking about the storage of
> key/value pairs where the atom representation of a value is
> effectively a void pointer, rather than tuples, which is how SQLite
> and other RDBMS' inherently operate.
Umm, have you looked at apr_dbd.h? It doesn't return void pointers to
you at all, it returns result and row structures, which you can
retrieve data out of via various functions. apr_dbm.h is very DBM
like, but that's a totally different API and has nothing to do with
sqlite (or any sql database for that matter).
-garrett
Re: Documentation Project
Posted by Tom Bradford <br...@gmail.com>.
On Apr 24, 2006, at 4:47 PM, Garrett Rooney wrote:
> Umm, what do you mean by "DBM-style"? The dbd stuff doesn't seem very
> similar to DBM apis to me. If you have alternate APIs you'd like to
> see feel free to propose them on this list.
By DBM-style, I mean you're effectively talking about the storage of
key/value pairs where the atom representation of a value is
effectively a void pointer, rather than tuples, which is how SQLite
and other RDBMS' inherently operate.
I have no ideas off the top of my head, but I will be using both
SQLite and APR in this project, so I may come up with something as it
moves forward.
--
Tom Bradford - http://www.tbradford.org/
Re: Documentation Project
Posted by Garrett Rooney <ro...@electricjellyfish.net>.
On 4/24/06, Tom Bradford <br...@gmail.com> wrote:
> Greetings, I have a few questions after having been subscribed to
> this list for a few days.
>
> 1) I see that there's not a lot of activity on this list. What is
> the current active status of the project?
As others have said, it varies.
> 2) I notice that there is a database interface, but even though
> SQLite is supported, the exposed APIs resemble DBM-style interfaces.
> Is there a plan to create a super-simple rowset style interface for
> backends that support it?
Umm, what do you mean by "DBM-style"? The dbd stuff doesn't seem very
similar to DBM apis to me. If you have alternate APIs you'd like to
see feel free to propose them on this list.
> 3) The documentation is scarce or non-existent. Everything I've
> learned thus far has been from Inoue Seiichiro's tutorial. Are there
> any official documentation project's active or planned?
>
> I'm currently using APR for a commercial router project, and am
> learning as I go. I'm rather impressed with the elegance and clean
> use of incomplete types for a more, dare I say it, 'object oriented'
> approach to C APIs.
>
> If there is no documentation project currently active, I can attempt
> to document what I'm learning as I go, and donate it back to the
> project.
Personally, I'd love to see more complete documentation, either via
patches to the existing doxygen or separate docs outside the source
code.
-garrett