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 "Laura Stewart (JIRA)" <ji...@apache.org> on 2007/03/15 07:25:09 UTC
[jira] Created: (DERBY-2454) Derby Doc Web pages - update FAQ,
patch procedures, and tips on formatting
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
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.
[jira] Commented: (DERBY-2454) Derby Doc Web pages - update FAQ,
patch procedures, and tips on formatting
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2454?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12482457 ]
Kim Haase commented on DERBY-2454:
----------------------------------
docsfaq.html:
Sorry, I would have thought you wanted it to look like this:
<xref format="html" href="http://www.w3.org/TR/xpath">http://www.w3.org/TR/xpath</xref>
rather than this:
<xref format="html" href="http://www.w3.org/TR/xpath"<http://www.w3.org/TR/xpath>/xref>
index.html:
I was thinking that someone relatively new to the docs who wanted to contribute (like me, not so long ago) would not even know what "DITA Source" meant until they scrolled down to that information on the 10.1 manuals. I admit I was very ignorant....
dita.html:
My mistake entirely. I got mixed up between svn and the other version control system here (cvs). Sorry.
> 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, derby2454_2.zip, docpages031507_2.diff, docpages032007_3.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.
[jira] Updated: (DERBY-2454) Derby Doc Web pages - update FAQ,
patch procedures, and tips on formatting
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2454?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Laura Stewart updated DERBY-2454:
---------------------------------
Attachment: derby2454.zip
docpages011507.diff
Attaching a patch and zip file (html and site.xml files) that address the following things:
dita.html = Improved the patch create and commit procedures
docsfaq.html = Added how to tag cross references to other topics in the same book, a different book, or to a web site. Added best practices for formatting code samples.
guidelines.html = Added tips for formatting..
> 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, docpages011507.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.
[jira] Commented: (DERBY-2454) Derby Doc Web pages - update FAQ,
patch procedures, and tips on formatting
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2454?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12482480 ]
Laura Stewart commented on DERBY-2454:
--------------------------------------
Thanks Kim. Drat, you are correct :-) All I see in the format is the > or < got confused.
I'll fix and post a new patch.
> 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, derby2454_2.zip, docpages031507_2.diff, docpages032007_3.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.
[jira] Updated: (DERBY-2454) Derby Doc Web pages - update FAQ,
patch procedures, and tips on formatting
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2454?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Laura Stewart updated DERBY-2454:
---------------------------------
Attachment: (was: derby2454.zip)
> 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
>
> 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.
[jira] Updated: (DERBY-2454) Derby Doc Web pages - update FAQ,
patch procedures, and tips on formatting
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2454?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Laura Stewart updated DERBY-2454:
---------------------------------
Attachment: derby2454_3.zip
docpages032007_4.diff
Updated the one file per Kim's last comment.
Attaching a new patch and zip file.
> 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, derby2454_2.zip, derby2454_3.zip, docpages031507_2.diff, docpages032007_3.diff, docpages032007_4.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.
[jira] Closed: (DERBY-2454) Derby Doc Web pages - update FAQ, patch
procedures, and tips on formatting
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2454?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Laura Stewart closed DERBY-2454.
--------------------------------
> 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, derby2454_2.zip, derby2454_3.zip, derby2454_5.zip, docpages031507_2.diff, docpages032007_3.diff, docpages032007_4.diff, docpages032107_5.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.
[jira] Commented: (DERBY-2454) Derby Doc Web pages - update FAQ,
patch procedures, and tips on formatting
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2454?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12482431 ]
Laura Stewart commented on DERBY-2454:
--------------------------------------
Kim - There were a few of your comments that I did not implement:
On docsfaq.html:
The example in "Cross references: To a Web site" the angled brackets are correct.
On index.html:
I did not move the intro paragraphs under the 10.1 and 10.0 manuals because those are "snap shot" comments for people using those versions of the manuals...and I don't think that users of the docs really care what we author in :-) If they did, they would be looking at the Dita Source Web page.
On dita.html:
Deleting files. I am not sure what you mean here. IThe text mentions deleting a file from the ditamap and then delete using svn. If you delete it from your file system, it isn't there to delete it using svn... Please explain further so that I will understand.
> 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, derby2454_2.zip, docpages031507_2.diff, docpages032007_3.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.
[jira] Commented: (DERBY-2454) Derby Doc Web pages - update FAQ,
patch procedures, and tips on formatting
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2454?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12482889 ]
Kim Haase commented on DERBY-2454:
----------------------------------
Oh, right, it'd have to be some XML attribute in the Forrest DTD that would translate into valign in HTML. No problem.
The rest of the fixes look great. Thanks for making these improvements!
> 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, derby2454_2.zip, derby2454_3.zip, derby2454_5.zip, docpages031507_2.diff, docpages032007_3.diff, docpages032007_4.diff, docpages032107_5.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.
[jira] Commented: (DERBY-2454) Derby Doc Web pages - update FAQ,
patch procedures, and tips on formatting
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2454?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12482779 ]
Kim Haase commented on DERBY-2454:
----------------------------------
Thanks a lot, Laura, these look great. Just a few more comments --
1) In dita.html, you don't seem to have implemented Jean's suggestion about running ant. Are you leaving it for her next round of edits (as she volunteered to do) or was this just an oversight?
2) In guidelines.html, have you thought of aligning the table rows at the top? Currently the tables are a little hard to read because it is not clear which text belongs to which topic. I think that for each table with multiple-line cells, you could change each <tr> tag to
<tr valign="top">
Except maybe for the first row (the header), which is probably more readable if it is set to
<tr valign="bottom">
3) In docsfaq.html, there's one slight problem resulting from the fix in "Cross references: To a Web site". There is a hyphen after the scope attribute instead of an equals sign:
scope-"external"
should be
scope="external"
> 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, derby2454_2.zip, derby2454_3.zip, docpages031507_2.diff, docpages032007_3.diff, docpages032007_4.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.
[jira] Updated: (DERBY-2454) Derby Doc Web pages - update FAQ,
patch procedures, and tips on formatting
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2454?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Laura Stewart updated DERBY-2454:
---------------------------------
Attachment: derby2454_5.zip
docpages032107_5.diff
Sharp Eyes Kim !
I added the new wording for ant and corrected the cross ref to Web, but was unable to to implement the
table alignment change. For whatever reason, it did not accept the valign attribute.
Attaching the latest patch and zip file (version 5)
> 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, derby2454_2.zip, derby2454_3.zip, derby2454_5.zip, docpages031507_2.diff, docpages032007_3.diff, docpages032007_4.diff, docpages032107_5.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.
[jira] Commented: (DERBY-2454) Derby Doc Web pages - update FAQ,
patch procedures, and tips on formatting
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2454?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12482991 ]
Laura Stewart commented on DERBY-2454:
--------------------------------------
Committed revision 521086.
> 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, derby2454_2.zip, derby2454_3.zip, derby2454_5.zip, docpages031507_2.diff, docpages032007_3.diff, docpages032007_4.diff, docpages032107_5.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.
[jira] Updated: (DERBY-2454) Derby Doc Web pages - update FAQ,
patch procedures, and tips on formatting
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2454?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Laura Stewart updated DERBY-2454:
---------------------------------
Attachment: derby2454_2.zip
docpages032007_3.diff
Attaching an updated patch docpages032007_3.diff
and zip file based on the comments from Kim and Jean.
I implemented all of the comments, with a few exceptions which I will
explain in another comment.
New in this patch, I also updated the papers/derby_web.xml file per a separate comment from Jean.
> 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, derby2454_2.zip, docpages031507_2.diff, docpages032007_3.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.
[jira] Commented: (DERBY-2454) Derby Doc Web pages - update FAQ,
patch procedures, and tips on formatting
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ 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.
[jira] Commented: (DERBY-2454) Derby Doc Web pages - update FAQ,
patch procedures, and tips on formatting
Posted by "Jean T. Anderson (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2454?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12481438 ]
Jean T. Anderson commented on DERBY-2454:
-----------------------------------------
These changes look fine to me.
Just one minor note -- there's a typo in docsfaq.xml : "Tabs produce inconsisten output."
I have one suggestion for dita.xml that isn't related to anything you changed. I added this guideline way back when:
At the very least run ant html, ant monohtml and ant pdf to create HTML and PDF output (running ant all is best).
I think it could be tweaked to be more helpful/reasonable (not necessary to build the books you didn't change):
At the very least run 'ant <manual_id>' to create HTML and PDF output for the book you are changing.
If you're interested in making that additional change, I'd appreciate it. Or I can catch that in my next round of web site edits.
> 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.
[jira] Resolved: (DERBY-2454) Derby Doc Web pages - update FAQ,
patch procedures, and tips on formatting
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2454?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Laura Stewart resolved DERBY-2454.
----------------------------------
Resolution: Fixed
> 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, derby2454_2.zip, derby2454_3.zip, derby2454_5.zip, docpages031507_2.diff, docpages032007_3.diff, docpages032007_4.diff, docpages032107_5.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.
[jira] Updated: (DERBY-2454) Derby Doc Web pages - update FAQ,
patch procedures, and tips on formatting
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2454?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Laura Stewart updated DERBY-2454:
---------------------------------
Attachment: derby2454.zip
docpages031507_2.diff
Replaced the attachments with updated versions.
Also improved the index.html page by improving the getstart manual description, adding a description of the API Reference, and adding "Reference" in the tables after "API" so that it doesn't get overlooked for being too short a title (which I personally did :-)
> 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.
[jira] Updated: (DERBY-2454) Derby Doc Web pages - update FAQ,
patch procedures, and tips on formatting
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2454?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Laura Stewart updated DERBY-2454:
---------------------------------
Attachment: (was: docpages011507.diff)
> 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
>
> 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.