[web/doc] Accessing DTDs locally vs. externally -- summary of Derby IRC chat

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

There was a lengthy discussion on infrastructure@a.o that I'll summarize
succinctly as:

1) Somebody requested a centralized location for Apache DTDs.
2) The request was turned down because of the load that resolving DTDs
puts on Apache resources; DTDs should be accessed locally.

Andrew and I chatted about this on IRC today because I've been confused
about what kinds of operations this applies to and how to best address them.

I have actually been vaguely aware of the issue since ApacheCon Europe
when David Crossley (Forrest) mentioned that people using tools to edit
forrest XML files should not be connecting to forrest.apache.org to
resolve the DTDs.  Since my XML editor is vi (and does no XML
validation, for good or ill), I let this issue move to the background;
however, I have been vaguely aware that every time I build the Derby web
site it does in fact get the DTDs from forrest.apache.org. And after the
discussion on the infrastructure list I realize that I do need to change
this.

So, to cut to the chase ...

The Derby DITA doc builds are set up so that when you run ant to build
the docs ( see http://db.apache.org/derby/manuals/dita.html for
details), ant copies the DTDs from the DITA Toolkit into src/dtd in the
Derby doc repo. The DITA files then include the appropriate DTD with a
local, relative reference ("../dtd/concept.dtd", "../dtd/reference.dtd",
or "../dtd/task.dtd")

I logged DERBY-1199 to fix the Derby web site source. Andrew and I
discussed a strategy similar to the DITA one: simply commit the forrest
DTDs to the Derby web site repo and put relative references in the XML
files. I'm also looking into a link that Crossley posted to infra
(http://forrest.apache.org/docs/catalog.html) to see if I can use an
entity resolver for the build itself (as opposed to for editing tools),
and if this can be done in a way that is super easy for other Derby web
site builders. I'm still spinning up on the technical considerations and
solutions.

 -jean

Re: [web/doc] Accessing DTDs locally vs. externally -- summary of Derby IRC chat

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

Stanley Bradbury wrote:
> Jean T. Anderson wrote:
> 
>> There was a lengthy discussion on infrastructure@a.o that I'll summarize
>> succinctly as:
>>
>> 1) Somebody requested a centralized location for Apache DTDs.
>> 2) The request was turned down because of the load that resolving DTDs
>> puts on Apache resources; DTDs should be accessed locally.
>> ...
>> The Derby DITA doc builds are set up so that when you run ant to build
>> the docs ( see http://db.apache.org/derby/manuals/dita.html for
>> details), ant copies the DTDs from the DITA Toolkit into src/dtd in the
>> Derby doc repo. The DITA files then include the appropriate DTD with a
>> local, relative reference ("../dtd/concept.dtd", "../dtd/reference.dtd",
>> or "../dtd/task.dtd")
>> ...
> Thanks Jean -
> I've been using the wrong reference in my DITA source files.   I will
> update the references in the Dita Source files for the Working With
> Derby document.  You've saved me some problems down the line.  : ) 

Just in case I confused anyone, the DITA DTDs aren't at Apache so
wouldn't be resolved there, but it's still a good practice to resolve
them locally. Derby DITA doc source is doing things correctly, and I'll
catch up the web site source with DERBY-1199.

-jean

Re: [web/doc] Accessing DTDs locally vs. externally -- summary of Derby IRC chat

[Stanley Bradbury <St...@gmail.com>]

Jean T. Anderson wrote:

>There was a lengthy discussion on infrastructure@a.o that I'll summarize
>succinctly as:
>
>1) Somebody requested a centralized location for Apache DTDs.
>2) The request was turned down because of the load that resolving DTDs
>puts on Apache resources; DTDs should be accessed locally.
>
>Andrew and I chatted about this on IRC today because I've been confused
>about what kinds of operations this applies to and how to best address them.
>
>I have actually been vaguely aware of the issue since ApacheCon Europe
>when David Crossley (Forrest) mentioned that people using tools to edit
>forrest XML files should not be connecting to forrest.apache.org to
>resolve the DTDs.  Since my XML editor is vi (and does no XML
>validation, for good or ill), I let this issue move to the background;
>however, I have been vaguely aware that every time I build the Derby web
>site it does in fact get the DTDs from forrest.apache.org. And after the
>discussion on the infrastructure list I realize that I do need to change
>this.
>
>So, to cut to the chase ...
>
>The Derby DITA doc builds are set up so that when you run ant to build
>the docs ( see http://db.apache.org/derby/manuals/dita.html for
>details), ant copies the DTDs from the DITA Toolkit into src/dtd in the
>Derby doc repo. The DITA files then include the appropriate DTD with a
>local, relative reference ("../dtd/concept.dtd", "../dtd/reference.dtd",
>or "../dtd/task.dtd")
>
>I logged DERBY-1199 to fix the Derby web site source. Andrew and I
>discussed a strategy similar to the DITA one: simply commit the forrest
>DTDs to the Derby web site repo and put relative references in the XML
>files. I'm also looking into a link that Crossley posted to infra
>(http://forrest.apache.org/docs/catalog.html) to see if I can use an
>entity resolver for the build itself (as opposed to for editing tools),
>and if this can be done in a way that is super easy for other Derby web
>site builders. I'm still spinning up on the technical considerations and
>solutions.
>
> -jean
>
>
>
>
>  
>
Thanks Jean -
I've been using the wrong reference in my DITA source files.   I will 
update the references in the Dita Source files for the Working With 
Derby document.  You've saved me some problems down the line.  : )

Re: [web/doc] Accessing DTDs locally vs. externally -- summary of Derby IRC chat

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

Jean T. Anderson wrote:
...
> I have been vaguely aware that every time I build the Derby web
> site it does in fact get the DTDs from forrest.apache.org. And after the
> discussion on the infrastructure list I realize that I do need to change
> this.

No, I'm wrong about this; building the web site is not an issue.
'forrest site' (and 'forrest run') resolve the DTDs from local copies
under FORREST_HOME. http://forrest.apache.org/docs_0_70/catalog.html says:

"When Forrest processes the documents, it uses the Resolver to find
Forrest's local copies of the DTDs, rather than trundling out onto the
network."

A search of the forrest mail list archives yielded a clarifying Crossley
tid bit in
http://mail-archives.apache.org/mod_mbox/forrest-user/200410.mbox/%3C1098058268.4210.31581.camel@ighp%3E

"If you call 'forrest' with its own shell script, then it uses its own
packaged Ant and the supporting catalog entity resolver."

The only issue is using non-forrest tools. For Derby this is most likely
editing Derby XML source with tools that perform validation. Those tools
need to be configured to use a catalog entity resolver per the
instructions in http://forrest.apache.org/docs_0_70/catalog.html .

I believe that no changes to the Derby source are needed. All that is
needed is a note in http://db.apache.org/derby/papers/derby_web.html .

Any disagreement?

thanks,

 -jean