Uploaded image for project: 'Derby'
  1. Derby
  2. DERBY-3262

Documentation is missing cross-references for connection URL attributes



    • Bug
    • Status: Closed
    • Minor
    • Resolution: Fixed
    • Documentation
    • None


      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.


        1. DERBY-3262.diff
          16 kB
          Camilla Haase
        2. DERBY-3262.stat
          0.5 kB
          Camilla Haase
        3. DERBY-3262.zip
          26 kB
          Camilla Haase



            chaase3 Camilla Haase
            chaase3 Camilla Haase
            0 Vote for this issue
            0 Start watching this issue