Mailing-List: contact apreq-dev-help@httpd.apache.org; run by ezmlm
Precedence: bulk
Mail-Followup-To: apreq-dev@httpd.apache.org
To: apreq-dev@httpd.apache.org
From: Joe Schaefer <joe+gmane@sunstarsys.com>
Subject: Re: [PROPOSAL] docs, tables,
 tests (was: Re: separate pod files for Apache:: packages)
Date: 19 Jul 2004 19:39:08 -0400
Lines: 67
Message-ID: <87pt6r8t43.fsf@gemini.sunstarsys.com>
References: <87wu15cicz.fsf@gemini.sunstarsys.com>
 <Pine.LNX.4.56.0407161350410.29308@theoryx5.uwinnipeg.ca>
 <87smbrafn5.fsf@gemini.sunstarsys.com>
 <87zn5w7xws.fsf_-_@gemini.sunstarsys.com>
 <Pine.LNX.4.56.0407191749170.24240@theoryx5.uwinnipeg.ca>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Mail-Copies-To: never
User-Agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.2
Sender: news <news@sea.gmane.org>

Randy Kobes <randy@theoryx5.uwinnipeg.ca> writes:

[...]

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

+1.  Basically I'm toying with adding something like this to 
the bottom of glue/perl/Makefile.PL:

==================================================
sub copy_docs {
    my @lines;
    my $dfs = '$(DIRFILESEP)';

    foreach my $file (@_) {
        my @dirs;
        $file =~ /(\w+\.pod)$/ or next;
        if ($1 eq "Error.pod" or $1 eq "Table.pod") {
            push @dirs, catfile("Apache", $_) for qw/Request Cookie Upload/;
        }
        else {
            push @dirs, catfile "Apache";
        }
        push @lines, map <<EOT, @dirs;
subdirs :: \$(INST_LIBDIR)$dfs$_$dfs$1
\$(INST_LIBDIR)$dfs$_$dfs$1: $file
	\$(MKPATH) \$(INST_LIBDIR)$dfs$_
	\$(CP) $file \$(INST_LIBDIR)$dfs$_$dfs$1

EOT
    }
    return join "", @lines;
}

sub MY::postamble {
    return copy_docs <docs/*.pod>;
}
==================================================

It's messy, but that will just copy whatever pods we put in 
the ./docs subdir into their proper location in ./blib,
duplicating Table.pod and Error.pod as necessary.

> 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
> Apache-Test.


Right- I guess we could also use the ./docs subdir to hold the 
.t files Test::Inline generates, and add a "test" target to the 
MY::postamble sub above to include them in a `make test` run.

If this is ok, let's name new directory "api", since it holds
our api docs *and* their tests.

-- 
Joe Schaefer