[ https://issues.apache.org/jira/browse/DERBY-2389?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12673298#action_12673298 ]
Dag H. Wanvik commented on DERBY-2389: -------------------------------------- Really good to see this clean-up, Kim! :) Sorry for the late review. I am ok with committing now, and fixing up the remaining items in a follow-up patch if that seems better than respinning this large patch. I applied the patch and it built cleanly; I scanned the text for references to Tuning Derby and found only one outdated link, see below. - Dev guide (I reviewed this material by reading the pdf-version's new section on Working with properties in its entirety; so some comments below relate to issues with the original material from the Tuning guide, not to changes introduced by moving the material. Feel free to ignore such comments, fix them now, or make separate JIRAs for them as you see fit :-) * "Derby and Security" "Configuring security in a client/server environment" "This procedure requires a system with multiple databases and some administrative resources. 1. Configure security features as system properties. See Tuning Derby." *************** Outdated link. * working with properties - properties overview The sentence "When you change these properties, they affect any tables or indexes created after this change" occurs twice; under both system and database scope. Above, the term conglomerate is introduced and defined. Suggest use it in this sentence (why else define it?) Also I am a bit wary of the sentence itself, I would invert its structure to make clearer we are only talking about what happens for such properties in relation to conglomerates: "When you change these properties, they affect any conglomerates created after this change" Suggest: "For properties that affect conglomerates, changing the value of such properties only affect conglomerates created after the change. Conglomerates created earlier are unaffected". * Setting Derby properties: - In the reference to "IBM Application Developer Kits": Make this generic (not?) or include reference to Sun's Java as well.. - "not as properties of the type discussed in this book" "book" is misleading now; use section instead? - «For more information, see "java.sql.DriverManager.getConnection method" and "Setting attributes for the database connection URL" in the Derby Reference Manual.» After moving, maybe it is now reasonable here to refer directly with a link to the proper section in the dev guide as well? - "There should be one derby.properties file per system, not per database." Suggest: "There can be only one derby.properties file per system, not one per database." - "Database-wide properties, which affect a single database, are stored within the database itself. This allows different databases within a single Derby system to have different properties and ensures that the properties are correctly set when a database is moved away from its original system or copied." suggest: "... and ensures that the properties are correctly retained when a database is moved away..." - "Note: You should use database-wide properties wherever possible for ease of deployment." I think this point should be explained more at the outset of the "working with properties section" to give the user an idea up front that system properties are practical at development time, but database properties are preferrable at deployment time. I think we (used to?) have such an explanation somewhere.. can't find it right now... - "If you specify an invalid value, Derby uses the default value for the property." So, if a subsequent SYSCS_UTIL.SYSCS_GET_DATABASE_PROPERTY is called, does it return the default or the non-valid value set? The reference manual section doesn't explain this either: http://db.apache.org/derby/docs/dev/ref/rrefsetdbpropproc.html - Typo: "Client applications can set database-wide because * "properties" missing they are set via SQL statements." - "Client applications can set dynamic system-wide properties in an SQL statement, as shown in the example in Using a Properties object within an application or statement." This seems to refer to URL attribute setting on the client side, not dynamic system-wide properties? It also seems to contradict the earlier statement in this section: "In a client/server environment, you must set the system properties for the server's system." * Case study - "java -Dderby.system.home=c:\system_directory MyApp" and others should be marked as Windows-centric. This example could use an extra blank line, IMHO: java -Dderby.system.home=c:\system_directory -Dderby.storage.pageSize=4096 MyApp CREATE TABLE anothertable (a INT, b VARCHAR(10)) The rest of the changes i reviewed by looking at the diffs and the HTML pages. - adminguide/cadminlockvti83889.html OK - getstart/rgsdocs17307.html OK - ref/crefproper22250.html OK - ref/crefproper51399.html OK - ref/rrefproper24390.html OK - ref/rrefproper32213.html OK - ref/rrefsqlj31783.html The reference to Tuning guide here for cursors was removed I see. I guess you could make it applicable by just rewording it a bit, e.g. as "For more information about how indexes affect performance, see.." but it's not essential here, so removing it is fine too. - tuning/ctunpropref11181.html "how to tune systems" " also contain tuning tips" No need for both of the above? Seems confusing.. - tuning/ctunpropref23947.html OK - devguide/cdevconcepts22300.html OK Good new link here! - devguide/cdevcsecure864692.html OK - devguide/cdevdgpref23947.html Good catches here; missing stuff! - devguide/cdevdvlp13018.html OK - devguide/cdevdvlp39943.html OK - devguide/cdevdvlp846110.html "Note: You should work with database-level properties wherever possible." This statement should explained, I think, perhaps referring to a general section explaining recommended usage of system level ("flexible at development time") vs. database level properties ("safest for deployment") > DOCS - Move Derby system and properties info from Tuning Guide into Reference > Manual > ------------------------------------------------------------------------------------ > > Key: DERBY-2389 > URL: https://issues.apache.org/jira/browse/DERBY-2389 > Project: Derby > Issue Type: Improvement > Components: Documentation > Affects Versions: 10.4.2.0 > Reporter: Laura Stewart > Assignee: Kim Haase > Attachments: DERBY-2389-adminguide.diff, DERBY-2389-adminguide.stat, > DERBY-2389-adminguide.zip, DERBY-2389-devguide.diff, > DERBY-2389-devguide.stat, DERBY-2389-devguide.zip, DERBY-2389-getstart.diff, > DERBY-2389-getstart.stat, DERBY-2389-getstart.zip, DERBY-2389-phase2.diff, > DERBY-2389-phase2.stat, DERBY-2389-phase2.zip, DERBY-2389-ref.diff, > DERBY-2389-ref.stat, DERBY-2389-ref.zip, DERBY-2389-ref2.zip, > DERBY-2389-tuning.diff, DERBY-2389-tuning.stat, DERBY-2389-tuning.zip, > derbydev.pdf, tuningderby.pdf > > > From Derby User list: > On 2/21/07, Anders Morken <ander...@stud.ntnu.no> wrote: > > Shooting from the hip here, but one thing that has occured to me a few > > times as I've browsed the docs to figure something out is that I > > intuitively expect Derby system and database properties (especially the > > non-performance-related) to be documented in the reference guide, not > > the tuning guide. =) > On 2/21/07, Oystein Grovlen - Sun Norway <oystein.grov...@sun.com> wrote: > > I agree on this. I would have preferred that all "facts" where > > presented in the Reference Manual, and that the other manuals where more > > "pedagogical" presentations of the same material. Currently, it is not > > very intuitive to determine which manual has the information you are > > looking for. -- This message is automatically generated by JIRA. - You can reply to this email to add a comment to the issue online.