You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-dev@db.apache.org by "Kristian Waagan (Created) (JIRA)" <ji...@apache.org> on 2011/10/14 15:18:11 UTC
[jira] [Created] (DERBY-5464) Add easier to find links to Derby
JavaDoc on the Derby web site
Add easier to find links to Derby JavaDoc on the Derby web site
---------------------------------------------------------------
Key: DERBY-5464
URL: https://issues.apache.org/jira/browse/DERBY-5464
Project: Derby
Issue Type: Task
Components: Web Site
Affects Versions: 10.9.0.0
Reporter: Kristian Waagan
Assignee: Kristian Waagan
Priority: Minor
Add links to the Derby JavaDocs, which we do publish on the Derby web site.
They can currently be found under Resources -> Papers -> Engine -> JavaDoc, but I'm proposing we add links to them under Documentation.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Commented] (DERBY-5464) Add easier to find links to Derby
JavaDoc on the Derby web site
Posted by "Kristian Waagan (Commented) (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5464?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13127841#comment-13127841 ]
Kristian Waagan commented on DERBY-5464:
----------------------------------------
Thanks, Kim.
I'll address the trademark issue in the next revision of the patch, which will also include other required changes.
Regarding the links to the different parts of the API documentation:
o The public API is already linked to for each version of Derby on the documentation page.
o The Apache Derby Papers page probably doesn't include testing because it's all about the engine (I'm just guessing here). Not sure if Tools fits into that theory though...
Regarding the documentation page, we can (a) use "API documentation" and duplicate the link to the published API, or (b) use "Internal API documentation" with the engine, language, testing, and tools links.
I lean towards (b) - i.e. a kind of Derby user vs Derby developer distinction [1] - but can happily go with (a) too :)
Of course, the content can be organized in a totally different way too. For instance, we could add the links into the latest alpha docs table. My reason for not doing that, is that I doubt these links will be used much by Derby users.
[1] Tools may not fit here, but then again BNF isn't the most user friendly documentation in my opinion... At least this one has comments and some helpful text :)
> Add easier to find links to Derby JavaDoc on the Derby web site
> ---------------------------------------------------------------
>
> Key: DERBY-5464
> URL: https://issues.apache.org/jira/browse/DERBY-5464
> Project: Derby
> Issue Type: Task
> Components: Web Site
> Affects Versions: 10.9.0.0
> Reporter: Kristian Waagan
> Assignee: Kristian Waagan
> Priority: Minor
> Attachments: derby-5464-javadoc_links.diff, index-1a.html
>
>
> Add links to the Derby JavaDocs, which we do publish on the Derby web site.
> They can currently be found under Resources -> Papers -> Engine -> JavaDoc, but I'm proposing we add links to them under Documentation.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Commented] (DERBY-5464) Add easier to find links to Derby
JavaDoc on the Derby web site
Posted by "Kim Haase (Commented) (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5464?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13127557#comment-13127557 ]
Kim Haase commented on DERBY-5464:
----------------------------------
Thanks, Kristian, the Javadoc links are a very good thing to have on the Documentation page. I am a bit puzzled, though, because in the draft page the links go to
Engine -- http://db.apache.org/derby/javadoc/engine/
Language -- http://db.apache.org/derby/javadoc/language/
Testing -- http://db.apache.org/derby/javadoc/testing/
Tools -- http://db.apache.org/derby/javadoc/tools/
but not to the public API that would be of most use (I think?) to readers of the documentation. Whereas on the Apache Derby Papers page (http://db.apache.org/derby/papers/index.html), the links are to
Engine (same)
Language (same)
Tools (same)
API -- http://db.apache.org/derby/javadoc/publishedapi/
I wonder why the Testing API is not on the Papers site. Maybe it's in some other hard-to-find location?
Perhaps all 5 should be linked to from both Papers and Documentation? Although arguably the published API is not strictly speaking internal, so maybe the title should just be
Derby API Documentation
Technically, "Javadoc" (initial capital only) is (or was) a trademarked term and has to be used as an adjective -- Sun only allowed it to be used in front of "tool" or some such word, as I recall -- so we generally say "API documentation" instead. I wouldn't worry about leaving "Javadoc" on the Papers page, though.
> Add easier to find links to Derby JavaDoc on the Derby web site
> ---------------------------------------------------------------
>
> Key: DERBY-5464
> URL: https://issues.apache.org/jira/browse/DERBY-5464
> Project: Derby
> Issue Type: Task
> Components: Web Site
> Affects Versions: 10.9.0.0
> Reporter: Kristian Waagan
> Assignee: Kristian Waagan
> Priority: Minor
> Attachments: derby-5464-javadoc_links.diff, index-1a.html
>
>
> Add links to the Derby JavaDocs, which we do publish on the Derby web site.
> They can currently be found under Resources -> Papers -> Engine -> JavaDoc, but I'm proposing we add links to them under Documentation.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Updated] (DERBY-5464) Add easier to find links to Derby
JavaDoc on the Derby web site
Posted by "Kristian Waagan (Updated) (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5464?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Kristian Waagan updated DERBY-5464:
-----------------------------------
Attachment: index-1a.html
derby-5464-javadoc_links.diff
Attaching patch 1a, and the resulting HTML page (it looks odd due to the missing graphics etc, but the content can be seen).
Patch ready for review.
> Add easier to find links to Derby JavaDoc on the Derby web site
> ---------------------------------------------------------------
>
> Key: DERBY-5464
> URL: https://issues.apache.org/jira/browse/DERBY-5464
> Project: Derby
> Issue Type: Task
> Components: Web Site
> Affects Versions: 10.9.0.0
> Reporter: Kristian Waagan
> Assignee: Kristian Waagan
> Priority: Minor
> Attachments: derby-5464-javadoc_links.diff, index-1a.html
>
>
> Add links to the Derby JavaDocs, which we do publish on the Derby web site.
> They can currently be found under Resources -> Papers -> Engine -> JavaDoc, but I'm proposing we add links to them under Documentation.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Updated] (DERBY-5464) Add easier to find links to Derby
JavaDoc on the Derby web site
Posted by "Kristian Waagan (Updated) (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5464?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Kristian Waagan updated DERBY-5464:
-----------------------------------
Attachment: derby-5464-1b-javadoc_links.diff
Attaching patch 1b.
Feel free to improve the language.
> Add easier to find links to Derby JavaDoc on the Derby web site
> ---------------------------------------------------------------
>
> Key: DERBY-5464
> URL: https://issues.apache.org/jira/browse/DERBY-5464
> Project: Derby
> Issue Type: Task
> Components: Web Site
> Affects Versions: 10.9.0.0
> Reporter: Kristian Waagan
> Assignee: Kristian Waagan
> Priority: Minor
> Attachments: derby-5464-1b-javadoc_links.diff, derby-5464-javadoc_links.diff, index-1a.html
>
>
> Add links to the Derby JavaDocs, which we do publish on the Derby web site.
> They can currently be found under Resources -> Papers -> Engine -> JavaDoc, but I'm proposing we add links to them under Documentation.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Commented] (DERBY-5464) Add easier to find links to Derby
JavaDoc on the Derby web site
Posted by "Kim Haase (Commented) (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5464?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13127848#comment-13127848 ]
Kim Haase commented on DERBY-5464:
----------------------------------
Silly me, I managed to miss those HTML links at the top of the docs for every release. Sorry, and thanks for pointing them out.
You are right, (b) is the best bet, with the "Internal API documentation" section at the end, since it will be less often used.
> Add easier to find links to Derby JavaDoc on the Derby web site
> ---------------------------------------------------------------
>
> Key: DERBY-5464
> URL: https://issues.apache.org/jira/browse/DERBY-5464
> Project: Derby
> Issue Type: Task
> Components: Web Site
> Affects Versions: 10.9.0.0
> Reporter: Kristian Waagan
> Assignee: Kristian Waagan
> Priority: Minor
> Attachments: derby-5464-javadoc_links.diff, index-1a.html
>
>
> Add links to the Derby JavaDocs, which we do publish on the Derby web site.
> They can currently be found under Resources -> Papers -> Engine -> JavaDoc, but I'm proposing we add links to them under Documentation.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Resolved] (DERBY-5464) Add easier to find links to Derby
JavaDoc on the Derby web site
Posted by "Kristian Waagan (Resolved) (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5464?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Kristian Waagan resolved DERBY-5464.
------------------------------------
Resolution: Fixed
Fix Version/s: 10.9.0.0
Issue & fix info: (was: Patch Available)
Updated the staging area on ppl. Will close the issue when they go live.
> Add easier to find links to Derby JavaDoc on the Derby web site
> ---------------------------------------------------------------
>
> Key: DERBY-5464
> URL: https://issues.apache.org/jira/browse/DERBY-5464
> Project: Derby
> Issue Type: Task
> Components: Web Site
> Affects Versions: 10.9.0.0
> Reporter: Kristian Waagan
> Assignee: Kristian Waagan
> Priority: Minor
> Fix For: 10.9.0.0
>
> Attachments: derby-5464-1b-javadoc_links.diff, derby-5464-1c-javadoc_links.diff, derby-5464-javadoc_links.diff, index-1a.html
>
>
> Add links to the Derby JavaDocs, which we do publish on the Derby web site.
> They can currently be found under Resources -> Papers -> Engine -> JavaDoc, but I'm proposing we add links to them under Documentation.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Commented] (DERBY-5464) Add easier to find links to Derby
JavaDoc on the Derby web site
Posted by "Kim Haase (Commented) (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5464?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13130657#comment-13130657 ]
Kim Haase commented on DERBY-5464:
----------------------------------
The language looks fine to me. You might change "described as BNF" to "described in BNF", I think. And if I were really inclined to quibble, I would suggest changing "only useful for" to "useful only for", but this is not necessary.
> Add easier to find links to Derby JavaDoc on the Derby web site
> ---------------------------------------------------------------
>
> Key: DERBY-5464
> URL: https://issues.apache.org/jira/browse/DERBY-5464
> Project: Derby
> Issue Type: Task
> Components: Web Site
> Affects Versions: 10.9.0.0
> Reporter: Kristian Waagan
> Assignee: Kristian Waagan
> Priority: Minor
> Attachments: derby-5464-1b-javadoc_links.diff, derby-5464-javadoc_links.diff, index-1a.html
>
>
> Add links to the Derby JavaDocs, which we do publish on the Derby web site.
> They can currently be found under Resources -> Papers -> Engine -> JavaDoc, but I'm proposing we add links to them under Documentation.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Closed] (DERBY-5464) Add easier to find links to Derby
JavaDoc on the Derby web site
Posted by "Kristian Waagan (Closed) (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5464?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Kristian Waagan closed DERBY-5464.
----------------------------------
Changes are live, closing issue.
> Add easier to find links to Derby JavaDoc on the Derby web site
> ---------------------------------------------------------------
>
> Key: DERBY-5464
> URL: https://issues.apache.org/jira/browse/DERBY-5464
> Project: Derby
> Issue Type: Task
> Components: Web Site
> Affects Versions: 10.9.0.0
> Reporter: Kristian Waagan
> Assignee: Kristian Waagan
> Priority: Minor
> Fix For: 10.9.0.0
>
> Attachments: derby-5464-1b-javadoc_links.diff, derby-5464-1c-javadoc_links.diff, derby-5464-javadoc_links.diff, index-1a.html
>
>
> Add links to the Derby JavaDocs, which we do publish on the Derby web site.
> They can currently be found under Resources -> Papers -> Engine -> JavaDoc, but I'm proposing we add links to them under Documentation.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Updated] (DERBY-5464) Add easier to find links to Derby
JavaDoc on the Derby web site
Posted by "Kristian Waagan (Updated) (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5464?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Kristian Waagan updated DERBY-5464:
-----------------------------------
Issue & fix info: Patch Available
> Add easier to find links to Derby JavaDoc on the Derby web site
> ---------------------------------------------------------------
>
> Key: DERBY-5464
> URL: https://issues.apache.org/jira/browse/DERBY-5464
> Project: Derby
> Issue Type: Task
> Components: Web Site
> Affects Versions: 10.9.0.0
> Reporter: Kristian Waagan
> Assignee: Kristian Waagan
> Priority: Minor
> Attachments: derby-5464-javadoc_links.diff, index-1a.html
>
>
> Add links to the Derby JavaDocs, which we do publish on the Derby web site.
> They can currently be found under Resources -> Papers -> Engine -> JavaDoc, but I'm proposing we add links to them under Documentation.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Updated] (DERBY-5464) Add easier to find links to Derby
JavaDoc on the Derby web site
Posted by "Kristian Waagan (Updated) (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5464?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Kristian Waagan updated DERBY-5464:
-----------------------------------
Attachment: derby-5464-1c-javadoc_links.diff
Thank you, Kim.
I have made the changes you proposed, and I committed patch 1c (attached) to trunk with revision 1186707.
> Add easier to find links to Derby JavaDoc on the Derby web site
> ---------------------------------------------------------------
>
> Key: DERBY-5464
> URL: https://issues.apache.org/jira/browse/DERBY-5464
> Project: Derby
> Issue Type: Task
> Components: Web Site
> Affects Versions: 10.9.0.0
> Reporter: Kristian Waagan
> Assignee: Kristian Waagan
> Priority: Minor
> Attachments: derby-5464-1b-javadoc_links.diff, derby-5464-1c-javadoc_links.diff, derby-5464-javadoc_links.diff, index-1a.html
>
>
> Add links to the Derby JavaDocs, which we do publish on the Derby web site.
> They can currently be found under Resources -> Papers -> Engine -> JavaDoc, but I'm proposing we add links to them under Documentation.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira