Documentation is missing cross-references for connection URL attributes
-----------------------------------------------------------------------
Key: DERBY-3262
URL: https://issues.apache.org/jira/browse/DERBY-3262
Project: Derby
Issue Type: Bug
Components: Documentation
Affects Versions: 10.3.1.4
Reporter: Kim Haase
Assignee: Kim Haase
Priority: Minor
As part of a plan to improve the documentation of connection URL attributes,
I've found some topics that mention these attributes but don't point to
reference information about them. These topics should point to the descriptions
of the attributes in the Reference Manual, and the Reference Manual topics
should in turn point to some of them.
In the Admin Guide:
http://db.apache.org/derby/docs/dev/adminguide/tadminhubbkup44.html (Restoring
a database from a backup copy) lacks a reference to the restoreFrom=Path URL
attribute description in the Reference Manual
(http://db.apache.org/derby/docs/dev/ref/rrefrestorefrom.html) and vice versa.
http://db.apache.org/derby/docs/dev/adminguide/tadmincrtdbbkup.html (Creating a
database from a backup copy) lacks a reference to the createFrom=Path URL
attribute description in the Reference Manual
(http://db.apache.org/derby/docs/dev/ref/rrefcreatefrom.html) and vice versa.
http://db.apache.org/derby/docs/dev/adminguide/tadminlog800206.html (Using the
logDevice attribute) lacks a reference to the logDevice=logDirectoryPath URL
attribute description in the Reference Manual
(http://db.apache.org/derby/docs/dev/ref/rrefattrib72457.html) and vice versa.
It also needs to observe the convention of calling the attribute
logDevice=logDirectoryPath rather than just logDevice. Its parent topic,
Logging on a separate device
(http://db.apache.org/derby/docs/dev/adminguide/cadminlog98.html), needs to
observe the naming convention also.
http://db.apache.org/derby/docs/dev/adminguide/cadminappsclienttracing.html
should refer to the URL attribute topics related to tracing in the Reference
Manual. The Reference Manual topics already refer to this topic. Currently,
traceFileAppend isn't mentioned in cadminappsclienttracing.html; it should be
added, and the naming convention should also be observed.
The task topic
http://db.apache.org/derby/docs/dev/adminguide/cadminrollforward.html
(Roll-forward recovery) mentions the rollForwardRecoveryFrom=path URL attribute
description in the Reference Manual
(http://db.apache.org/derby/docs/dev/ref/rrefrollforward.html) but uses older
documentation conventions to refer to it, and duplicates some information. It
should be updated.
In the Tuning Guide:
http://db.apache.org/derby/docs/dev/tuning/ctunsetprop38343.html (Using a
properties object within an application or statement) has a note on connection
URL attributes that lacks a cross-reference either to the main Reference Manual
section (http://db.apache.org/derby/docs/dev/ref/rrefattrib24612.html) or to
the information about the DriverManager.getConnection method, which is also
mentioned (http://db.apache.org/derby/docs/dev/ref/rrefjdbc34565.html).
In the Tools Guide:
http://db.apache.org/derby/docs/dev/tools/ctoolsijtools16011.html (Database
connection URLs) probably duplicates information that exists elsewhere, but the
immediate problem is that it contains references to the Developer's Guide only.
It should also have a reference to the Reference Manual
http://db.apache.org/derby/docs/dev/ref/rrefattrib24612.html). Ideally, the
Developer's Guide references should be to specific topics rather than to the
entire manual, but the Developer's Guide has a lot of duplication in this area
that's a whole separate problem, and I don't want to add something that might
have to be backed out later.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
