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
