db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Kim Haase (JIRA)" <j...@apache.org>
Subject [jira] Commented: (DERBY-1920) DOCS - Improve topic titles for vague and duplicate topics
Date Thu, 04 Jan 2007 19:46:27 GMT

    [ https://issues.apache.org/jira/browse/DERBY-1920?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12462302

Kim Haase commented on DERBY-1920:

Thanks very much, Laura. Some comments on your comments:

About the two topics in the Developer's Guide (currently called "ALTER TABLE" and "BLOB and
"CLOB"): this is an interesting problem. These are currently subsections under the heading
"Derby and standards" and describe areas in which Derby follows or varies from a standard.

 Derby and standards
    * Calling functions and procedures
    * CLOB and BLOB
    * Cursors
    * DECIMAL max precision
    * Dynamic SQL
    * Expressions on LONGs
    * Information schema
    * NOT NULL characteristic
    * Transactions
    * Stored routines and PSM
    * Unique constraints and nulls
    * XML data types and operators

Most of them are just one or two sentences long, and in fact the text of most of them appears
in the "Derby and standards" topic itself because of how DITA manuals are processed. We could
argue that the individual topics should be removed and the texts instead be included in the
"Derby and standards" topic. (The last one, "XML data types and operators," is too long for
that.) What do you think?

a VALUES expression to call a function, but you use the CALL statement to call a procedure.
The functions and procedures are under different section topics.

About "ref/rrefsqlj1080962.dita" -- the example is just two short lines long -- not extensive
at all. So I think it is best to merge it with the "Expression precedence" topic, which is
not very long.

Since you are equally mystified about the inconsistent syntax in the connection attribute
titles, it seems likely that the inconsistencies are unintentional, and we can just go ahead
and make the titles consistent with the majority of the topics. Unless someone can explain
the inconsistencies, that is.

> DOCS - Improve topic titles for vague and duplicate topics
> ----------------------------------------------------------
>                 Key: DERBY-1920
>                 URL: https://issues.apache.org/jira/browse/DERBY-1920
>             Project: Derby
>          Issue Type: Bug
>          Components: Documentation
>    Affects Versions:
>            Reporter: Laura Stewart
>         Assigned To: Kim Haase
>             Fix For:,
>         Attachments: DERBY-1920.list, DERBY-1920_list_ls.htm
> 1) Many of the topic titles are vague. 
> Examples - 
> a) Almost all of the titles for the built-in function topics do not indicate that the
topic is about a "function".
> The word "function" should be added to all of the reference topics (In the Reference
Manual) that discuss the built in functions
> b) Almost all of the titles for the data type topics do not indicate that the topic is
about a data type.
> The words "data type" should be added to all of the reference topics (In the Reference
Manual) that discuss the data types
> c) Some of the SQL statement topic titles do not include the word "statement" in the
title and they should.
> 2)Some of the topics use the same title, but discuss very different things.  Each topic
title in the Derby documentation should be
> unique.  
> Examples - 
> LOCK TABLE statement in the Reference Manual (http://db.apache.org/derby/docs/dev/ref/rrefsqlj40506.html)
> and in the Tuning Guide (http://db.apache.org/derby/docs/dev/tuning/ctunoptimz11775.html)
> This is just one of several examples.

This message is automatically generated by JIRA.
If you think it was sent incorrectly contact one of the administrators: https://issues.apache.org/jira/secure/Administrators.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira


View raw message