db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Kim Haase (JIRA)" <j...@apache.org>
Subject [jira] Updated: (DERBY-1972) Working With Derby needs some formatting fixes and other minor cleanup
Date Mon, 06 Nov 2006 20:31:39 GMT
     [ http://issues.apache.org/jira/browse/DERBY-1972?page=all ]

Kim Haase updated DERBY-1972:

    Attachment: DERBY-1747.diff

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


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)


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

Removed unnecessary quotation marks

Used capitalization and lowercase consistently

Used terms consistently (used the same word to mean the same thing throughout)


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


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:
>            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


View raw message