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 "Kim Haase (JIRA)" <de...@db.apache.org> on 2006/10/17 20:03:35 UTC
[jira] Created: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Working With Derby needs some formatting fixes and other minor cleanup
----------------------------------------------------------------------
Key: DERBY-1972
URL: http://issues.apache.org/jira/browse/DERBY-1972
Project: Derby
Issue Type: Bug
Components: Documentation
Affects Versions: 10.2.1.6
Reporter: Kim Haase
Assigned To: Kim Haase
Priority: Minor
The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=comments#action_12455392 ]
Laura Stewart commented on DERBY-1972:
--------------------------------------
Thanks Kim, having the dita will be a huge help to me :-)
I agree, let's try to avoid so much italic tagging if there is a good DITA tag that will format the text in either monospace or italic. So codeph is a good one to use.
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972-2-dita.zip, DERBY-1972-2.diff, DERBY-1972-2.zip, DERBY-1972.zip, DERBY_1972.diff
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Laura Stewart (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=comments#action_12443311 ]
Laura Stewart commented on DERBY-1972:
--------------------------------------
I think that the topbot attribute should be removed from all of the <codeblock> tags in the WWD book.
None of the other books use that convention. The PDF and monohtml have gray backgrounds for codeblocks to set off examples.
Also, instead of using stepxml and dl for the different operating systems, I recommend using a choice table. For example:
<choicetable>
<chhead><choptionhd>Operating System</choptionhd><chdeschd>Step</chdeschd>
</chhead>
<chrow><choption>On Linux</choption><chdesc></chdesc></chrow>
<chrow><choption>On Windows</choption><chdesc></chdesc></chrow>
</choicetable>
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Closed: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=all ]
Kim Haase closed DERBY-1972.
----------------------------
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Fix For: 10.2.3.0
>
> Attachments: DERBY-1747.diff, DERBY-1972-2-dita.zip, DERBY-1972-2.diff, DERBY-1972-2.zip, DERBY-1972-3-dita.zip, DERBY-1972-3.diff, DERBY-1972-3.zip, DERBY-1972-4-dita.zip, DERBY-1972-4.diff, DERBY-1972-4.zip, DERBY-1972.zip, DERBY_1972.diff
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=comments#action_12458960 ]
Laura Stewart commented on DERBY-1972:
--------------------------------------
Hi Kim -
The updates look really good. I noticed something that I hadn't noticed before. When we use note=type important, it adds a > symbol in front of the note. This might be something for us to look at with the new version of the DITA toolkit.
I'll commit these changes. Thanks for ALL of your hard work on these files !
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972-2-dita.zip, DERBY-1972-2.diff, DERBY-1972-2.zip, DERBY-1972-3-dita.zip, DERBY-1972-3.diff, DERBY-1972-3.zip, DERBY-1972-4-dita.zip, DERBY-1972-4.diff, DERBY-1972-4.zip, DERBY-1972.zip, DERBY_1972.diff
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=all ]
Kim Haase updated DERBY-1972:
-----------------------------
Attachment: DERBY-1972-2-dita.zip
I see the problem! I'm attaching the DITA files.
I tried to observe the Getting Started doc conventions. There are a couple of items that aren't covered in those conventions: command-line commands (vs. SQL ones) and URL connection attributes. For these I used codeph, but if you think they should be in italic I can make that change. I still haven't figured out the principle behind putting so many things in italics.
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972-2-dita.zip, DERBY-1972-2.diff, DERBY-1972-2.zip, DERBY-1972.zip, DERBY_1972.diff
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=comments#action_12455401 ]
Laura Stewart commented on DERBY-1972:
--------------------------------------
Hi Kim -
Here are my comments:
PDF copyright (page 4) appears run together. I would ask about this on derby-dev and perhaps someone like Andrew can fix it. he copyright info on page 5 is just fine.
Introduction and prerequisites = twwdIntro.dita
The shortdesc seems really long. How about this:
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972-2-dita.zip, DERBY-1972-2.diff, DERBY-1972-2.zip, DERBY-1972.zip, DERBY_1972.diff
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=all ]
Kim Haase updated DERBY-1972:
-----------------------------
Attachment: DERBY-1747.diff
DERBY-1972.zip
I hope I have not done too much here. Please let me know if I need to split the fixes into a series of smaller bugs and fix them piecemeal. All of the fixes fall into one of the categories listed here. The diffs file will be hard to read, so the zip file includes all the book output files (HTML and PDF).
Consistent formatting:
Used <varname> only for replaceable items, <codeph> elsewhere
Used <userinput> and <systemoutput> tags, with user input in bold to distinguish it from output in plain code font (instead of <b> and <i>)
Replaced <dl> with tables to indicate input and output for different operating systems (used <simpletable> throughout, for consistency, because <choicetable> is not allowed in substeps)
Used bulleted lists (<ul>) where helpful
Removed horizontal rules (using the attribute frame="topbot") from above and below code blocks (this also eliminates all the error messages in the PDF/monohtml generation)
Made formatting consistent with other books: SQL statement names and table names are capitalized but are not in code font
Made xrefs to websites scope="external" instead of scope="local", so they open in a separate window instead of in the same frame as the manual page
Files:
Made conrefs file similar to that for other books (references to manuals, Derby, DERBY_HOME as well as version)
Removed instructions on installation and referred users to Getting Started book (it's best that this information be in one place only for maintainability)
Language:
Changed passive to active voice where it would remove ambiguity
Avoided present participles where possible (for translatability)
Changed future tense to present where appropriate
Fixed dangling participles
Added hyphenation where needed
Fixed punctuation where needed
Removed "please" where needed
Corrected sentence fragments
Removed unnecessary verbiage
Removed ambiguous phrasing (changed "key files" to "most important files" since "key" has special meanings for databases and security; changed "enter" to "type" when that's what it means)
Removed unnecessary quotation marks
Used capitalization and lowercase consistently
Used terms consistently (used the same word to mean the same thing throughout)
Terminology:
Consistently used "client/server" instead of "client-server" or "Client-Server"(after checking other Derby docs)
Used "Java Development Kit" and "JDK" consistently
Used "ij" consistently (lowercase)
Used "jar files" and "class files" consistently
Used "shut down", "start up", and "set up" as verbs, "shutdown", "startup", and "setup" as adjectives and nouns
Changed "UNIX/Linux" to "UNIX" to conform to usage in other Derby manuals
Trademarks:
Used "Java" and "JDBC" as adjectives only
Put "UNIX" in uppercase
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972.zip
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=all ]
Kim Haase updated DERBY-1972:
-----------------------------
Attachment: DERBY_1972.diff
So sorry. Thank you for the catch, Laura! A slip of the file-chooser finger...
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972.zip, DERBY_1972.diff
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=comments#action_12447572 ]
Kim Haase commented on DERBY-1972:
----------------------------------
Thanks, Laura. Actually I have since realized that I failed to observe the doc conventions outlined in the Getting Started book for some things. I will probably need to fix that.
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972.zip
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=all ]
Laura Stewart updated DERBY-1972:
---------------------------------
Derby Info: (was: [Patch Available])
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972-2-dita.zip, DERBY-1972-2.diff, DERBY-1972-2.zip, DERBY-1972-3-dita.zip, DERBY-1972-3.diff, DERBY-1972-3.zip, DERBY-1972-4-dita.zip, DERBY-1972-4.diff, DERBY-1972-4.zip, DERBY-1972.zip, DERBY_1972.diff
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=comments#action_12447547 ]
Laura Stewart commented on DERBY-1972:
--------------------------------------
WOW. You did a lot of work on this book. Thank you !!!
I'll look over the tagging as soon as I get a chance.
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972.zip
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=all ]
Kim Haase updated DERBY-1972:
-----------------------------
Attachment: DERBY-1972-2.diff
DERBY-1972-2.zip
DERBY-1972-2.diff is a replacement patch that includes the following additional fixes: 1) Substitution of productshortname from new conrefs file for the one file that didn't have that before; 2) fixes to observe typographical conventions listed in Getting Started manual. Please use this patch instead of the first one.
DERBY-1972-2.zip contains the output files for this version.
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972-2.diff, DERBY-1972-2.zip, DERBY-1972.zip, DERBY_1972.diff
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=comments#action_12458979 ]
Laura Stewart commented on DERBY-1972:
--------------------------------------
Committed patch Derby-1972-4.diff with revision 487729.
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972-2-dita.zip, DERBY-1972-2.diff, DERBY-1972-2.zip, DERBY-1972-3-dita.zip, DERBY-1972-3.diff, DERBY-1972-3.zip, DERBY-1972-4-dita.zip, DERBY-1972-4.diff, DERBY-1972-4.zip, DERBY-1972.zip, DERBY_1972.diff
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=comments#action_12456158 ]
Kim Haase commented on DERBY-1972:
----------------------------------
Thanks, Laura! I'm glad we are in agreement about what doc conventions are normal. I agree with proposing to the list that we update Getting Started to use what we might call "conventional conventions" and that we incrementally update the docs to use them.
So if we can do that, then filepath and cmdname should be in code font. And as you say, userinput should be in bold code font instead of the current plain code font.
I have learned a little XSL in my time, but it gets me only so far with the toolkit, whose organization is rather baroque. However, I think I have actually found the files that we could change for both the HTML and the PDF/monohtml output: DITA-OT1.1.2.1/xsl/xslhtml/sw-d.xsl and DITA-OT1.1.2.1/xsl/xslfo/domains2fo.xsl.
I'll work with your comments in the meantime.
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972-2-dita.zip, DERBY-1972-2.diff, DERBY-1972-2.zip, DERBY-1972.zip, DERBY_1972.diff
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=comments#action_12455743 ]
Laura Stewart commented on DERBY-1972:
--------------------------------------
Let's try this again...
Hi Kim -
Thanks for including the DITA files, my ol' eyes can read those files much easier than the diff files :-)
You have made some great improvements in the tagging and formatting. Some of the formatting you use (pre for example) is not what I am used to, and I think we need to discuss what we want to promote/recommand as we go forward with more edits to the Derby doc files. But for the most part I think we are on the same page and use most the same tags.
Here are my comments:
PDF copyright (page 4) appears run together. I would ask about this on derby-dev and perhaps someone like Andrew can fix it. he copyright info on page 5 is just fine.
All of the files seem to have a comment at the top with a date of the "contribution". The dates seem to be from earlier this year. Also there is a rev attribute on the first tag. Do you think that we should maintain the contribution date or remove it? Are you using the rev attribute?
File = twwdIntro.dita (Introduction and prerequisites)
The shortdesc seems really long. How about this:
<shortdesc>
Welcome to <ph conref="wwdconrefs.dita#prod/productshortname"></ph>! To help you get up and running with <ph conref="wwdconrefs.dita#prod/productshortname"></ph> as quickly as possible, this self-study guide highlights some of the more important
features of <ph conref="wwdconrefs.dita#prod/productshortname"></ph>
</shortdesc>
<p>
This guide uses a series of activities designed to demonstrate the use of <ph conref="wwdconrefs.dita#prod/productshortname"></ph> in
the embedded and client/server configurations. After performing these activities, you will find <ph conref="wwdconrefs.dita#prod/productshortname"></ph> to be an easy-to-use and fully functional RDBMS.
</p>
Also, should we assume that Derby users understand the abbreviation RDBMS? I am thinking specifically about people for whom English is not their first language.
The index terms for this file are a little vague. How about these:
Java Development Kit version
validating
JDK version
validating
Working with Derby activities
prerequistes
prerequistes
Working with Derby activities
environment variables
verifying
JAVA_HOME environment variable
verifying
DERBY_HOME environment variable
verifying
"website" should be "Web site".
I don't like the way that the text in the steps runs together. I tried to fix it but there must be something that we need to change in the CSS or elsewhere to get better formatting. I don't know how to fix this now, but we need to address it for the html output. Maybe a goal for 10.3? We also need to fix the formatting in the choice tables. The text in the second columns is always 1 line below the text in the first column. I would prefer to use
choice tables in the steps but let's leave the simple tables in there for now until we can figure it out.
Step 1 - In one place you use userinput and another codeph. In another place you use userinput and systemoutput. I have consistenly used codeph inline in paragraphs and codeblocks in choicetables and for blocks of code. They all produce monospace and there is no formatting difference between them. Is there a reason that you think we should use each of these tags. If we were in an proprietary project where doc contributors are all tech writers, or if these tags actually produced formatting differences, then I would be all for using unique tags (in the hopes that some day the formatting would be unique between the text - aka DITA flexibility). But I am concerned overburdening our open source contributor with too many different tags to learn...
Why do you use the "pre" tag? In many cases I don't think that it is necessary.
"via" is latin based and can cause problems with translation. It should be changed to ""by using".
File = cwwdactivities.dita (Activity overview)
There are no index entries. How about adding this index entry:
Working with Derby activities
overview
There is a definition list here that doesn't appear to be used properly. There are empty dt tags and a series of dd tags with paragraph tags inside. It would be best if it was formatted like this:
<dl>
<dlentry>
<dt>Activity 1:</dt>
<dd>Use the <ph conref="wwdconrefs.dita#prod/productshortname"></ph> <codeph>ij</codeph> tool to load the <ph conref="wwdconrefs.dita#prod/productshortname"></ph> embedded driver and start the <ph conref="wwdconrefs.dita#prod/productshortname"></ph> database engine. Create the database <i>firstdb</i> and the table FIRSTTABLE. Use a
few basic SQL commands to insert and select data. The <ph conref="wwdconrefs.dita#prod/productshortname"></ph> message log <i>derby.log</i> and the database directories and files are introduced.
</dd>
</dlentry>
<dlentry>
<dt>Activity 2:</dt>
<dd>Use <ph conref="wwdconrefs.dita#prod/productshortname"></ph> within a client/server configuration. Start the <ph conref="wwdconrefs.dita#prod/productshortname"></ph> Network Server, which will embed the <ph conref="wwdconrefs.dita#prod/productshortname"></ph> engine. In a separate process, use the <ph conref="wwdconrefs.dita#prod/productshortname"></ph> <codeph>ij</codeph> tool to load the <ph conref="wwdconrefs.dita#prod/productshortname"></ph> client driver and connect to the Server. Create a database called <i>seconddb</i> and
the table SECONDTABLE. Use a few basic SQL commands to insert and select data.
</dd>
</dlentry>
This automatically puts the activity number in bold and you only need to use paragraph tags if you need a second paragraph for the activity description.
If you want to use italic for things like the database name and the message log name you can. The most logical tag for an object name is filepath, but it doesn't display any format. The only other tag to display italic is varname, but this isn't really a variable. I often use codeph. Your choice, until we figure out the best tag and formatting :-)
File = twwdactivity1_Setup.dita
I don't think that the indexes here are helpful. If you want to hold off on changing this, we can do an "index blitz (probably early next year?) on all of the files. I intend to do one on the Ref Guide before the end of the year.
Is filesystem one word?
An overall design question... I usually see the step include the appropriate command example. The way that it is currently layed out, the steps are listed followed by an example of all of the commands together in a large table. So the user reads step 1 and thinks, okay what do I do now? I can't go to step 2 until I finish step 1. Is there a reason that you prefer this other arrangement?
There is a sentence just before the steps that I think should be changed:
Be sure to adjust these commands so that <ph conref="wwdconrefs.dita#prod/productinstallpath"></ph> indicates the location of the <ph conref="wwdconrefs.dita#prod/productshortname"></ph> installation on the system being used.
I think that we need to be more direct and change the phrase "on the system being used" to "on the system that you are using".
There should be periods at the end of each step.
File = twwdactivity1.dita
There is no shortdesc in this file and it seems odd to launch right into the steps. You can steal part of the shortdesc from the twwdactivity1_Setup.dita file. Here is the text that I would move to the twwdactivity1.dita file:
You will use the <ph conref="wwdconrefs.dita#prod/productshortname"></ph> embedded driver to create and connect to the database <i>firstdb</i>. You will also use a few basic SQL commands.
Try to avoid using the word "it", which isn't specific. You can see this especially in step 9. Is "it" referring to message or the error log file?
I think that the "Description of connection command" should be moved to the end of step 2. Also the tagging in the definition list is not what I am used to. It is my understanding that for each dl there is one dd. But you can next definition lists. Added a few words and changed the formatting in the following example. For example, I tend to use "quotation marks" instead of "quotes" for better translation and to avoid slang.
<dl>
<dlentry>
<dt>Description of connection command: <codeph>connect 'jdbc:derby:firstdb;create=true';</codeph></dt>
<dd>
<dl>
<dlentry>
<dt><codeph>connect</codeph></dt>
<dd>The <codeph>ij</codeph> command to establish a connection to a database.
The <ph conref="wwdconrefs.dita#prod/productshortname"></ph> connection URL
is enclosed in single quotation marks.</dd>
</dlentry>
<dlentry>
<dt><codeph>jdbc:derby:</codeph></dt>
<dd>The JDBC protocol specification for the <ph conref="wwdconrefs.dita#prod/productshortname"></ph> driver.</dd>
</dlentry>
<dlentry>
<dt><codeph>firstdb</codeph></dt>
<dd>The name of the database; this can be any string. Because no filepath
is specified, the database is created in the default working directory (<i>DERBYDBS</i>).</dd>
</dlentry>
<dlentry>
<dt><codeph>;create=true</codeph></dt>
<dd>The <ph conref="wwdconrefs.dita#prod/productshortname"></ph> <varname>URL
attribute</varname> used to create databases. <ph conref="wwdconrefs.dita#prod/productshortname"></ph> does
not have an SQL <codeph>create database</codeph> command.</dd>
</dlentry>
<dlentry>
<dt><codeph>;</codeph></dt>
<dd>The semicolon is the <codeph>ij</codeph> command terminator.</dd>
</dlentry>
</dl>
</dd>
</dlentry>
</dl>
File = twwdactivity2.dita
Again, I don't think that the indexes here are helpful.
Prereq tag includes this text "This activity assumes that you know how to..." and at then end talks about the env variable. I think that you might want to reword this last part since in an earlier part of this book they have set the variable. Maybe say something like "... directory, and have already set the <ph conref="wwdconrefs.dita#prod/productinstallpath"></ph> environment variable.
Try to avoid contractions like "we'll" and vague words like "them"
Step 9. It might be better to say "Select a subset of records from the table by specifying a WHERE clause."
File = twwdactivity3_Setup.dita
The shortdesc is really long. Can you move some of that to the context section?
Should the index term be "WwdEmbedded.java program" instead of just "WwdEmbedded.java" ?
In the IMPORTANT note, I would remove the word "Only" and add the acronym or use the acronym instead of spelling out the name (since I believe that it is mentioned in the Introduction?
File = twwdactivity3.dita
Same comment here about the index term "WwdEmbedded.java"
Define key variables and objects section has a ul that seems like it should be a dl. Do you typically use ul to introduce part of a syntax followed by a dash and the explanation?
Should the method names be in italic or monospace? We should probably decide on this an add it to the Doc FAQ or Guidelines Web page (because I know that I will forget :-)
File = twwdactivity4.dita
I think that shortdesc is long in this file too. Can you move some of that to the context section?
Should the index term be "WwdClient.java program" instead of just "WwdClient.java" ?
Steps - I don't think that you need to bold the text in the cmd tag. If you want to indicate that there are substeps, add the text "using the following steps:"
Try to avoid contractions like "we'll". Maybe reword to "Open a command window that we will use as the Client-Shell command window."
In the IMPORTANT note, I would remove the word "Only"
File = cwwdsummary.dita
In most of the writing that I do, we avoid the use of word "we". Is that true at SUN? If so, then there are several places that the text should be reworded.
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972-2-dita.zip, DERBY-1972-2.diff, DERBY-1972-2.zip, DERBY-1972.zip, DERBY_1972.diff
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=comments#action_12449451 ]
Laura Stewart commented on DERBY-1972:
--------------------------------------
I just realized that the diff file was for the Admin Guide & Dev Guide, not the Working with Derby.
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972.zip
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Resolved: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=all ]
Laura Stewart resolved DERBY-1972.
----------------------------------
Fix Version/s: 10.2.3.0
Resolution: Fixed
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Fix For: 10.2.3.0
>
> Attachments: DERBY-1747.diff, DERBY-1972-2-dita.zip, DERBY-1972-2.diff, DERBY-1972-2.zip, DERBY-1972-3-dita.zip, DERBY-1972-3.diff, DERBY-1972-3.zip, DERBY-1972-4-dita.zip, DERBY-1972-4.diff, DERBY-1972-4.zip, DERBY-1972.zip, DERBY_1972.diff
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=comments#action_12449449 ]
Laura Stewart commented on DERBY-1972:
--------------------------------------
When I downloaded the Diff file, it only had 3 files listed in it...
src/adminguide/cadminappsclientsecurity.dita
src/adminguide/cadminapps49914.dita
src/devguide/tdevcsecure82556.dita
Are these the only ones that you changed?
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972.zip
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=all ]
Kim Haase updated DERBY-1972:
-----------------------------
Derby Info: [Patch Available]
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972.zip
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=comments#action_12455773 ]
Kim Haase commented on DERBY-1972:
----------------------------------
Thank you, Laura! You have gone way beyond what I did and found things I had not noticed or known how to deal with, including things in the original version that I had just left as is because I was making so many other changes. To most of what you say my answer is just Yes! I'll make those fixes. I'm glad you looked at the index entries, for example; since they don't yet show up in the output, I have been ignoring them.
You've also raised a bunch of interesting philosophical issues about DITA. I guess I was somewhat narrowly focused on using DITA "properly," that is on using tagging for semantic purposes (to the extent the somewhat buggy toolkit would allow). Whereas another major goal to keep in mind, as you point out, is usability by a large community whose main goal is to fix content and not to have to worry too much about tagging.
Hence the answers to some of the questions you raise:
Why <pre>? Well, according to the DITA spec, <codeblock> is a programming element meant just for "lines of program code," whereas <pre> -- which is familiar to those who know HTML -- is for any other kind of preformatted text, such as command input and output. However, DITA really violates its own rules, because it allows all sorts of things inside a codeblock that are not normally part of program code: in fact, everything that's allowed inside <pre> is also allowed inside <codeblock> and vice versa. So what the heck. You've convinced me. We've been using <codeblock>, so let's stick with it.
Similarly I was using <userinput> and <systemoutput> semantically. The DTD we use at Sun has <userinput> so I was used to it. But if our goal is simplicity there is really no need for these.
There was also some weird stuff about certain formatting tags within codeblocks getting munged (the toolkit ignoring spaces between them). I think whatever tags I used solved that problem; I'll have to experiment to find what else works.
You also raise some good points about our doc conventions (the ones in the Getting Started manual). There are really a couple of separate issues -- what we want certain things to look like, and how to do that with the toolkit (the current one anyway; I haven't had time to try the new one).
Speaking of the toolkit, the first thing you noticed -- "PDF copyright (page 4) appears run together" -- has been the case for all the docs since 10.1 I think. You mean the fact that the string "Apache Software FoundationWorking With DerbyApache Derby" is all stuck together in both the PDF and the monohtml version, I think? If this is not already a JIRA issue we should make it one, and if it is maybe we should raise its priority.
I think the contribution line and the rev attributes must date from when the files were first checked in. I had not thought about them, but I guess none of our other books use them. It probably makes sense to remove those.
I am not clear exactly what you mean by "the way that the text in the steps runs together" -- could you clarify that? There are at least two problems of that nature: vertical spacing in the HTML; and the fact that in the PDF and monohtml, the toolkit removes any space between the output of a <ph> (like "Derby") and anything before or after it that is not in plain text font. Possibly others!
Re doc conventions -- I used italics for the database names because they are "dictionary objects" (not a term I'm used to, but I looked it up) and for the message log because it is a file. I would like to use <filepath> for files and directories, but as you say, the toolkit doesn't provide any formatting for this tag. Same with <cmdname> for commands -- it would be very handy, but if you use it, there's no formatting for it. We can file a bug after we decide what format we want.
Also you asked about method names. They seem to be in italics in other books -- for example, in the JDBC material in the Reference Manual. I am used to monospace for method names and for all other programming terms. And I'm also used to monospace (<codeph>) for files, directories, database names, commands and, in fact, most of the things that the doc conventions specify italics for. The only things I'm used to italics for are new terms, emphasis, book titles, and placeholders to be replaced with a real name or value (what we use <varname> for).
However, though the typographic conventions in Getting Started seem strange to me, I'm willing to adopt them if I can figure out the principle behind them. The latest theory I have come up with is that every programming or database term in body text that isn't in all caps (like environment variables and SQL commands) is supposed to be in italics -- whereas I'm used to those things being in monospace (even the all-caps ones). There's some inconsistency in the docs, so I'm not sure this principle really works, but it's the best I can come up with. Do you have any idea of the history behind the current conventions -- do they come from IBM, or Informix, or Cloudscape before it was bought?
If we stick with that principle, then we can ask for <filepath> and <cmdname> to be output in italics, and I can fix command names and attributes and whatnot in the Working With Derby book to be in italics too.
In the meantime, I'll work on these fixes. Thanks again!
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972-2-dita.zip, DERBY-1972-2.diff, DERBY-1972-2.zip, DERBY-1972.zip, DERBY_1972.diff
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=all ]
Kim Haase updated DERBY-1972:
-----------------------------
Attachment: DERBY-1972-3.diff
DERBY-1972-3.zip
DERBY-1972-3-dita.zip
I think I've incorporated all your comments, Laura, and taken advantage of Andrew's fix and advice for DERBY-408. I've attached DERBY-1972-3.diff, which contains the diffs; DERBY-1972-3.zip, which contains the output files; and DERBY-1972-3-dita.zip, which contains the DITA source. Please let me know if any additional fixes are needed. Thanks again!
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972-2-dita.zip, DERBY-1972-2.diff, DERBY-1972-2.zip, DERBY-1972-3-dita.zip, DERBY-1972-3.diff, DERBY-1972-3.zip, DERBY-1972.zip, DERBY_1972.diff
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=comments#action_12455374 ]
Laura Stewart commented on DERBY-1972:
--------------------------------------
Hi Kim -
I started to review all of your changed, but I am having a really hard time reviewing the diff file and understanding the tagging that you used. Can you please attache a zip of the dita files? I can then use the HTML and PDF files that you have already attached to review the changes more quickly.
Thanks!
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972-2.diff, DERBY-1972-2.zip, DERBY-1972.zip, DERBY_1972.diff
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=comments#action_12455792 ]
Laura Stewart commented on DERBY-1972:
--------------------------------------
Hi Kim -
Re doc conventions. I think that we should not tie ourselves to what was done before. I say that because it is my understanding that the library of docs is a mis-mash of conventions from the companies that you named and from contributors who didn't have any guidelines to go by and used what was seen in other parts of the documentation. I want us to see the new conventions and (over time) implement them as we can.
So for tags that are in DITA like filepath and cmdname, which currently don't have any formatting from the toolkit, I think that we should decide what the format should be an figure out how to change the xsl files.
Like you, I am used to using italic for just a few limited things - the very ones that you mentioned :-) And monospace (aka codeph) for lots of other things.
So, how about you implement what seems reasonable from my comments and lets start a discussion on the list about the formatting conventions that we do want to use.
And if I have convinced you to use codeblock for non-code stuff, then you have convinced me to use userinput and systemoutput (although I think we can set the bold for the format for userinput thus eliminating the need to apply both bold and userinput !
I don't know XSL and have a few other things on my plate for the remainder of this year, but for early next year I want to start learning it so that when we agree on a format change, we can implement it. One of the things that I need to do this year is look at the new toolkit to see if it implements any new formats for us :-)
Thanks Kim !
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972-2-dita.zip, DERBY-1972-2.diff, DERBY-1972-2.zip, DERBY-1972.zip, DERBY_1972.diff
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=comments#action_12459396 ]
Kim Haase commented on DERBY-1972:
----------------------------------
Thank you, Laura!
Believe it or not, after I submitted that last patch I ran through all the steps in the manual again and discovered some more errors (mostly output spacing, and one problem with step order). I will file a new issue for those. The diffs should be easier to deal with.
IIRC, the > occurs only in the PDF/monohtml output; the HTML prefaces the word "Important" to the note. Yes, let's check the new toolkit.
You can mark this resolved now, and then I'll close it. Thanks again.
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972-2-dita.zip, DERBY-1972-2.diff, DERBY-1972-2.zip, DERBY-1972-3-dita.zip, DERBY-1972-3.diff, DERBY-1972-3.zip, DERBY-1972-4-dita.zip, DERBY-1972-4.diff, DERBY-1972-4.zip, DERBY-1972.zip, DERBY_1972.diff
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=all ]
Kim Haase updated DERBY-1972:
-----------------------------
Attachment: DERBY-1972-4-dita.zip
DERBY-1972-4.diff
DERBY-1972-4.zip
My apologies. I realized one more problem. The client/server examples show output that has a Derby version (10.2.1.6) and tag hardcoded in them. (This means they are out of date for 10.2.2, but this is not worth fixing, I think.) These and other output examples also have a date from this past fall hardcoded in them, which is also obsolete and would be a nuisance to maintain.
So I've replaced these with <varname> tags specifying version, tag, and date. This affects all the twwdactivity files except for twwdactivity1_Setup.dita. I'm attaching DERBY-1972-4.diff, DERBY-1972-4-dita.zip (without the .svn files that accidentally got in there last time), and DERBY-1972-4.zip. Let me know if this seems like a reasonable solution.
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972-2-dita.zip, DERBY-1972-2.diff, DERBY-1972-2.zip, DERBY-1972-3-dita.zip, DERBY-1972-3.diff, DERBY-1972-3.zip, DERBY-1972-4-dita.zip, DERBY-1972-4.diff, DERBY-1972-4.zip, DERBY-1972.zip, DERBY_1972.diff
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=comments#action_12455402 ]
Laura Stewart commented on DERBY-1972:
--------------------------------------
Sorry, I inadvertantly pressed enter which added the comment before I was finished. I'll post all of my comments when I am finished reviewing the files.
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972-2-dita.zip, DERBY-1972-2.diff, DERBY-1972-2.zip, DERBY-1972.zip, DERBY_1972.diff
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=comments#action_12456569 ]
Kim Haase commented on DERBY-1972:
----------------------------------
Now I remember why I used <pre> instead of <codeblock> when according to the DITA spec they work identically. The reason is that with our toolkit, they don't.
If I use <codeblock> for multi-line output that contains line breaks between tags, the toolkit ignores the line breaks when generating monohtml and PDF output. If I use <pre>, the line breaks are preserved.
Tags followed by plain text are fine. For example, the following results in preserved line breaks:
<codeblock>
<b><userinput>java MyProgram</userinput></b>
program output
</codeblock>
But the following does not:
<codeblock>
<b><userinput>java MyProgram</userinput></b>
<systemoutput>program output</systemoutput>
</codeblock>
I've looked in the xsl files and the generated monohtml source and I can't figure out why this happens. But it definitely does. It's a bug, but until it's fixed we should either use <pre> if we want to preserve line breaks, or else use plain text instead of <systemoutput> to indicate system output. Do you have a preference?
I suspect this is the same bug that results in consecutive tags in plain text being munged together in the monohtml and PDF. For example, if you want to talk about the Derby ij tool, and you use the usual <ph> tag for Derby and then enclose "ij" in a <codeph> --
<ph conref="wwdconrefs.dita#prod/productshortname"></ph> <codeph>ij</codeph>
The processor removes the space between </ph> and <codeph>, resulting in "Derbyij".
I reopened DERBY-408 to describe this problem back in October, but it has not been dealt with.
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
> Attachments: DERBY-1747.diff, DERBY-1972-2-dita.zip, DERBY-1972-2.diff, DERBY-1972-2.zip, DERBY-1972.zip, DERBY_1972.diff
>
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-1972) Working With Derby needs some
formatting fixes and other minor cleanup
Posted by "Kim Haase (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-1972?page=comments#action_12443321 ]
Kim Haase commented on DERBY-1972:
----------------------------------
Those are great suggestions, Laura -- thanks. I hadn't gotten around to researching this problem yet, so you've saved me some work!
> Working With Derby needs some formatting fixes and other minor cleanup
> ----------------------------------------------------------------------
>
> Key: DERBY-1972
> URL: http://issues.apache.org/jira/browse/DERBY-1972
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Kim Haase
> Assigned To: Kim Haase
> Priority: Minor
>
> The Working With Derby book uses DITA tags in ways that are not always consistent with the usage in other books and that lead to some problems in the processed output. Some examples are the use of the <varname> tag in inappropriate places and the use of formatting tags within <codeblock> tags.
> There are also a few minor punctuation and syntax issues worth fixing.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira