db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Myrna van Lunteren (JIRA)" <derby-...@db.apache.org>
Subject [jira] Commented: (DERBY-383) Doc Review: Derby Tools and Utilities Guide
Date Fri, 24 Jun 2005 17:59:57 GMT
    [ http://issues.apache.org/jira/browse/DERBY-383?page=comments#action_12314412 ] 

Myrna van Lunteren commented on DERBY-383:
------------------------------------------

I commented on the list (because JIRA was unavailable). But here it is again...

-------------------------------------------------------------

I've been reviewing the PDF and using the page numbers on each page on line.
 
Firstly - I'm wondering if the section on export & import should get adjusted for the
identity column support...But I've not done this, maybe someone else can have a look at that?
  
general comments using PDF: 
- version on front - should be 10.1? or leave at at 10?
- p4 - Copyright - First Edition... says 2004. Should we change this? To Second Edition....
2005 ?
  Also, copyright says 1997, 2004. Should that get updated to
  2005?
- I'm not sure this can be changed, but in the PDF format, some of the syntax 'boxes' looked
really peculiar with only one word on each line...For example, in this manual, the 'Starting
ij' (p11) or the ij.outfile (p18) boxes are odd looking. 
- many ij examples have the ij version in it saying ij version 10.0. 
This should get changed to 10.1.
 
p7 - section JVM and class path for Derby tools
rewrite start of first sentence to include sysinfo:
'ij, dblook and sysinfo are tools...' and drop the last sentence (starting with 'sysinfo....environment.')
 
p8 - section Classpath. first bullet 2nd sentence has derbytools.jar again & needs an
extra space. change to:
'If you are using the embedded driver, you must also include derby.jar.'
       2nd bullet. rephrase to:
'To use the import and export utilities and the database class utilities youmust have derby.jar
in your class path. To use these from ij you must also have derbytools.jar in your class path.

       last bullet. rephrase first sentence to:
'To use Derby tools from a client with the Derby Network Server you must have derbyclient.jar
and derby.tools.jar in your class path. ...'
 
p 8, section Database connection URLs
bullet - there should be no space before databaseName and no spaces around the semi-colon.
 
p9 - Database connection URLs (cont from p 8) 
top bullet: there should be no space in front of databaseName
2nd bullet - there should be no space in front of, nor after, databaseName
 
p12 - section Starting ij using properties
rephrase 'To start ij bij using the ij.properties file, use...' to 'To start ij by using a
properties file ij.properties, use...'
 
replace the name 'sample' (in bold) with 'toursDB' (in bold) in the sentence:
'To start ij with an ij.protocol of ....'
 
in the example box including the -Dij.connection.toursDB remove the extra space before system.home
(so it becomes '-Dderby.system.home' and change the '/' slashes to '\' to reflect correct
DOS path separators.
 
URL's should be URLs in 'To see a list of connection names and the URL....'
 
p19 - ij.showErrorCode example.
The example does not actually reflect the result of a showErrorCode=true session...It's missing
the actual errorCode. Add: ' (errorCode = 30000)' behind the 'column 1.'
 
p 20 - the ij.URLCheck appears to not work when just using the database name and relying on
the -Dij.protocol. I think this may be a trivial, trivial bug, but for the sake of this document,
fully qualify the database name in the examples. 
Thus:
example1 becomes:
java org.apache.derby.tools.ij
ij version 10.1
ij> connect 'jdbc:derby:mydb;uSer=naomi';
URL Attribute [uSer=naomi]
     Case of the Derby attribute is incorrect
 
example 2 becomes:
java -Dij.URLCheck=false org.apache.derby.tools.ij
ij version 10.1
ij> connect 'jdbc:derby:mydb;uSer=naomi';
 
p 43 - section Bulk Import/Export overview
typo 1st bullet:...'You can use an procedure to export ...' should be 'You can use a procedure
to export ...'
 2nd bullet: 'Use import procedures to import data from a files ...' should be 'Use import
procedures to import data from a file ...'
 
p 43 - section Bulk import/export requirements and considerations, section Data Types: remove
',LONG VARBINARY, or LONG BINARY'
 
p 44 - section Bulk import and export, change second sentence to add 'from ij' at the end:
' You must have derbytools.jar in your class path to use the import or export procedures from
ij.'
(at least, I could do export fine without derbytools.jar).
 
p46 - bullet 'codeset' - uppercase the codeset, i.e. '(utf-8)' becomes '(UTF-8)'
 
p 47 - bullet 'tableName'  - insert 'the' between 'exactly match' and 'case' (so it becomes:
'The string must exactly match the case of the table name.')
 
p47 - last example box replace '/' with '\' i.e. the filename becomes 'c:\output\myfile.del'
 
p 48 - in 2nd and 3rd example box, replace the '/' in the file path with '/'. i.e. the filename
in the first example becomes 'c:\output\awards.del' and in the second example 'c:\output\myfile.del'
 
p52 - section Installing a jar example
replace '/' with '\' and drop the extra space in front of"ToursLogic!" so the example becomes
CALL SQLJ.install_jar('d:\todays_build\tours.jar','APP."ToursLogic!"',0);
 
p 54 - sysinfo example - example is outdated.
Replace with (you need to format the classpath, should really be 1 line - sorry):
$ java org.apache.derby.tools.sysinf
------------------ Java Information ------------------
Java Version:    1.4.2_07
Java Vendor:     Sun Microsystems Inc.
Java home:       c:\p4main\jdk142\jre
Java classpath:  c:\Derby_10\lib\derby.jar;
c:\Derby_10\lib\derbytools.jar;
c:\Derby_10\lib\derbyLocale_de_DE.jar;
e:\Derby_10\lib\derbyLocale_es.jar;
e:\Derby_10\lib\derbyLocale_fr.jar;
e:\Derby_10\lib\derbyLocale_it.jar;
e:\Derby_10\lib\derbyLocale_ja_JP.jar;
e:\Derby_10\lib\derbyLocale_ko_KR.jar;
e:\Derby_10\lib\derbyLocale_pt_BR.jar;
e:\Derby_10\lib\derbyLocale_zh_CN.jar;
e:\Derby_10\lib\derbyLocale_zh_TW.jar
OS name:         Windows 2000
OS architecture: x86
OS version:      5.0
Java user name:  myrna
Java user home:  C:\Documents and Settings\myhome
Java user dir:   E:\p4main\systest\myrtst7 
java.specification.name: Java Platform API Specification
java.specification.version: 1.4
--------- Derby Information --------
JRE - JDBC: J2SE 1.4.2 - JDBC 3.0
[E:\Derby_10\lib\derby.jar] 10.1.1.0 - (190628)
[E:\Derby_10\lib\derbytools.jar] 10.1.1.0 - (190628)
------------------------------------------------------ 
----------------- Locale Information -----------------
Current Locale :  [English/United States [en_US]]
Found support for locale: [de_DE]
         version: 10.1.1.0 - (190628)
Found support for locale: [es]
         version: 10.1.1.0 - (190628)
Found support for locale: [fr]
         version: 10.1.1.0 - (190628)
Found support for locale: [it] 
         version: 10.1.1.0 - (190628)
Found support for locale: [ja_JP]
         version: 10.1.1.0 - (190628)
Found support for locale: [ko_KR]
         version: 10.1.1.0 - (190628)
Found support for locale: [pt_BR]
         version: 10.1.1.0 - (190628)
Found support for locale: [zh_CN]
         version: 10.1.1.0 - (190628)
Found support for locale: [zh_TW]
         version: 10.1.1.0 - (190628)
------------------------------------------------------
 
p 54 - Using sysinfo to check the class path
The usage is outdated, it is now:
java org.apache.derby.tools.sysinfo -cp [ [ embedded ][ server ][ client] [ tools ] [  anyClass.class
] ]
 
so, p54 bullet 'embedded' stays, 
p 55 remove the bullets and replace by:
. server
. client
. tools
. classname.class
 
p 55 example box: remove the bit about the license (i.e. remove: 'Valid Derby license (derby.jar,
or for evaluation copies of the software only, license.jar)')
 
p 56 - Using dblook - 'For example ...' paragraph, replace '/' in the path with '\', i.e.
the section becomes ' ...to connect using the Network Server to a database 'C:\private\tmp\myDB'
on a remote ...'
 
same in example box, plus that one needs to loose the final semi-colon, and change the colon
before user into a semi-colon, so it becomes:
'jdbc:derby://localhost:1527/"C:\private\tmp\myDB";user=someusr;password=somepwd'
 
p 58 - fourth example needs to be modified similarly, i.e. it becomes
java org.apache.derby.tools.dblook -d 'jdbc:derby://localhost:1527/"C:\temp\sample";user=someusr;password=somepwd
' -z samp


> Doc Review: Derby Tools and Utilities Guide
> -------------------------------------------
>
>          Key: DERBY-383
>          URL: http://issues.apache.org/jira/browse/DERBY-383
>      Project: Derby
>         Type: Improvement
>   Components: Documentation
>  Environment: all
>     Reporter: Jeff Levitt
>     Priority: Minor
>      Fix For: 10.1.1.0

>
> This issue tracks comments for the Derby Tools and Utilities Guide. The deadline for
posting comments is Tuesday, June 28, noon Pacific time.
> Some guidelines to follow when posting comments to this issue are:
> - Try to make clear and concise comments about what you want changed whenever possible.
 Provide concrete comments that say "Please change <original> to <modified>" instead
of generic comments like "This section needs to be rewritten."
> - If you're reviewing the HTML Files copy, include the URL for the page in the review
comment. Obtain the URL like this:
>     * highlight the topic in the left frame
>     * right click
>     * choose "Properties"
>     * copy and paste the address in the pop up box.
> - If you're reviewing the PDF copy, in the review comment:
>     * Include the page number for the PDF, and indicate whether the number is the PDF
sheet number or the printed page number.
>     * Include the title of the section that the problem occurs in. If it's in a subsection,
try to include the hierarchy of titles.
> - Please don't review the HTML Book copy -- it'll be time consuming to match up that
copy with the underlying DITA source.

-- 
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


Mime
View raw message