[hibernate-dev] Tutorials

[Steve Ebersole]

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