[doc] Derby DITA documentation source DTD declarations

[Jeff Levitt <de...@mylevita.com>]

Hi all,

I noticed that in the DITA doc source files that we
have DTD declarations at the top that look like this:

<!DOCTYPE reference PUBLIC "-//IBM//DTD DITA
Reference//EN"
 "../dtd/reference.dtd">

Note that the declarations have the word "IBM" in
them.  This is because they are based on an old DTD
that DITA used before it was contributed to the open
source OASIS foundation.  Currently, the correct OASIS
DTD declaration looks like this:

<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA
Reference//EN"
 "reference.dtd">

While I dont see any problems with the old IBM
declaration right now, we will miss out on features in
the future if we dont migrate to the new OASIS
declaration.  We could do a search and replace, but
we'd have to be sure to do it correctly.  I dont think
this is a crucial requirement right now, so
alternatively I suggest that as doc contributors
submit patches to doc code, they should change the
declaration to the files they change as they go.  It
wont hurt anything to have different DTD declarations
in different files, and this solution allows us to
continue to work on the files without having to commit
time and resources to a migration.

If no one has any problems with this, I'll begin
submitting patches with the new declaration.  Also, is
there some place we can make this directive
moreprominent so future contributors will see it?  Any
suggestions?

Of course, if someone wants to make a script that
fixes the problem, that's alright too.  It would
require changing the word "IBM" in the declaration to
"OASIS", and the "../" before the concept.dtd,
reference.dtd, and task.dtd to be removed.

Jeff

Re: [doc] Derby DITA documentation source DTD declarations

[scott hutinger <S-...@wiu.edu>]

BTW, I started looking at the DITA-OT 1.2 beta, which has some hooks in 
it to make life a bit easier.  I didn't get very far in looking at it 
yet; but think Jeff must know that 1.2 should have the different 
declarations.  I'll continue to investigate the changes to OT1.2 etc...

scott

Jean T. Anderson wrote:
> Jeff Levitt wrote:
>   
>> Hi all,
>>
>> I noticed that in the DITA doc source files that we
>> have DTD declarations at the top that look like this:
>>
>> <!DOCTYPE reference PUBLIC "-//IBM//DTD DITA
>> Reference//EN"
>>  "../dtd/reference.dtd">
>>
>> Note that the declarations have the word "IBM" in
>> them.  This is because they are based on an old DTD
>> that DITA used before it was contributed to the open
>> source OASIS foundation.  Currently, the correct OASIS
>> DTD declaration looks like this:
>>
>> <!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA
>> Reference//EN"
>>  "reference.dtd">
>>
>> While I dont see any problems with the old IBM
>> declaration right now, we will miss out on features in
>> the future if we dont migrate to the new OASIS
>> declaration.  We could do a search and replace, but
>> we'd have to be sure to do it correctly.  I dont think
>> this is a crucial requirement right now, so
>> alternatively I suggest that as doc contributors
>> submit patches to doc code, they should change the
>> declaration to the files they change as they go.  It
>> wont hurt anything to have different DTD declarations
>> in different files, and this solution allows us to
>> continue to work on the files without having to commit
>> time and resources to a migration.
>>     
>
> I think the phased "change as you go" approach you suggest is fine.
>
>   
>> If no one has any problems with this, I'll begin
>> submitting patches with the new declaration.  Also, is
>> there some place we can make this directive
>> moreprominent so future contributors will see it?  Any
>> suggestions?
>>     
>
> how about documenting it here?
>
>    http://db.apache.org/derby/manuals/dita.html
>
> If you want to provide a patch for that page, I'll be happy to apply it.
>
> -jean
>
>
>   
>> Of course, if someone wants to make a script that
>> fixes the problem, that's alright too.  It would
>> require changing the word "IBM" in the declaration to
>> "OASIS", and the "../" before the concept.dtd,
>> reference.dtd, and task.dtd to be removed.
>>
>> Jeff
>>
>>
>>     
>
>   

Re: [doc] Derby DITA documentation source DTD declarations

["Jean T. Anderson" <jt...@bristowhill.com>]

Jeff Levitt wrote:
> Hi all,
> 
> I noticed that in the DITA doc source files that we
> have DTD declarations at the top that look like this:
> 
> <!DOCTYPE reference PUBLIC "-//IBM//DTD DITA
> Reference//EN"
>  "../dtd/reference.dtd">
> 
> Note that the declarations have the word "IBM" in
> them.  This is because they are based on an old DTD
> that DITA used before it was contributed to the open
> source OASIS foundation.  Currently, the correct OASIS
> DTD declaration looks like this:
> 
> <!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA
> Reference//EN"
>  "reference.dtd">
> 
> While I dont see any problems with the old IBM
> declaration right now, we will miss out on features in
> the future if we dont migrate to the new OASIS
> declaration.  We could do a search and replace, but
> we'd have to be sure to do it correctly.  I dont think
> this is a crucial requirement right now, so
> alternatively I suggest that as doc contributors
> submit patches to doc code, they should change the
> declaration to the files they change as they go.  It
> wont hurt anything to have different DTD declarations
> in different files, and this solution allows us to
> continue to work on the files without having to commit
> time and resources to a migration.

I think the phased "change as you go" approach you suggest is fine.

> If no one has any problems with this, I'll begin
> submitting patches with the new declaration.  Also, is
> there some place we can make this directive
> moreprominent so future contributors will see it?  Any
> suggestions?

how about documenting it here?

   http://db.apache.org/derby/manuals/dita.html

If you want to provide a patch for that page, I'll be happy to apply it.

-jean


> Of course, if someone wants to make a script that
> fixes the problem, that's alright too.  It would
> require changing the word "IBM" in the declaration to
> "OASIS", and the "../" before the concept.dtd,
> reference.dtd, and task.dtd to be removed.
> 
> Jeff
> 
> 

Re: [doc] Derby DITA documentation source DTD declarations

[Jeff Levitt <de...@mylevita.com>]

--- Jeff Levitt <de...@mylevita.com> wrote:

> 
> Of course, if someone wants to make a script that
> fixes the problem, that's alright too.  It would
> require changing the word "IBM" in the declaration
> to
> "OASIS", and the "../" before the concept.dtd,
> reference.dtd, and task.dtd to be removed.
> 
> Jeff
> 


Ooops, what I meant to say is that "../dtd/" would
have to be removed, not just "../"