New way of adding internationalized messages. This affects the Derby Reference Guide.

[Rick Hillegas <Ri...@Sun.COM>]

My last checkin (469975, DERBY-1868) changed the way that we add 
internationalized messages to the Derby engine. There is now a file of 
xml descriptors (java/engine/org/apache/derby/loc/messages.xml). This is 
where we should add new engine messages. As part of adding a new 
message, you will want to give friendly names to the message 
arguments--these friendly names will appear in the SQLState tables in 
the Derby Reference Guide.

Please do not edit java/engine/apache/derby/loc/messages.xml. This file 
has been removed from code management and is now generated from 
messages.xml during the Derby build.

Thanks,
-Rick

Re: New way of adding internationalized messages. This affects the Derby Reference Guide.

[Laura Stewart <sc...@gmail.com>]

On 11/3/06, Rick Hillegas <Ri...@sun.com> wrote:
> Thanks, Laura. This looks great. I have added a sentence to messages.xml
> which directs message writers to your web page for guidance.
>

Thanks!

I will also add examples of "good" and "bad" messages to help guide
people when they write new messages.

-- 
Laura Stewart

Re: New way of adding internationalized messages. This affects the Derby Reference Guide.

[Rick Hillegas <Ri...@Sun.COM>]

Laura Stewart wrote:
> On 11/1/06, Rick Hillegas <Ri...@sun.com> wrote:
>> Hi Laura,
>>
>> If I understand you correctly, it sounds like you would like to create a
>> website page which gives people stylistic advice on how to write clear,
>> meaningful messages and how to name the arguments plugged into those
>> messages. Then messages.xml could have a prominent header comment
>> directing message writers to the website for style tips. I think that's
>> a great idea.
>>
>> Right now, messages.xml does not have such a header comment.
>>
>> Unfortunately, messages.xml lives in the code repository while the
>> documentation lives in the doc repository. It sound like you have only
>> checked out the doc repository--that would be why you can't find
>> messages.xml.
>>
>> Regards,
>> -Rick
>>
>>
>
> Hi Rick -
> I created this page on the Derby Documentation site
> http://db.apache.org/derby/manuals/messages.html
>
> please let me know if the content is acceptable and if there is
> anything else that you think needs to be added.
>
>
Thanks, Laura. This looks great. I have added a sentence to messages.xml 
which directs message writers to your web page for guidance.

Re: New way of adding internationalized messages. This affects the Derby Reference Guide.

[Laura Stewart <sc...@gmail.com>]

On 11/1/06, Rick Hillegas <Ri...@sun.com> wrote:
> Hi Laura,
>
> If I understand you correctly, it sounds like you would like to create a
> website page which gives people stylistic advice on how to write clear,
> meaningful messages and how to name the arguments plugged into those
> messages. Then messages.xml could have a prominent header comment
> directing message writers to the website for style tips. I think that's
> a great idea.
>
> Right now, messages.xml does not have such a header comment.
>
> Unfortunately, messages.xml lives in the code repository while the
> documentation lives in the doc repository. It sound like you have only
> checked out the doc repository--that would be why you can't find
> messages.xml.
>
> Regards,
> -Rick
>
>

Hi Rick -
I created this page on the Derby Documentation site
http://db.apache.org/derby/manuals/messages.html

please let me know if the content is acceptable and if there is
anything else that you think needs to be added.


-- 
Laura Stewart

Re: New way of adding internationalized messages. This affects the Derby Reference Guide.

[Rick Hillegas <Ri...@Sun.COM>]

Laura Stewart wrote:
> On 11/1/06, Rick Hillegas <Ri...@sun.com> wrote:
>> Hi Laura,
>>
>> Right now, the friendly names are exactly the ones which you created
>> when you overhauled rrefexcept71493.dita recently. Those argument names
>> have been copied to messages.xml. When adding a new message, one should
>> just look for examples in messages.xml. Here are some of the friendly
>> argument names in messages.xml which you added and which I faithfully
>> reproduced. I culled these names by searching that file for the first
>> several occurrences of the <arg> tag:
>>
>> authorizationID
>> constraintName
>> tableName
>> viewName
>> triggerName
>> columnName
>> indexName
>> valueName
>> objectName
>> databaseName
>>
>> Do you think that we should document these somewhere? For instance, is
>> there some style advice which you would like me to add to the
>> introductory comments in messages.xml?
>>
>> Thanks,
>> -Rick
>>
>>
>
> Hmmm, right now I am creating new content for the Documentation tab of
> the Derby Web pages.  I think it might be good to add new sub-page
> about messages.  I currently don't have access to the messages.xml
> file. Are there already some intro comments in that file?  If yes,
> then perhaps we can use that and point people to the Web page...
> ensuring the content is the same in both places.  If there isn't then
> we can add some info to the Web page and whenever this comes up on the
> list we can point people to that page.
>
> What do you think?
>
Hi Laura,

If I understand you correctly, it sounds like you would like to create a 
website page which gives people stylistic advice on how to write clear, 
meaningful messages and how to name the arguments plugged into those 
messages. Then messages.xml could have a prominent header comment 
directing message writers to the website for style tips. I think that's 
a great idea.

Right now, messages.xml does not have such a header comment.

Unfortunately, messages.xml lives in the code repository while the 
documentation lives in the doc repository. It sound like you have only 
checked out the doc repository--that would be why you can't find 
messages.xml.

Regards,
-Rick

Re: New way of adding internationalized messages. This affects the Derby Reference Guide.

[Laura Stewart <sc...@gmail.com>]

On 11/1/06, Rick Hillegas <Ri...@sun.com> wrote:
> Hi Laura,
>
> Right now, the friendly names are exactly the ones which you created
> when you overhauled rrefexcept71493.dita recently. Those argument names
> have been copied to messages.xml. When adding a new message, one should
> just look for examples in messages.xml. Here are some of the friendly
> argument names in messages.xml which you added and which I faithfully
> reproduced. I culled these names by searching that file for the first
> several occurrences of the <arg> tag:
>
> authorizationID
> constraintName
> tableName
> viewName
> triggerName
> columnName
> indexName
> valueName
> objectName
> databaseName
>
> Do you think that we should document these somewhere? For instance, is
> there some style advice which you would like me to add to the
> introductory comments in messages.xml?
>
> Thanks,
> -Rick
>
>

Hmmm, right now I am creating new content for the Documentation tab of
the Derby Web pages.  I think it might be good to add new sub-page
about messages.  I currently don't have access to the messages.xml
file. Are there already some intro comments in that file?  If yes,
then perhaps we can use that and point people to the Web page...
ensuring the content is the same in both places.  If there isn't then
we can add some info to the Web page and whenever this comes up on the
list we can point people to that page.

What do you think?

-- 
Laura Stewart

Re: New way of adding internationalized messages. This affects the Derby Reference Guide.

[Rick Hillegas <Ri...@Sun.COM>]

Laura Stewart wrote:
> On 11/1/06, Rick Hillegas <Ri...@sun.com> wrote:
>> My last checkin (469975, DERBY-1868) changed the way that we add
>> internationalized messages to the Derby engine. There is now a file of
>> xml descriptors (java/engine/org/apache/derby/loc/messages.xml). This is
>> where we should add new engine messages. As part of adding a new
>> message, you will want to give friendly names to the message
>> arguments--these friendly names will appear in the SQLState tables in
>> the Derby Reference Guide.
>>
>> Please do not edit java/engine/apache/derby/loc/messages.xml. This file
>> has been removed from code management and is now generated from
>> messages.xml during the Derby build.
>>
>> Thanks,
>> -Rick
>>
>
> Rick - Can you give the Derby community a few examples of "friendly 
> names" ?
Hi Laura,

Right now, the friendly names are exactly the ones which you created 
when you overhauled rrefexcept71493.dita recently. Those argument names 
have been copied to messages.xml. When adding a new message, one should 
just look for examples in messages.xml. Here are some of the friendly 
argument names in messages.xml which you added and which I faithfully 
reproduced. I culled these names by searching that file for the first 
several occurrences of the <arg> tag:

authorizationID
constraintName
tableName
viewName
triggerName
columnName
indexName
valueName
objectName
databaseName

Do you think that we should document these somewhere? For instance, is 
there some style advice which you would like me to add to the 
introductory comments in messages.xml?

Thanks,
-Rick

Re: New way of adding internationalized messages. This affects the Derby Reference Guide.

[Laura Stewart <sc...@gmail.com>]

On 11/1/06, Rick Hillegas <Ri...@sun.com> wrote:
> My last checkin (469975, DERBY-1868) changed the way that we add
> internationalized messages to the Derby engine. There is now a file of
> xml descriptors (java/engine/org/apache/derby/loc/messages.xml). This is
> where we should add new engine messages. As part of adding a new
> message, you will want to give friendly names to the message
> arguments--these friendly names will appear in the SQLState tables in
> the Derby Reference Guide.
>
> Please do not edit java/engine/apache/derby/loc/messages.xml. This file
> has been removed from code management and is now generated from
> messages.xml during the Derby build.
>
> Thanks,
> -Rick
>

Rick - Can you give the Derby community a few examples of "friendly names" ?
-- 
Laura Stewart