httpd-apreq-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Randy Kobes <>
Subject Re: [PROPOSAL] docs, tables, tests (was: Re: separate pod files for Apache:: packages)
Date Mon, 19 Jul 2004 22:58:34 GMT
On Mon, 19 Jul 2004, Joe Schaefer wrote:

> Joe Schaefer <> writes:
> [...]
> > What I'm sort-of looking for is to add one podfile for
> > ::Table and one for ::Error, bringing the total pods to 5
> > (the other packages are specialized enough that they probably
> > don't need separate docs).  But we should somehow add links/copies
> > in the installated docs so that eg
> >
> >   % man Apache::Request::Table
> >   % man Apache::Cookie::Table
> >   % man Apache::Upload::Table
> >
> > all point to the same documentation.
> Keeping that in mind...
> with the perl APIs complete, actually I think it's time
> to consider refactoring all the *::Table code into separate
> modules.  The table APIs aren't 100% necessary for our perl
> users, and separating them out would reduce the memory footprint
> of Apache::Request, Apache::Upload, and Apache::Cookie.
> So what I propose we do is
>   1) add to glue/perl/docs:
>      Request.pod   (replaces xsbuilder/Apache/Request/Request_pod)
>      Cookie.pod    (   "           "      "  /Cookie/Cookie_pod)
>      Upload.pod    (   "           "      "  /Upload/Upload_pod)
>      Table.pod     (new)
>      Error.pod     (new)
>      We should use Test::Inline (or something similar) to extract
>      basic API tests from these pods.  I haven't given this any
>      more thought, but hopefully someone can flesh out the details
>      a bit to make sure this is workable.

Although you later found not much advantage to separating
out the Apache::*::Table packages, it still seems to make
sense (?) to separate out the Table.pod (as well as
Error.pod), as they're similar.

I could take a look at using Test::Inline to make some basic
API tests (probably this weekend - I'm away for this week).
>From what I understand, one inserts the basic code for a
test within the pod, and then use a supplied script to
extract the tests into a .t test file that is run as usual
(developers do the extraction, so users don't have to
install Test::Inline). So with this it'd probably be a good
idea to have two separate test directories - one for these
tests (requiring Test::More), and the present one using

>   2) Factor the Apache::*::Table packages into separate modules.
>      If we want to be nice, we could C<<require>> those modules
>      whenever Apache::Request or Apache::Cookie generates a table,
>      that way users wouldn't notice the table refactoring (yes
>      it's a minor performace hit, but IMO reasonable since perl's
>      TIEHASH API is really slow anyways).
>   3) Have the build system transplant the /docs pods into the blib/
>      directory during `make`, replicating Table.pod and Error.pod
>      as needed.

So would one have separate Apache::*::(Table|Error)
packages, being essentially clones of each other
(perhaps with appropriate name substitutions)?

best regards,

View raw message