On Thu, Mar 08, 2001 at 05:12:47PM -0600, Appleton Brad-BRADAPP1 wrote:
> > Simlarly, I'd really like tools like Pod::Select to just take and
> > return trees rather than insisting on reading files (which the man
> > pages imply). Pod::Tree has worked well for this, but there is no
> > Pod::Tree::Select yet (though I'll probably wind up writing it soon).
>
> Pod::Select and Pod::Parser are file-based by default. They can be used for
> more than that though. You just need to give it an object that implements
> the getline method. Also, Pod::Parser can be used to return ParseTrees if
> that is what you want. The default & examples all use line-based input
> and output because that was the most common scenario. But if you want it
> to return a ParseTree it can.
But can Pod::Select then accept a ParseTree? That's the real goal to
me, since it would allow you to do this kind of stuff:
my $pod = "=head1 NAME\n\nDefobrucate\n\n";
my $podtree = new Pod::ParseTree( \$pod );
my $outtree = $podtree->select( "NAME" );
$outtree->add( Pod::Node->head1( "Notice" ),
Pod::Node->paragraph( Pod->parse( "Copyright E<copy> 2001" ) ) );
my $outfile = new File::IO( "mystuff.html" );
my $html= new Pod::HTML( $outfile, $outtree );
$html->translate;
---
I'm just coming up with syntax here off the cuff (I'm not sure where
Pod->parse really belongs in this case), but that's kind of the goal.
I want to write pod on the fly, insert things into it, insert it into
other things (with Text::Template for instance), and then translate it
when I'm all done. The current Pod:: tools don't all seem to accept
and return ParseTrees or pod strings, but maybe I'm overlooking it.
I have some tools that do this kind of stuff based on Pod::Tree now.
It doesn't let me add nodes as nicely as I'd like (there is no
Pod::Tree->add(Pod::Tree::Node)), but other than that it does seem to
work very well with very little effort. I'd like to bring that kind of
functionality "into the fold" as it were with the core pod tools.
Here's an example of some real code I'm talking about. I'm trying to
build an index for a set of pod documents. While walking through the
configuration file, which tells me where the pod is, I inserted into
@index strings for headings (defined in the configuration file) and
listrefs (title=>path) for actual pod documents. I then take this and
stick it into a template and output it:
my $index_entries = "=over 4\n\n";
foreach my $entry ( @index )
{
if( ref( $entry ) eq 'ARRAY' )
{
$index_entries .= "=item *\n\nL<$entry->[0]|$entry->[1]>\n\n";
}
else
{
$index_entries .= $entry;
}
}
$index_entries .= "=back\n\n";
my $index_pod = fill_in_file( $Config::index_tmpl,
HASH => { title => $Config::title,
index => $index_entries
} ) or die;
my $index_html = new Pod::Tree::HTML( \$index_pod,
"${Config::html_dir}/index.html",
HTML_OPTS,
toc => 0 ) or die;
$index_html->translate;
The config file looks something like this:
$pod = [ { SECTION => 'High level documentation' },
'ccobjs_as.pod',
{ SECTION => 'Classic objects' },
[ '/usr/local/packages/atria/current/lib/perl', [
'cc_cspec.pm',
'cc_get_context.pl',
'cc_label.pm',
'cc_tmp_view.pl' ] ],
[...]
The result is http://www.employees.org/~rnapier/ccobjdoc-index.html.
I'd like the buildup of $index_entries to be nicer (I don't like the
hard coded =item stuff), but other than that, it actually works quite
well, and we're expanding it to handle hierarchical indexes and
similar things, all without magic and in less than 200 lines of code.
I tried to build this on top of Pod::Parser and just didn't find it
orthogonal enough, at least from reading the docs. So that's where I'm
trying to go with all this. Maybe Pod::Parser is already there and I
just need to understand it better.
Thanks,
Rob
