db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Laura Stewart (JIRA)" <j...@apache.org>
Subject [jira] Commented: (DERBY-1972) Working With Derby needs some formatting fixes and other minor cleanup
Date Tue, 05 Dec 2006 23:01:23 GMT
    [ 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:
>            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


View raw message