[hibernate-dev] Tutorials
Steve Ebersole
steve at hibernate.org
Fri Aug 27 20:23:04 EDT 2010
So I worked on this approach today.
http://anonsvn.jboss.org/repos/hibernate/core/trunk/documentation/quickstart/
This is the root source directory for the "Getting Started Guide" (its a
pom of type "jdocbook").
Under it is a "tutorials" directory which defines a (unrelated)
multi-module maven project for all of the tutorials (well the first 3,
still working up the envers one).
In the docbook then I simply refer to the classes etc from the
"tutorials".
On Fri, 2010-08-27 at 08:21 -0500, Steve Ebersole wrote:
> I guess my concern here is mostly the lack of cohesion. So we'd be
> discussing stuff in a web page opened in the users browser, referencing
> source code that is open in their IDE.
>
> I guess everything else is just technical details. Bottom line is
> whether we think this is easier for users or less.
>
> On Fri, 2010-08-27 at 06:34 -0500, Steve Ebersole wrote:
> > On Fri, 2010-08-27 at 10:50 +0200, Hardy Ferentschik wrote:
> > > I also like the idea of externalizing the docs.
> > >
> > > Have you thought about building maven archetypes? Not sure whether this
> > > would be possible with gradle though.
> > > Besides the archetype plugin sucks.
> >
> > Thought about it? Sure. My "issue" is that you'd have to create
> > multiple to be useful because of the inability to script within the
> > archetype. Really its just gonna handle the dependencies for you. Yeah
> > you could "whip up" somne MyEntity.java and MyEntity.hbm.xml
> >
> >
> > > Regarding the versions. Wouldn't you you some sort of filtering during
> > > build time?
> >
> > What I mean is that now you'd have some source code and some html. In
> > the html you have a choice:
> > 1) completely "reproduce" the source code inline
> > 2) tell the user where to get said source
> >
> > Really we'd probably need (2) anyway. The problem here is that we have
> > a choice:
> > 1) Are the examples versioned along with the project and docs?
> > 2) Or do we simply push the "latest" hibernate-tutorials.zip to a
> > well-known url and reference that from within
> >
> > In the second case lets say the url is "http://tutorials.hibernate.org".
> > Easy enough in terms of referencing; in the docbook source we'd just
> > direct the user to that url. The drawback is that all versions of the
> > getting-started-guide point here.
> >
> > In the first we'd need perhaps to leverage the injections we do right
> > now. TBH not sure the tutorials need updating and uploading for every
> > single release. Maybe major.minor is ok there, so 3.5 and 3.6 etc. At
> > any rate in the docbook source we'd need that fragment available and
> > could then use it in the url link *I think*:
> > <ulink
> > url="http://tutorials.hibernate.org/hibernate-tutorials-&tutorialVersion.zip"/>
> >
> > Or maybe we need to assemble the URL externally and inject it:
> > <ulink url="&tutorialUrl"/>
> >
> >
>
--
Steve Ebersole <steve at hibernate.org>
http://hibernate.org
More information about the hibernate-dev
mailing list