Re: learning DocSet, was Re: perldocs2 plan

Stephen,

> I downloaded DocSet-0.14 and got the example running.
> See the results here.
> 
>    http://www.officevision.com/pub/DocSet/example/dst_html
>    http://www.officevision.com/pub/DocSet/example/dst_ps
> 
> FYI: I had to change the "id" in example/src/config.cfg
>      from "docs" to "home" (I assume anything would have worked)
>      because the "id" => "docs" was already in use in 
>      example/src/docs/config.cfg.  (It complained about a
>      duplicate id when I first ran it.)
>      (I don't have a patch file.)

Sorry about that. This example wasn't kept in sync with the doc, as i 
was mainly concentrating to finish perl.apache.org. I'm going to nuke 
this example and replace with a short version of perl.apache.org that 
really demonstrates all the features.

> If I understand how to use this correctly, I need my own
> distribution (perhaps "Devel::Perldocs") in which I
> have my own version of your "example" directory full of files.
> This defines styles, structure of resulting documents, and so forth.
> Devel::Perldocs would be the application component
> which uses [Module::Info and/or Devel::Metadata and/or Modinfo
> to gather the metadata (perhaps by implementing a replacement
> for DocSet::Source::* ?) and then uses DocSet to produce the
> documentation (with custom templates to create the
> desired look).

First, the best place to look at the usage is to download:
http://cvs.apache.org/snapshots/modperl-docs/

or using the cvs:
http://perl.apache.org/download/docs.html#Download

it includes the whole DocSet in its ./lib, but this is just to be safe 
and the site will always built properly if something goes wrong with 
system wide libraries. But otherwise this package sans the lib directory 
is all you need. (it creates the pds, src, etc).

so basically you need to have your distribution prerequisite DocSet.

> Rather than replace DocSet::Source::Pod, I could actually 
> create "metadata-enhanced" PODs as a result of all the metadata
> extraction and inherited-method-copying and then simply process
> these Pods in the normal way through DocSet.

Basically you either subclass DocSet::Source::Pod, or the top level 
DocSet::Source. And define your parser. I use Pod::POM for that, but you 
can use anything else.

Now you are the first to really extend things outside the main distro, 
so I'll be glad to work out with you the details and do the necessary 
changes to the code to make it really happen. Because currently the 
translation map is hardcoded in DocSet::Config:

my %conv_class = (
     'text/pod'  => {
                     'text/html'   => 'DocSet::Doc::POD2HTML',
                     'text/htmlps' => 'DocSet::Doc::POD2HTMLPS',
                     'text/ps'     => 'DocSet::Doc::POD2PS',
                    },
     'text/html' => {
                     'text/html'   => 'DocSet::Doc::HTML2HTML',
                     'text/htmlps' => 'DocSet::Doc::HTML2HTMLPS',
                     'text/ps'     => 'DocSet::Doc::HTML2PS',
                    },
     'text/plain' => {
                     'text/html'   => 'DocSet::Doc::Text2HTML',
                     'text/pdf'    => 'DocSet::Doc::Text2PDF',
                    },
);

> What other things would you describe had to be done in order
> to be able to generate documentation using DocSet which is
> similar to this?
> 
>    http://www.officevision.com/docs/perl
>    http://www.officevision.com/pub/p5ee/software/htdocs/api/

It's all about templates that render everything. DocSet builds a linked 
tree of docsets, chapters and links. In any node you can traverse the 
whole tree in any direction from the templates. For example this sitemap 
is autogenerated from a template that traverses all other nodes:
http://perl.apache.org/sitemap.html. DocSet works in two stages. First 
it parses everything and stores the data and metadata in objects. Then 
it renders everything using these objects.

The magic is happening in DocSet::NavigateCache. At any given moment you 
have the current node's navigation object. Then you can go up(), down(), 
first(), last(), next() etc within the templates. so building menus as 
in your example is easy. the new perl.apache.org is the best to 
demonstrate this functionality.

Just a word of caution, this project is very new and unpolished, so 
please bear with me if some things aren't clear or not perfectly 
working. As it gains more users I hope it'll become easier to grok. But 
I'm here to answer any questions you might have ;)

As mentioned at the beginning of this email, I'm going to work on making 
two examples this weekend. One for building a site like perl.apache.org, 
the other is to create slides and handouts. Once I'm done it'll be on 
its way to CPAN.

__________________________________________________________________
Stas Bekman            JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/     mod_perl Guide ---> http://perl.apache.org
mailto:[email protected] http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org   http://ticketmaster.com