[jira] Updated: (DERBY-1972) Working With Derby needs some formatting fixes and other minor cleanup

["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