[
https://issues.apache.org/jira/browse/DERBY-2454?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12481657
]
Kim Haase commented on DERBY-2454:
----------------------------------
These are really helpful updates, Laura. Thanks!
A few comments --
On docsfaq.html:
The new info on xrefs is very good to have. The example in "Cross references:
To a Web site" looks kind of odd in the HTML, though: it has the URL in angle
brackets in the middle of it, right after the URL not in angle brackets, which
seems strange.
<xref format="html"
href="http://www.w3.org/TR/xpath";<http://www.w3.org/TR/xpath>/xref>
I think what happened is that the < and > are reversed in the DITA
source. It should look like this, shouldn't it?
<xref format="html"
href="http://www.w3.org/TR/xpath";>http://www.w3.org/TR/xpath</xref>
I would also make an additional suggestion about links to URLs: that people add
the scope="external" attribute so the URL shows up in a different window from
the documentation page.
<xref format="html"
href="http://www.w3.org/TR/xpath";
scope="external">http://www.w3.org/TR/xpath</xref>
For "Cross references: To a DITA topic in a different Derby manual" it is
useful to have some convention and I guess bolding them is as good as any,
though I think that quotation marks are the usual convention for referring to
sections within a manual. The example is a little confusing, though, because
one of the section references uses <b> followed by "topic", while the other
uses <parmname> followed by "property". Should they not both be the same? Also,
the sentence in which they occur is a run-on.
At the end of "Semi-colon use at the end of statements and commands" there is
some missing punctuation in the last sentence (there should probably be a colon
after "2006" and a period at the end).
As for "SQL Terminology..." -- as I noted elsewhere (DERBY-2261), I don't think
it is correct to list "VALUES" as a clause; all the other clauses can occur
*only* as part of a statement, whereas "VALUES" can be used both as a clause
within a statement and as a statement. And it fits perfectly the definition of
expressions: "parts of SQL statements that return a value."
On index.html:
I like the rewording for the Derby API Reference, though I would suggest that
the second sentence could begin "No API reference" instead of "No javadoc".
I'm wondering if it might make sense to move the introductory paragraph about
DITA, under "10.1 Manuals," up near the top of the page. It's a bit hard to
find now and will get harder the more post-10.1 releases we list. It might also
make sense to change the first sentence from
Derby adopted the Darwin Information Typing Architecture (DITA) XML format for
the 10.1 Derby manuals.
to
Derby has been using the Darwin Information Typing Architecture (DITA) XML
format for the Derby manuals since Release 10.1.
For "10.0 Manuals", does the second sentence still make sense in a post-10.1
context? Maybe instead there should be a general statement near the top:
"Before reporting a problem in an earlier release of one of these manuals,
please check to see if the problem still exists in the latest release."
On dita.html:
I like Jean's suggestion.
There is a typo ("documenation") in the second line of the first paragraph.
I would suggest that under step 3 of "Submitting documentation patches" you
might explain what the propset command is for. I think it may be needed only if
you are using Windows, to fix the Windows-style line breaks. (Do you need it if
you have your svn config file set right? I use Unix so I don't know.)
You might mention that if you are deleting a file, you need to first delete the
file from your file system (using Windows Explorer or whatever) and then delete
it using svn. At least that is my experience.
Under step 5 -- you can also create a patch with changes for just one file, or
a few files -- but that may be overkill. BTW, this is very helpful. I've been
remiss about running "svn stat."
Under "Committing documentation patches", should it be noted that only someone
with committer status can do this? Or would it make more sense to put this up
at the top -- that anyone with developer status can create and submit issues
and patches but only committers can commit?
On guidelines.html:
Is the ending </p> tag where you meant it to be? It is not immediately after
the codeblock as the introductory paragraph implies.
> Derby Doc Web pages - update FAQ, patch procedures, and tips on formatting
> --------------------------------------------------------------------------
>
> Key: DERBY-2454
> URL: https://issues.apache.org/jira/browse/DERBY-2454
> Project: Derby
> Issue Type: Improvement
> Components: Web Site
> Reporter: Laura Stewart
> Assigned To: Laura Stewart
> Attachments: derby2454.zip, docpages031507_2.diff
>
>
> Update the FAQ:
> - How to create cross-references to other topics, other books, and web sties
> - How to format code examples
> Update DITA page:
> - Improve instructions on Creating a patch
> - Improve instructions on Commiting a patch
> Update Guidelines page:
> - Add a section on "Tips to Improve Output Formats"
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
