[Maypole] The plan for documentation

[Simon Cozens]

Oliver Gorwits:
> Might I suggest, as part of the documentation effort, a more complex
> example than the BeerDB application? Perhaps something that includes
> messing with visible columns, titles, aliases, Stringification,
> related_accessors, and so on.

Funny, I'm currently starting on the massive task of planning out and writing
the Maypole manual. I'm slightly worried that I won't be able to get this done
by September; I've applied for a TPF grant to be able to spend some time on
it, but I haven't heard back from them yet. I'm preparing it in the form of a
book, because I can write books, but it's unlikely that any publisher is going
to take on a manual for an unproven and hardly deployed emerging technology.
(Except perhaps for O'Reilly's new academic press series but they don't
commission books, only print existing ones.)

> I think this would really help those without experience of CDBI,
> Apache:: or TT who are probably happy with BeerDB but don't know what
> else is possible, or how to go about achieving something they have in
> mind.

Here's what I've written for the Overview document:

The Maypole documentation is arranged over several files; this is a good
one to start with.

Once you've read this, you should probably look at L<About.pod>, the
guide to what Maypole is and how the Maypole request works. It also
describes how to set up a simple CRUD web application in Maypole.

The next two chapters are quite thorough, and you might want to skip
over them if you already know how L<Class::DBI> and the L<Template>
toolkit work. L<Model.pod> and L<View.pod> describe these technologies
and their relationship to Maypole.

Now we present the default actions and templates - the F<factory>
templates - in L<StandardTemplates.pod>. When you have read these
chapters, you are ready to start building more complex applications in
Maypole than just a simple CRUD interface. L<Beer.pod> reintroduces the
beer database application and shows how to move from the "magic" of the
automatically supplied templates and actions to a customized application
with user-specified actions.

L<Request.pod> contains more information about the Maypole request
object and provides some cookbook-style techniques: how to provide
authentication, how to provide a REST interface, how to override various
stages of the content generation process, and so on.

The final chapters are examples of how to construct large web
applications in Maypole: L<Flox.pod> describes a "social network" site
similar to Friendster and Orkut; L<PetStore.pod> implements the Java/C#
benchmark Pet Store application; and L<Recipe.pod> describes a kitchen
management application.

> 'name' seems to be a magic column title; could this be made more
> obvious, or even better a facility to setup magic columns yourself?

Yeah, I think I've gone overboard on the DTRT magic. It'll all be documented
in the StandardTemplates chapter, and should ideally be changed so that the
name of magic columns can be specified in the config.

-- 
What would happen if you ran up to Hitler and mentioned Usenet?
	- Kibo