[ http://issues.apache.org/jira/browse/TORQUE-50?page=comments#action_12429281 ]
I have got some comments regarding the documentation, mostly concerning its organisation. On the whole, I like it, but several points need to be addressed in my opinion. First, I'm not a big friend of howtos as a main source of documentation. Howtos are nice as a supplement, but if they are used as main documentation, it is very difficult for users to find the information they need because they have to scan through various howtos to find it. In my opinion, documentation should be in a "reference" form. Then, the procedure of how to submit supplements should be discussed at the dev mailing list; people should have a chance to object to this procedure if they wish. The main publishuing supplements on the torque site is not as easy as it sounds: First, all that is on there must be donated to the ASF and must have an apache licence. For larger contribution, the ASF wishes that a CLA is signed. Then, there is the problem of mirroring. The infrastructure team has not been amused in the past about non-mirrored downloads, so mirroring must be set up. Also, the ASF has a reputation for delievering rather high-quality software. This is achieved by reviewing all contributions by the committers. So before anything is put on the torque website, we want to be reasonably sure that it works, which also needs effort by the Torque team. Dont get me wrong, I'm not saying this is impossible, it is just things to keep in mind when such a procedure should be established. So I'd suggest the following: - move the documentation from the site to the generator, because it only affects the generator - add the property torque.override.dir to the generator properties reference, http://db.apache.org/torque/releases/torque-3.2/generator/properties-reference.html, and thell users that it only works if torque.useClasspath is set to true - Move the part about how templates work into an extra file and call it "how templates work" or the like. - discuss the part of how to submit references on the dev list > Supporting local and add-on Generator "Override" jars > ----------------------------------------------------- > > Key: TORQUE-50 > URL: http://issues.apache.org/jira/browse/TORQUE-50 > Project: Torque > Issue Type: Improvement > Components: Generator, Maven-Plugin, Documentation > Affects Versions: 3.2.1 > Reporter: CG Monroe > Priority: Minor > Fix For: 3.2.1 > > Attachments: Generator Override Support.zip > > > <From an e-mail proposal talked about on the torque-dev list> > I've been looking at how to package, document, contribute > my betwixt map/dtd generation code. As Thomas pointed out, > it's not truely mainstream Torque but might be a useful > addon. Anyway, this got me thinking about how to best > support template and/or generator local modifications or > add-on. > > If the generator build scripts supplied by the Torque > distro had classpaths that first tried to add any > *-override.jar files before the distro files, then > Templates and generator classes could easily be locally > overriden. This is trivial to do with the Ant > torque-build.xml. I assume that it would be easy in Maven? > > If no *override.jar files exist, it's a standard install. > But if you've got local changes to implement or want to > use a supplied add-on, just add *override.jar files to the > correct directory(s) and use the standard generation > processes. > > IMHO, this seems cleaner than trying to maintain a full > customized template or generator distros. If a new > version comes out, just grab the standard, check for > any gottcha's between it and your modified code, add back > in your override jars. All the benefits of a new version > with your local mods included. > > In a lot of cases, like changes to sql generation > templates (e.g. MySQL Table options ) or new db > adaptor support (like Informix/MSSQL7), this will be > very easy. These areas don't change a lot or are > mostly new templates. > > It also allows for easier add-on contributions. An add-on > could be supplied as a set of jars that are simply put in > the correct directories using common How-To instructions. > The add-in supplier just needs to document any additional > settings. > > It's not perfect since add-on's can override each other > and break... but it's better than it was. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
