[Catalyst-dev] RFC, docs reorg, again

[J. Shirley]

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