The CaveatEmptor app was doing that. I think it's a good idea. Christian told be it was quite popular. That being said, I think the getting started guide explaining the tutorial should keep an embedded copy of the sources (at least partial - showing the code on the focused feature) to show people how to do things even if they don't download the sources per se. Emmanuel On 26 août 2010, at 20:21, Steve Ebersole wrote: > http://opensource.atlassian.com/projects/hibernate/browse/HHH-5441 > > There was a suggestion to externalize all the tutorial source into a > separate zip to make it even easier to get started. So as a user I'd be > able to download the tutorials.zip (with or without the "getting started > guide"), extract it and be up and running. The actual documentation > would then not have to have the contents of all these files in total, > which help cut down on the size as well, though might make it not as > easy to follow, not sure. > > Curious what y'all thought about this based on other tutorial sets you > have run across and used. > > -- > Steve Ebersole <steve(a)hibernate.org&gt; > http://hibernate.org > > _______________________________________________ > hibernate-dev mailing list > hibernate-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev

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.

Regarding the versions. Wouldn't you you some sort of filtering during build time?

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-&tutoria... > > Or maybe we need to assemble the URL externally and inject it: > <ulink url="&tutorialUrl"/> > >