Menu
▾
▴
hibernate-devel
|
From: Gavin_King/Cirrus%<CI...@ci...> - 2002-07-19 17:41:46
|
>OK, I managed to get the basic conversion done right now. Have a look at >the PDF version and a quick zip of the XML source files: > >http://incubus.de/~turin/hibernate_reference.pdf >http://incubus.de/~turin/hibernate_reference_dbxml.tar.gz Awesome! The PDF looks great. I'm so excited ;) >- Move chapters and sections around for a more consistent read >- Convert graphics to vector and make a small styleguide for this >- Improve DSSSL stylesheet for PDF generation >- Prepare stylesheets for HTML version >- Add "Best Practices" chapter >- Write makefiles and documentation for automatic output generation >- Checkin to CVS All good. I have the original diagrams as visio documents (lame, i know) and I can send those if it would help at all. >This will take some days, maybe I can checkin a version early next week. >It's all not too difficult but time consuming stuff... I know how time consuming it is - your work is very appreciated :) Thanks Gavin. |
|
From: Gavin_King/Cirrus%<CI...@ci...> - 2002-07-25 02:09:25
|
>>- Move chapters and sections around for a more consistent read >Done. I hope this is an improvement. I need more time to think some of the reordering through .... the previous order was designed to get people started as quick as possible ... topics went from "basic" to "advanced". The new ordering is much more by subject which makes it more readable for most users but perhaps harder for brand new users just getting started. Anyway, I will put some thought into this and perhaps suggest some further changes. >I still have some ideas left and >like to rewrite some chapters (especially the transaction and >association handling, which seems most confusing for hibernate >beginners, including myself). Yeah, spot on. collections: Many users seem to have trouble the first time they map an association. But only ever that first time. That definately points to problems in the doco. transactions: Just recently I've noticed lots of people with problems arising from forgetting to flush the session when not using the Transaction API. Also people are uncomfortable calling Transaction.commit(), Transaction.rollback() when using container managed transactions. It needs to be clearer that this doesn't actually call UserTransaction.commit(), UserTransaction.rollback(). >>- Convert graphics to vector and make a small styleguide for this >Done. We are using OpenOffice Draw, because it's the only cross >platform vector drawing tool. Try it, it's not that bad if you know >how to use it. cool. unfortunately I'm having trouble checking this stuff out of CVS. Are you sure you checked in all the binary files with -kb? >>- Prepare stylesheets for HTML version >Modified stylesheets. Sorry, I didn't use the hibernate css (blue >background), because the images are not transparent and I don't have >time to fix this. It doesn't lock that bad either and could be easily >changed later. Its beautiful. The only problem with presentation at the moment is I think subsection headings are too large. I might be able to fix this just by fiddling the css. I'll have a look later. >>- Write makefiles and documentation for automatic output generation >Still pending because I haven't decided for make or Ant. I would very much prefer Ant if its at all possible. I've finally started using the ant build script to generate javadoc, etc, So it would be really nice to integrate this stuff with the existing stuff. My dream is to eventually be able to do a whole release with just a single Ant task but I'm not there yet ;) >>- Checkin to CVS >Done, with a lot of cursing about CVS over ssh. I cannot use any >graphical client with Unix... any solution for this problem? In my experience the graphical clients are really not worth the effort. I just use the cmd-line client under win2k, even though I _could_ use winCVS. >So, if everyone agrees that the new documentation can replace the old >"Programming Guide", the following steps would be neccessary: yes, I would like to do this stuff for 1.0.2 if possible, since I want to document the new 1.0.2 features in docbook. Could you tell me exactly how up to date the docbook text is compared to the aft text? I did make a couple of minor changes this week and I might need to copy them over. >Thats it. Hm, the "Toolset Guide" could be integrated as a separate >chapter? yep. And we should probably move the documentation of Dialects somewhere else, since they are no longer used only by the schema generator, as was originally the case. >The website itself could do with little reorg, too. I think the >whole Q&A and feature list is really one big block itself. The website could do with many improvements actually..... Thanks for all this Christian, its awesome. |
|
From: Anton v. S. <an...@ap...> - 2002-07-25 02:40:59
|
> I need more time to think some of the reordering through .... the > previous order was designed to get people started as quick as > possible ... topics went from "basic" to "advanced". The new > ordering is much more by subject which makes it more readable > for most users but perhaps harder for brand new users just > getting started. I haven't been following this too closely, other than to notice how amazing it all is - I love the pdf. But it had occurred to me previously that it might be worth having more than one index into the docs, at least for the HTML version. A "reference" index and a "tutorial" index, basically. Also, I would imagine that over time, stuff would end up in the reference section that wouldn't necessarily be appropriate in the tutorial. Anton |
|
From: Christian B. <chr...@bl...> - 2002-07-25 10:28:10
|
On 24 Jul (22:41), Anton van Straaten wrote:
> I haven't been following this too closely, other than to notice how amazing
> it all is - I love the pdf. But it had occurred to me previously that it
> might be worth having more than one index into the docs, at least for the
> HTML version. A "reference" index and a "tutorial" index, basically. Also,
> I would imagine that over time, stuff would end up in the reference section
> that wouldn't necessarily be appropriate in the tutorial.
Ok, I think I should point out the plan I have in my head for the
"Documentation" section of hibernate:
* QUICKSTART
- different beginners level documents (in form of articles)
- special case documents ("Quickstart: Integration with JBoss 3.0")
* REFERENCE
- complete reference documentation for alle functions and tools (book)
* TUTORIALS
- from beginner to expert and different scenarios (articles)
--
Christian Bauer
tu...@in...
|
|
From: Christoph S. <ch...@mc...> - 2002-07-25 07:50:34
|
Hey all! > -----Urspr=FCngliche Nachricht----- > Von: hib...@li...=20 > [mailto:hib...@li...] Im=20 > Auftrag von Gavin_King/Cirrus%CI...@ci... > Gesendet: Donnerstag, 25. Juli 2002 03:54 > An: Christian Bauer > Cc: hib...@li... > Betreff: Re: [Hibernate-devel] Documentation in DocBook > >>- Write makefiles and documentation for automatic output generation >=20 > >Still pending because I haven't decided for make or Ant. >=20 > I would very much prefer Ant if its at all possible. I've=20 > finally started using the ant build script to generate=20 > javadoc, etc, So it would be really nice to integrate this=20 > stuff with the existing stuff. My dream is to eventually be=20 > able to do a whole release with just a single Ant task but=20 > I'm not there yet ;) +1 for ant :)=20 Are there some problems doing it with ant, or why did you think about using make? I didnt use make for about 3 years now, and I'm really happy with it :) >=20 > >>- Checkin to CVS >=20 > >Done, with a lot of cursing about CVS over ssh. I cannot use any=20 > >graphical client with Unix... any solution for this problem? >=20 > In my experience the graphical clients are really not worth > the effort. I just use the cmd-line client under win2k, even=20 > though I _could_ use winCVS. If you are using windows, you should definately check out tortoise cvs, its an awesome cvs client :) http://tortoisecvs.sourceforge.net/ Cheers Chris |
|
From: Christian B. <chr...@bl...> - 2002-07-25 10:22:04
|
On 25 Jul (11:53), Gavin_King/Cirrus%CI...@ci... wrote: > I need more time to think some of the reordering through .... the > previous order was designed to get people started as quick as > possible ... topics went from "basic" to "advanced". The new > ordering is much more by subject which makes it more readable > for most users but perhaps harder for brand new users just > getting started. Anyway, I will put some thought into this and > perhaps suggest some further changes. My initial intention was to provide a complete reference documentation for all features. One of the next steps would be to provide "Quickstart" documentation for different scenarios. But I don't think this should be _in_ the reference documentation. > cool. unfortunately I'm having trouble checking this stuff out of CVS. > Are you sure you checked in all the binary files with -kb? Gah, used -ko, my fault. I think this can be fixed with a cvs admin -kb command? > I would very much prefer Ant if its at all possible. I've finally > started using the ant build script to generate javadoc, etc, So > it would be really nice to integrate this stuff with the existing > stuff. My dream is to eventually be able to do a whole release > with just a single Ant task but I'm not there yet ;) OK, I will try Ant. > yes, I would like to do this stuff for 1.0.2 if possible, since I want > to document the new 1.0.2 features in docbook. Could you tell me > exactly how up to date the docbook text is compared to the aft text? I > did make a couple of minor changes this week and I might need to copy > them over. You will need to add your changes, the converted version is more than a week old. P.S. I'm subscribed to the devloper list, no need to Cc. :) -- Christian Bauer tu...@in... |
|
From: Pierer c. <pie...@ya...> - 2002-07-25 16:52:20
|
There is a very interesting tool in Jakarta : http://jakarta.apache.org/turbine/maven/ This tool/environment, based on Java, allows you to perform usual tasks automatically and even to generate the website : As an example of project using marven, you can have a look at : http://jaxen.org/ Pierre > I would very much prefer Ant if its at all possible. > I've finally > started using the ant build script to generate > javadoc, etc, So > it would be really nice to integrate this stuff with > the existing > stuff. My dream is to eventually be able to do a > whole release > with just a single Ant task but I'm not there yet ;) __________________________________________________ Do You Yahoo!? Yahoo! Autos - Get free new car price quotes http://autos.yahoo.com |
|
From: Christian B. <chr...@bl...> - 2002-07-29 07:46:38
|
On 25 Jul (09:52), Pierer carion wrote: > There is a very interesting tool in Jakarta : > http://jakarta.apache.org/turbine/maven/ > This tool/environment, based on Java, allows you to > perform usual tasks automatically and even > to generate the website : Hm, I had a fist look at Maven and it may be possible to use it for hibernate. I'm not happy with the default directory layout (to simple) and some other things are still not clear. I will try to setup a hibernate project with Maven and report... -- Christian Bauer tu...@in... |
|
From: Gavin_King/Cirrus%<CI...@ci...> - 2002-07-25 04:59:12
|
Okay, I had a better chance to play with everything If anyone else wants to check out the new doco, be sure to use cvs upd -kb since images are checked in as text. We will have to fix that. Changes I'd like to see (some may not be possible): 1. currently, all <title> elements are transformed to <h2>. It would be much nicer if sect1/title would by rendered as <h3>. 2. can we get rid of the <p> tags inside <li> in the HTML version? (A minor issue, I suppose) 3. I think the persistent-classes and basic-or-mapping sections should come before the session-configuration section. Otherwise the order seems good. 4. The full_cream and lite architecture diagrams don't quite represent the same relationships I was trying to convey in the old diagrams. I will fix this. (The other architecture diagram is an improvement upon what I had.) 5. There is a bunch of important stuff presented as lists which really should be presented using tables now. The reason for the lists was that AFT didn't give me a good way to create tables. I will fix this ASAP. I have a long todo-list now so it may take me a couple of days to get round to everything. :) |
|
From: Christian B. <chr...@bl...> - 2002-07-25 10:38:41
|
On 25 Jul (14:43), Gavin_King/Cirrus%CI...@ci... wrote: > 1. currently, all <title> elements are transformed to <h2>. It would be > much nicer if sect1/title would by rendered as <h3>. I'll fix that. > 2. can we get rid of the <p> tags inside <li> in the HTML version? (A minor > issue, I suppose) Yes, but only in the stylesheets. The docbook requires a para in a listitem in XML. > 3. I think the persistent-classes and basic-or-mapping sections should come > before the session-configuration section. Otherwise the order seems good. Hm. My first approach would be to read the "how to get it up and running; aka configuration" and after that I will look into how to do basic things. That was my approach when getting in contact with hibernate and I jumped alot around the documentation to get a basic "configuration, load, manipulate, store"-cycle going. I think it's better that way (further down my todo-list is a rewrite and cleanup of the configuration section). Of course, if you insist, just move it around. > I have a long todo-list now so it may take me a couple of days to get round > to everything. Me too, I won't have any time until next week, so your changes will be checked in first. -- Christian Bauer tu...@in... |
|
From: Gavin_King/Cirrus%<CI...@ci...> - 2002-07-25 10:51:33
|
>> 3. I think the persistent-classes and basic-or-mapping sections should come >> before the session-configuration section. Otherwise the order seems good. >Hm. My first approach would be to read the "how to get it up and >running; aka configuration" and after that I will look into how to do >basic things. That was my approach when getting in contact with >hibernate and I jumped alot around the documentation to get a basic >"configuration, load, manipulate, store"-cycle going. I think it's >better that way (further down my todo-list is a rewrite and cleanup of the >configuration section). Okay, I hadn't realized that you were planning a quickstart guide. That changes things.... But could we temporarily move those sections earlier, then move them back to where they are now when the quickstart guide is complete? I just liked having the stuff about persistent classes right slap bang upfront so everyone sees how they don't have to do anything special. more in a sec.... |
|
From: Gavin_King/Cirrus%<CI...@ci...> - 2002-07-26 03:17:17
|
Yeah, funnily enough, I've just been noticing maven at the JCS project. Unfortunately, I don't have anywhere to host the project, only Sourceforge. I presume you need an actual box with an application server to run maven. |
|
From: Glen S. <gs...@ip...> - 2002-07-26 03:34:09
|
No app server is required for maven... all content is statically generated and uploaded using scp (and I think ssh). A similar tool is centipede (www.krysalis.org). Regards, Glen Stampoultzis (TriNexus Pty Ltd) Fixed:+61 3 9753-6850 Mob:+61 (0)402 835 458 ICQ: 62722370 EMail: gl...@ap... URL's: http://jakarta.apache.org/poi, http://www.krysalis.org > > Yeah, funnily enough, I've just been noticing maven at the JCS project. > Unfortunately, I don't have anywhere to host the project, only > Sourceforge. I presume you need an actual box with an application > server to run maven. > > > > ------------------------------------------------------- > This sf.net email is sponsored by: Jabber - The world's fastest growing > real-time communications platform! Don't just IM. Build it in! > http://www.jabber.com/osdn/xim > _______________________________________________ > Hibernate-devel mailing list > Hib...@li... > https://lists.sourceforge.net/lists/listinfo/hibernate-devel > |
|
From: Pierer c. <pie...@ya...> - 2002-07-27 01:18:11
|
Actually you just need to be able to do a scp and a ssh to your hosting machine. I don't know if you have such a possibility with SourceForge. Pierre --- Gavin_King/Cirrus%CI...@ci... wrote: > > Yeah, funnily enough, I've just been noticing maven > at the JCS project. > Unfortunately, I don't have anywhere to host the > project, only > Sourceforge. I presume you need an actual box with > an application > server to run maven. > __________________________________________________ Do You Yahoo!? Yahoo! Health - Feel better, live better http://health.yahoo.com |
|
From: Gavin_King/Cirrus%<CI...@ci...> - 2002-07-27 01:40:36
|
>Actually you just need to be able to do a scp and >a ssh to your hosting machine. >I don't know if you have such a possibility with >SourceForge. Yeah, Sourceforge allows ssh + scp. |
|
From: Christian B. <chr...@bl...> - 2002-07-24 17:53:24
|
On 20 Jul (03:26), Gavin_King/Cirrus%CI...@ci... wrote: > >- Move chapters and sections around for a more consistent read Done. I hope this is an improvement. I still have some ideas left and like to rewrite some chapters (especially the transaction and association handling, which seems most confusing for hibernate beginners, including myself). > >- Convert graphics to vector and make a small styleguide for this Done. We are using OpenOffice Draw, because it's the only cross platform vector drawing tool. Try it, it's not that bad if you know how to use it. > >- Improve DSSSL stylesheet for PDF generation Well, I did the best I could. Some things are still not nice (the Revision history) but difficult to fix. I think we should stay with the current layout until next time... > >- Prepare stylesheets for HTML version Modified stylesheets. Sorry, I didn't use the hibernate css (blue background), because the images are not transparent and I don't have time to fix this. It doesn't lock that bad either and could be easily changed later. > >- Add "Best Practices" chapter Done. > >- Write makefiles and documentation for automatic output generation Still pending because I haven't decided for make or Ant. This stuff is really complex and involves about 10 different shell commands for a complete conversion with about 8 different tools. My current helper scripts and all stylesheets (PDF and HTML) are _not_ in CVS. The stylesheets require some serious cleanup before everything is in the right place and ready for the repository. > >- Checkin to CVS Done, with a lot of cursing about CVS over ssh. I cannot use any graphical client with Unix... any solution for this problem? So, if everyone agrees that the new documentation can replace the old "Programming Guide", the following steps would be neccessary: - Change the link on the left frame from "Programming Guide" to "Documentation" - Link it to doc/reference/index.html in the right frame Thats it. Hm, the "Toolset Guide" could be integrated as a separate chapter? The website itself could do with little reorg, too. I think the whole Q&A and feature list is really one big block itself. -- Christian Bauer tu...@in... |
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X