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-2454) Derby Doc Web pages - update FAQ, patch procedures, and tips on formatting
Date Fri, 16 Mar 2007 15:44:09 GMT

    [ 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 &lt; and &gt; 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.


Mime
View raw message