jshirley at gmail
May 4, 2008, 9:16 AM
Post #15 of 28
(603 views)
Permalink
|
On Sun, May 4, 2008 at 6:53 AM, Matt S Trout <dbix-class[at]trout.me.uk> wrote:
> On Sun, May 04, 2008 at 08:15:16AM +1000, Kieren Diment wrote:
> >
> > On 4 May 2008, at 07:35, Matt S Trout wrote:
> >
> > >On Sat, Apr 26, 2008 at 09:03:43PM +1000, Kieren Diment wrote:
> > >>Please consider this idea:
> > >>
> > >>Ditch the Catalyst::Manual dist, move everhthing that's not the
> > >>tutorial back into Catalyst::Devel, and make a separate
> > >>Catalyst::Manual::Tutorial dist.
> > >
> > >Make it a Catalyst::Devel dependency if you like.
> > >
> > >-1 on rolling the thing back in unless somebody can show a genuine
> > >advantage to it; "please consider this idea" doesn't count as a
> > >reason.
> > >
> > >
> >
> > (Almost) Everyone with ::Devel installed needs the docs - but not
> > everyone with ::Devel installed needs the tutorial.
> >
> > So we've got two independent dists here - the first are informational
> > pages (mostly pretty stable, Intro could do with a significant
> > rework) and the second is the somewhat out-of-date tutorial.
> >
> > so a Catalyst::Manual dist, and a Catalyst::Manual::Tutorial dist is
> > what you're suggesting instead?
>
> I'm not suggesting anything. I'm asking you to justify your suggestion.
>
>
>
> > I'm just not completely sure of the
> > advantage of yet another dist, when Devel has a long release cycle
> > anyway, and the content of these pages is reasonably tightly coupled
> > to the code.
> >
> > ./Catalyst/Manual/About.pod
> > ./Catalyst/Manual/Actions.pod
> > ./Catalyst/Manual/Cookbook.pod
> > ./Catalyst/Manual/DevelopmentProcess.pod
> > ./Catalyst/Manual/ExtendingCatalyst.pod
> > ./Catalyst/Manual/Internals.pod
> > ./Catalyst/Manual/Intro.pod
> > ./Catalyst/Manual/Plugins.pod
> > ./Catalyst/Manual/WritingPlugins.pod
> >
> > The second are tutorial pages (needs an overhaul - mainly ditching
> > HTML::Widget for FormFu or Formbuilder and using the new auth
> > framework API):
> >
> > ./Catalyst/Manual/Tutorial/AdvancedCRUD.pod
> > ./Catalyst/Manual/Tutorial/Appendices.pod
> > ./Catalyst/Manual/Tutorial/Authentication.pod
> > ./Catalyst/Manual/Tutorial/Authorization.pod
> > ./Catalyst/Manual/Tutorial/BasicCRUD.pod
> > ./Catalyst/Manual/Tutorial/CatalystBasics.pod
> > ./Catalyst/Manual/Tutorial/Debugging.pod
> > ./Catalyst/Manual/Tutorial/Intro.pod
> > ./Catalyst/Manual/Tutorial/Testing.pod
> > ./Catalyst/Manual/Tutorial.pod
>
> So move Catalyst::Manual:: into devel and have a separate tutorial dist?
>
> Could work but the reason we moved the damn thing out was complaints
> from the documenters that doc releases were waiting for a release of a code
> containing package (though that was -Runtime IIRC).
>
> How about if we put all this crap off, and first work on getting a
> docs -> HTML rendering that can live on the website done (I believe Jay
> got most of the way to this). Then we can have the POD versions say very
> clearly "we're a goddamn snapshot, here's the latest" and shifting them
> back into a code dist ceases to be an issue.
>
> Thoughts?
>
Docs -> HTML is good, but only works if someone is connected to the
interweb and doesn't want local docs so I see them as two separate
issues, really.
Catalyst-Devel could include Manual, because Devel doesn't get
released all that often and I don't think it will hurt to push updates
frequently. If we have a Catalyst(?:::Manual)?::Tutorial dist, we
could potentially start bundling up many tutorials... but, CPAN isn't
a repos for tutorial packages - unless we include the working apps
with them. So, Catalyst::Tutorial::Book could be a working app,
complete with documentation... this would also help alert us to stale
tutorials because the tests would undoubtedly fail when things change
(like the Authorization refactor; jayk++ again for that)
The static doc builder code is done, pulls from a table of contents
file so there is cohesive navigation and you just point it to pod
sources and away it goes:
http://dev.catalystframework.org/repos/Catalyst/branches/site-notrac/podbuilder/
The navigation bits need some work, and I really hate doing UI pixel
pushing but it is there and works. The code could vastly be cleaned
up, this was just a flurry of some hacking and my first foray into
dealing with the pod processing modules.
PS., thank you for fixing -Manual.
-J
_______________________________________________
Catalyst-dev mailing list
Catalyst-dev[at]lists.scsys.co.uk
http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst-dev
|
1
