httpd-apreq-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joe Schaefer <>
Subject Re: separate pod files for Apache:: packages
Date Fri, 16 Jul 2004 19:58:06 GMT
Randy Kobes <> writes:


> > Currently we have 3 podfiles, one for each module.
> > There are 11 packages we need to document (albeit
> > all the ::Table docs would be more-or-less identical,
> > as would the ::Error docs).
> >
> > Any thoughts on what we should do about this?  FWIW
> > I would love to see us adopt a system where the
> > doc files included their own API tests, and our
> > Apache::Test tests verified those, but I don't
> > have the skills necessary to pull that off myself.
> >
> > Any takers?
> I suppose it's worth it, from a user's perspective,
> to include the almost-duplicated ::Table and ::Error
> docs. Were you thinking of splitting it up into 11
> separate files, one for each package?

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.

> As for the doc files including their own tests, would this
> be something like what's done in the Test-Inline package,
> which extracts tests from the pod section of a module? 

I guess I was asking for something more like the converse:
a set of doc files from which tests can be extracted.  I
suppose it's the same as what Test-Inline does, but without 
the actual code (all pod).  I don't think it makes sense for
us to stuff our docs in our generated .pm files, because 
there's only three of those (which is where we are now).

It's really wide-open as to what would work best for us,
but whatever we do, the purpose should be to ensure that
our docs are as accurate as possible.  I thought that keeping 
the docs together with the tests would help, but I don't
want this to become more trouble that it's worth.

Joe Schaefer

View raw message