You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Keiron Liddle <ke...@aftexsw.com> on 2002/12/11 10:28:36 UTC
RE: src/documentation/README
On Tue, 2002-12-10 at 19:17, Victor Mote wrote:
> OK, I see now that I misunderstood your "Sorry, yes" answer to Keiron. If
> http://forrestbot.cocoondev.org/site/xml-fop should be reflecting changes no
> more than an hour old made to xml-fop/src/documentation, then it is not
> working. I just looked for changes that were made about 24 hours ago, and
> they are not there. Also, as I mentioned, it shows a publish date of 12-7.
> So I suspect that something is not working. We have one document with a
> non-standard DTD (my fault, in fact that is what I am trying to work on)
> that might be messing up the flow. How do I go about troubleshooting this?
Judging by the log it might be a DISPLAY problem.
The compliance doc should only cause a broken link.
Who is in charge of the cocoondev site, could they work out what the
problem is?
> > I think Sam Ruby has a script which automatically updates the live site
> > to the contents of xml-site/targets/*.
>
> Should I contact him directly? Also, I still don't know whether
> xml-site/targets/fop is my final destination. What is best practices for
> this process? If this is documented somewhere, please excuse me -- I haven't
> found it yet. Also, I realize that this conversation might be better on
> forrest-dev. I asked on this list because I think Keiron has already figured
> most of this out & I am trying to leverage off of that. Thanks very much for
> your help.
Haven't figured out all of it.
There is no real documentation for the old process, currently we are
only really replacing the doc generation process.
Re: dtd catalog (was: src/documentation/README)
Posted by Jeff Turner <je...@apache.org>.
On Wed, Dec 11, 2002 at 12:59:03PM -0700, Victor Mote wrote:
> Peter B. West wrote:
>
> > I'm still floundering around here, but when I found 'catalog' in
> > .../documentation/resources/schema, and the dtd in .../schema/dtd, I
> > began to see a ray of light. It seems to me that such a setup should be
> > used for all of the DOCTYPE delcarations in the documentation tree. At
> > the moment we are relying on the system identifier component of the
> > DOCTYPE declaration, and that is indicating a CVS retrieval - some from
> > the xml-forrest base, some from xml-cocoon2, last time I looked.
>
> The way this works is that your validation software has to know how to find
> the catalog. If it does, then the catalog can contain mappings from the
> PUBLIC IDs in the DOCTYPE declaration to a local physical file. That setup
> is already in all of our documents. For example, our resources.xml file
> contains the following DOCTYPE:
>
> <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
>
> "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/sche
> ma/dtd/document-v11.dtd">
>
> Your catalog has to know how to map "-//APACHE//DTD Documentation V1.1//EN"
> to "/u/xml-schema/document-v11.dtd" or whatever your local file is.
FTR, Forrest has a built-in catalog, so the SYSTEM id of docs processed
by Forrest will be ignored.
If FOP has any DTDs not included in Forrest, then these can be added to
src/documentation/resources/schema/dtd, and a project-specific catalog
added. This process is documented at
http://xml.apache.org/forrest/validation.html
> It seems to me that we have this set up as well as it can be
Looks like it.
--Jeff
> but I sure could be missing something.
>
> Victor Mote
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
Re: Ant-based local doc valiation
Posted by Jeff Turner <je...@apache.org>.
On Thu, Dec 12, 2002 at 04:54:03PM +0100, Keiron Liddle wrote:
> On Thu, 2002-12-12 at 16:16, Jeff Turner wrote:
> > Yes. There is nothing wrong with FOP grabbing the latest DTDs from
> > Forrest and including them locally. That is effectively what users of
> > Forrest binary distributions do; they're using an old snapshot of the
> > DTDs.
>
> The problems at the moment I think are with versioning and what might
> happen in the future. This would require updating with external changes
> rather than relying on the external directly.
>
> How stable etc. are things?
No DTD changes for the last 2 months.
AFAIK, forrest-dev is completely lacking in bearded SGML gurus. So far,
we have treated DTD versioning like code versioning: increment the
version on large or backwards-incompatible changes. I have no idea if
this is adequate in practice, or if we must create a new DTD with every
minor edit.
<snip: using Ant for validation>
>
> I have a question. Why does the compliance.html work for the forrestbot
> but not on my machine.
> I get the error:
> Failed to create InputSource:
> file://<valid_path>/xml-fop/src/documentation/resources/schema/dtd/compliance-v10.dtd
>
> The file exists in that location (yes I have checked). So why can it not
> find the dtd. Is there a "/" missing or something like that. The
> "file:/" prepends a valid unix path.
Hmm. I get the same message, but build/site/compliance.html renders
fine. I presume it does on your box too?
As for the forrestbot, possibly the script is only logging stdout, not
stderr. I'll look into it.
--Jeff
Re: Ant-based local doc valiation
Posted by Jeff Turner <je...@apache.org>.
On Thu, Dec 12, 2002 at 04:54:03PM +0100, Keiron Liddle wrote:
> On Thu, 2002-12-12 at 16:16, Jeff Turner wrote:
> > Yes. There is nothing wrong with FOP grabbing the latest DTDs from
> > Forrest and including them locally. That is effectively what users of
> > Forrest binary distributions do; they're using an old snapshot of the
> > DTDs.
>
> The problems at the moment I think are with versioning and what might
> happen in the future. This would require updating with external changes
> rather than relying on the external directly.
>
> How stable etc. are things?
No DTD changes for the last 2 months.
AFAIK, forrest-dev is completely lacking in bearded SGML gurus. So far,
we have treated DTD versioning like code versioning: increment the
version on large or backwards-incompatible changes. I have no idea if
this is adequate in practice, or if we must create a new DTD with every
minor edit.
<snip: using Ant for validation>
>
> I have a question. Why does the compliance.html work for the forrestbot
> but not on my machine.
> I get the error:
> Failed to create InputSource:
> file://<valid_path>/xml-fop/src/documentation/resources/schema/dtd/compliance-v10.dtd
>
> The file exists in that location (yes I have checked). So why can it not
> find the dtd. Is there a "/" missing or something like that. The
> "file:/" prepends a valid unix path.
Hmm. I get the same message, but build/site/compliance.html renders
fine. I presume it does on your box too?
As for the forrestbot, possibly the script is only logging stdout, not
stderr. I'll look into it.
--Jeff
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
Re: Ant-based local doc valiation
Posted by Jeff Turner <je...@apache.org>.
On Thu, Dec 12, 2002 at 04:54:03PM +0100, Keiron Liddle wrote:
...
> > Including the DTDs would IMO be a good idea. They are only 57k. The
> > question is, what catalog-aware validation tool would you use?
> >
> > I would suggest upgrading the version of Ant bundled with FOP to 1.6-dev
> > from CVS. This includes <xmlcatalog> support for multiple external
> > catalogs. So after editing xdocs, developers could type 'build
> > validate', and if everything passes, they can safely commit the xdocs.
> > Then check on http://forrestbot.cocoondev.org if the changes look okay..
> > and one day, trigger an xml-site commit from that site too. Tada..
> > Forrest is no longer required for daily edits :)
>
> That sounds like a good idea once things settle down. Especially for
> small patches.
If you decide that an Ant 'validate' target using built-in DTDs is a good
idea, I created a patch to add this to FOP:
http://cvs.apache.org/~jefft/tmp/fop-validate.zip
The patch adds about 900k to xml-fop.
Appended is the patch README.
--Jeff
FOP Validation Patch README
Jeff Turner <je...@apache.org>
================================
Introduction
------------
This patch provides Ant-based validation of the various XML files used to
generate FOP's documentation.
The following files are validated:
src/documentation/content/xdocs/**/*.xml
src/documentation/sitemap.xmap
src/documentation/skinconf.xml
src/documentation/resources/stylesheets/**/*.xsl
The motivation is to prevent casual doc editors from having to download Forrest
to update content. The whole point of XML documentation is to separate content
from presentation. As long as the docs validate, it should be safe to check
them in, and then view the rendered website online at:
http://forrestbot.cocoondev.org/sites/xml-fop/
(updated every hour, or an update can be triggered)
Installation
------------
1) Copy everything in this directory (except this README) to the xml-fop/
directory.
2) In xml-fop, run 'patch -p0 < build.xml.diff', which adds a 'validate' target
to build.xml.
3) Delete lib/ant.jar, as it is no longer necessary.
Usage
-----
To validate XML files, run './build.sh validate' (Unix) or 'build validate'
(DOS). For better feedback, add a '-v' option. This should be done after an
XML edit, before checking into CVS.
If your editor supports catalogs, then it will be possible to validate docs as
you edit them. Point your editor to the catalog files (either OASIS or XML
format) in tools/schema/
How it works
------------
- The current (2002-12-14) Forrest DTDs are installed in tools/schema/.
- A stripped-down Ant 1.6-dev is installed in tools/ant.
- The new build.{sh,bat} files (and unfortunately, appendcp.bat) will use the
built-in Ant, which has external catalog support.
- The 'validate' target in build.xml will call tools/validate.xml, which
contains <xmlvalidate> and <jing> validation tasks. validate.xml is a
stripped-down version of Forrest's forrest.build.xml, and so supports
Forrest's fine-grained validation control properties specified in
forrest.properties (see http://xml.apache.org/forrest/validation.html).
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
Re: Ant-based local doc valiation
Posted by Keiron Liddle <ke...@aftexsw.com>.
On Thu, 2002-12-12 at 16:16, Jeff Turner wrote:
> Yes. There is nothing wrong with FOP grabbing the latest DTDs from
> Forrest and including them locally. That is effectively what users of
> Forrest binary distributions do; they're using an old snapshot of the
> DTDs.
The problems at the moment I think are with versioning and what might
happen in the future. This would require updating with external changes
rather than relying on the external directly.
How stable etc. are things?
> Including the DTDs would IMO be a good idea. They are only 57k. The
> question is, what catalog-aware validation tool would you use?
>
> I would suggest upgrading the version of Ant bundled with FOP to 1.6-dev
> from CVS. This includes <xmlcatalog> support for multiple external
> catalogs. So after editing xdocs, developers could type 'build
> validate', and if everything passes, they can safely commit the xdocs.
> Then check on http://forrestbot.cocoondev.org if the changes look okay..
> and one day, trigger an xml-site commit from that site too. Tada..
> Forrest is no longer required for daily edits :)
That sounds like a good idea once things settle down. Especially for
small patches.
What do others think?
I have a question. Why does the compliance.html work for the forrestbot
but not on my machine.
I get the error:
Failed to create InputSource:
file://<valid_path>/xml-fop/src/documentation/resources/schema/dtd/compliance-v10.dtd
The file exists in that location (yes I have checked). So why can it not
find the dtd. Is there a "/" missing or something like that. The
"file:/" prepends a valid unix path.
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
Ant-based local doc valiation (was: dtd catalog (was:...))
Posted by Jeff Turner <je...@apache.org>.
On Thu, Dec 12, 2002 at 11:48:16PM +1000, Peter B. West wrote:
> Victor Mote wrote:
> >Peter B. West wrote:
...
> >>These can (probably will) get out of sync. The dtd should be the one
> >>used when the document was last modified, shouldn't it? It seems to me
> >>there is a case for including the schema subtree, including catalog
> >>file(s) and the dtd subdirectory, in the src/build tree, and maintaining
> >>the synchronization locally.
> >
>
> It seems to me, on reflection, that I had this completely wrong. They
> can't get out of sync *while they have a PUBLIC identifier.* I am still
> naive about such things, but doesn't the assignment of a PUBLIC ID
> ammount to a contract that the document so named will never change?
Will never _break_. It may change in backwards-compatible ways. Just
like Java APIs.
> If you want to change it, you must assign another PUBLIC id, because
> people all over the net are relying on the constancy of the association
> between the original PUBLIC id and the actual document.
Yes. There is nothing wrong with FOP grabbing the latest DTDs from
Forrest and including them locally. That is effectively what users of
Forrest binary distributions do; they're using an old snapshot of the
DTDs.
> That means that it is perfectly safe to keep local copies of the
> documents, as long as you get the association right.
>
> >Keiron & I discussed this at the time:
> > http://marc.theaimsgroup.com/?l=fop-dev&m=103726556406364&w=2
> > http://marc.theaimsgroup.com/?l=fop-dev&m=103726721907599&w=2
> > http://marc.theaimsgroup.com/?l=fop-dev&m=103730698919444&w=2
> >and decided against it. Since I did this work, I see that we could use
> >viewcvs to get a specific revision of the file, so we could control this
> >using that method. However, it seems to me that DTDs conventionally have a
> >version number built into their filenames, so I assume that any changes
> >made
> >on those files are of a bug fix nature as opposed to radical changes that
> >would be likely to mess up users of the DTD.
> >
>
> I reviewed this exchange, and found that we had the same concern; a
> desire to be able to make changes to the documentation without having to
> have a local forrest installation for validation and rendering. Your
> (and Keiron's) initial suppositions about this were the same as mine.
Including the DTDs would IMO be a good idea. They are only 57k. The
question is, what catalog-aware validation tool would you use?
I would suggest upgrading the version of Ant bundled with FOP to 1.6-dev
from CVS. This includes <xmlcatalog> support for multiple external
catalogs. So after editing xdocs, developers could type 'build
validate', and if everything passes, they can safely commit the xdocs.
Then check on http://forrestbot.cocoondev.org if the changes look okay..
and one day, trigger an xml-site commit from that site too. Tada..
Forrest is no longer required for daily edits :)
If this sounds decent, I can create a patch to add Ant-based local
validation to FOP, and then document the process, as I'm sure lots of
projects' developers hate having to download 13mb of Forrest just to
update some stupid docs :)
> I don't understand what went wrong when Keiron tried this,
> > http://marc.theaimsgroup.com/?l=fop-dev&m=103726721907599&w=2
> but I wonder if cocoon is misbehaving by using the SYSTEM id instead of
> the PUBLIC id.
>
> <quote>
> Unfortunately it does work like that.
> To get the verification to work I need to add just the local public ID,
> so it uses the forrest one to verify forrest ID's and the local one for
> the local ID.
> Then when it is copied across cocoon can only find the ID for the fop
> dtd and the others are missing.
> If I put all the forrest+fop ID's in the catalog then it cannot verify
> as it cannot find the forrest dtd's relative to the catalog.
> </quote>
Keiron's expectations were correct. That was a bug in a pre-0.2 version
of Forrest. A small sample Forrest site illustrating the fix is at
http://cvs.apache.org/~jefft/forrest/samples/
--Jeff
...
> Peter
> --
> Peter B. West pbwest@powerup.com.au http://www.powerup.com.au/~pbwest/
> "Lord, to whom shall we go?"
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
Re: dtd catalog (was: src/documentation/README)
Posted by "Peter B. West" <pb...@powerup.com.au>.
Victor Mote wrote:
> Peter B. West wrote:
>
...
>
> The way this works is that your validation software has to know how to find
> the catalog. If it does, then the catalog can contain mappings from the
> PUBLIC IDs in the DOCTYPE declaration to a local physical file. That setup
> is already in all of our documents. For example, our resources.xml file
> contains the following DOCTYPE:
>
> <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
>
> "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/sche
> ma/dtd/document-v11.dtd">
>
> Your catalog has to know how to map "-//APACHE//DTD Documentation V1.1//EN"
> to "/u/xml-schema/document-v11.dtd" or whatever your local file is.
>
> What I added several weeks ago was the URIs (yes, they are CVS-based until
> we find some static URI to use instead) that allow the validation to be done
> across the internet. This doesn't take away the ability to use a local
> catalog, but rather makes it no longer a necessity. My understanding is that
> using URIs is the preferable way to do the validation. O'Reilly's "XML in a
> Nutshell", 2nd edition, page 32, says "In practice, however, PUBLIC IDs
> aren't used very much. Almost all validators rely on the URI to actually
> validate the document." The only reason to use the catalog and the PUBLIC ID
> is if you are on a machine that doesn't have suitable net access.
>
>
>>These can (probably will) get out of sync. The dtd should be the one
>>used when the document was last modified, shouldn't it? It seems to me
>>there is a case for including the schema subtree, including catalog
>>file(s) and the dtd subdirectory, in the src/build tree, and maintaining
>>the synchronization locally.
>
It seems to me, on reflection, that I had this completely wrong. They
can't get out of sync *while they have a PUBLIC identifier.* I am still
naive about such things, but doesn't the assignment of a PUBLIC ID
ammount to a contract that the document so named will never change? If
you want to change it, you must assign another PUBLIC id, because people
all over the net are relying on the constancy of the association between
the original PUBLIC id and the actual document.
That means that it is perfectly safe to keep local copies of the
documents, as long as you get the association right.
> Keiron & I discussed this at the time:
> http://marc.theaimsgroup.com/?l=fop-dev&m=103726556406364&w=2
> http://marc.theaimsgroup.com/?l=fop-dev&m=103726721907599&w=2
> http://marc.theaimsgroup.com/?l=fop-dev&m=103730698919444&w=2
> and decided against it. Since I did this work, I see that we could use
> viewcvs to get a specific revision of the file, so we could control this
> using that method. However, it seems to me that DTDs conventionally have a
> version number built into their filenames, so I assume that any changes made
> on those files are of a bug fix nature as opposed to radical changes that
> would be likely to mess up users of the DTD.
>
I reviewed this exchange, and found that we had the same concern; a
desire to be able to make changes to the documentation without having to
have a local forrest installation for validation and rendering. Your
(and Keiron's) initial suppositions about this were the same as mine.
I don't understand what went wrong when Keiron tried this,
> http://marc.theaimsgroup.com/?l=fop-dev&m=103726721907599&w=2
but I wonder if cocoon is misbehaving by using the SYSTEM id instead of
the PUBLIC id.
<quote>
Unfortunately it does work like that.
To get the verification to work I need to add just the local public ID,
so it uses the forrest one to verify forrest ID's and the local one for
the local ID.
Then when it is copied across cocoon can only find the ID for the fop
dtd and the others are missing.
If I put all the forrest+fop ID's in the catalog then it cannot verify
as it cannot find the forrest dtd's relative to the catalog.
</quote>
Keiron, when you say "local PUBLIC id", are you referring to last
component of the PUBLID id, containing the SYSTEM url? If a local copy
of all of the forrest DTDs were maintained, and the FOP catalog pointed
to that, then the problem of rendering locally or rendering remotely
would come down to making the renderer (cocoon + forrest) use the
correct (local or remote) catalog.
fop forrest(local) forrest(remote)
schema schema schema
| catalog | catalog | catalog
| | | | | |
dtd etc. | dtd | dtd |
*.dtd <-+ *.dtd <-+ *.dtd <-+
These DTDs are, I believe, set in concrete by virtue of their common
PUBLID id (irrespective of the SYSTEM component of those ids, which can
be completely ignored if a catalog is in place.)
At this stage we are not even talking about any local extensions, are we?
Peter
--
Peter B. West pbwest@powerup.com.au http://www.powerup.com.au/~pbwest/
"Lord, to whom shall we go?"
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
Re: dtd catalog (was: src/documentation/README)
Posted by Oleg Tkachenko <ol...@multiconn.com>.
Victor Mote wrote:
>>It seems to me, on reflection, that I had this completely wrong. They
>>can't get out of sync *while they have a PUBLIC identifier.* I am still
>>naive about such things, but doesn't the assignment of a PUBLIC ID
>>ammount to a contract that the document so named will never change? If
>>you want to change it, you must assign another PUBLIC id, because people
>>all over the net are relying on the constancy of the association between
>>the original PUBLIC id and the actual document.
>
>
> I don't know that there is any "contract" per se.
I think the contract does exist, at least IMO the essence of Public Id is to
be globally *unique* name of an entity [1]. Excactly one didtinct entity,
usually specific version of a dtd.
I would think of it more
> as a naming convention, a reserved /name/. You & I could have the same XML
> document on our local machines, and have catalogs pointing to local DTDs
> that were radically different.
That's violation of the contract as Public Id should uniquely name the
resource. e.g. -//OASIS//DTD DocBook XML V4.1.2//EN now and forever refers to
the XML version of DocBook V4.1.2.
To my knowledge, there is no universal way to
> translate a PUBLIC id into a real file (either local or on the net). Without
> that, there is no file, and therefore no assurance of anything resembling
> synchronization. In other words, to use PUBLIC ids, it seems to me that you
> have to have some totally external convention for making the actual DTD file
> available to the user of the DTD, and some external way of updating them as
> well. (By "external", I mean outside of XML -- for example, somebody has to
> send an email that says "the actual file is at ...".
That's why Public Id'd must be globally unique, e.g. when a dtd is modified
its Public Id must be changed and this way all are notified automatically.
[1] http://wwws.sun.com/software/xml/developers/resolver/article/#d0e229
--
Oleg Tkachenko
eXperanto team
Multiconn Technologies, Israel
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
RE: dtd catalog (was: src/documentation/README)
Posted by Victor Mote <vi...@outfitr.com>.
Peter B. West wrote:
> >>These can (probably will) get out of sync. The dtd should be the one
> >>used when the document was last modified, shouldn't it? It seems to me
> >>there is a case for including the schema subtree, including catalog
> >>file(s) and the dtd subdirectory, in the src/build tree, and maintaining
> >>the synchronization locally.
> >
>
> It seems to me, on reflection, that I had this completely wrong. They
> can't get out of sync *while they have a PUBLIC identifier.* I am still
> naive about such things, but doesn't the assignment of a PUBLIC ID
> ammount to a contract that the document so named will never change? If
> you want to change it, you must assign another PUBLIC id, because people
> all over the net are relying on the constancy of the association between
> the original PUBLIC id and the actual document.
I don't know that there is any "contract" per se. I would think of it more
as a naming convention, a reserved /name/. You & I could have the same XML
document on our local machines, and have catalogs pointing to local DTDs
that were radically different. To my knowledge, there is no universal way to
translate a PUBLIC id into a real file (either local or on the net). Without
that, there is no file, and therefore no assurance of anything resembling
synchronization. In other words, to use PUBLIC ids, it seems to me that you
have to have some totally external convention for making the actual DTD file
available to the user of the DTD, and some external way of updating them as
well. (By "external", I mean outside of XML -- for example, somebody has to
send an email that says "the actual file is at ...".
I think the terminology is a bit confusing, probably because this stuff
comes from SGML, which was created long before the net became popular.
PUBLIC doesn't refer to the access of the document, but rather to the fact
that the DTD is shared and therefore needs its own standard name.
> That means that it is perfectly safe to keep local copies of the
> documents, as long as you get the association right.
If you keep a local copy of the DTD & use it for validation, you do run the
risk of having the document validate on your machine, but not validate by
Forrest. In practice, I hope this will not happen, but I see nothing to
prevent it. To keep synchronized with Forrest, we'll have to point to their
DTDs. If they change something that makes our stuff break, we'll just have
to deal with it.
Victor Mote
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
Re: dtd catalog (was: src/documentation/README)
Posted by "Peter B. West" <pb...@powerup.com.au>.
Victor Mote wrote:
> Peter B. West wrote:
>
>
>>I'm still floundering around here, but when I found 'catalog' in
>>.../documentation/resources/schema, and the dtd in .../schema/dtd, I
>>began to see a ray of light. It seems to me that such a setup should be
>>used for all of the DOCTYPE delcarations in the documentation tree. At
>>the moment we are relying on the system identifier component of the
>>DOCTYPE declaration, and that is indicating a CVS retrieval - some from
>>the xml-forrest base, some from xml-cocoon2, last time I looked.
>
>
> The way this works is that your validation software has to know how to find
> the catalog. If it does, then the catalog can contain mappings from the
> PUBLIC IDs in the DOCTYPE declaration to a local physical file. That setup
> is already in all of our documents. For example, our resources.xml file
> contains the following DOCTYPE:
>
> <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
>
> "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/sche
> ma/dtd/document-v11.dtd">
>
> Your catalog has to know how to map "-//APACHE//DTD Documentation V1.1//EN"
> to "/u/xml-schema/document-v11.dtd" or whatever your local file is.
>
> What I added several weeks ago was the URIs (yes, they are CVS-based until
> we find some static URI to use instead) that allow the validation to be done
> across the internet. This doesn't take away the ability to use a local
> catalog, but rather makes it no longer a necessity. My understanding is that
> using URIs is the preferable way to do the validation. O'Reilly's "XML in a
> Nutshell", 2nd edition, page 32, says "In practice, however, PUBLIC IDs
> aren't used very much. Almost all validators rely on the URI to actually
> validate the document." The only reason to use the catalog and the PUBLIC ID
> is if you are on a machine that doesn't have suitable net access.
>
Norm Walsh has been campaigning for catalogs for a while now. E.g.
<http://wwws.sun.com/software/xml/developers/resolver/article/>.
I don't have the luxury of permanent net access. Neither do you if
cvs.apache.org is down or your access to the net is cut for any reason.
I think many apache developers would be in the situation that their work
on open source must take place _away_ from their employment environment,
and many of these would not have broadband or other permanent access. I
think that factor is worth considering.
Peter
--
Peter B. West pbwest@powerup.com.au http://www.powerup.com.au/~pbwest/
"Lord, to whom shall we go?"
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
RE: dtd catalog (was: src/documentation/README)
Posted by Victor Mote <vi...@outfitr.com>.
Peter B. West wrote:
> I'm still floundering around here, but when I found 'catalog' in
> .../documentation/resources/schema, and the dtd in .../schema/dtd, I
> began to see a ray of light. It seems to me that such a setup should be
> used for all of the DOCTYPE delcarations in the documentation tree. At
> the moment we are relying on the system identifier component of the
> DOCTYPE declaration, and that is indicating a CVS retrieval - some from
> the xml-forrest base, some from xml-cocoon2, last time I looked.
The way this works is that your validation software has to know how to find
the catalog. If it does, then the catalog can contain mappings from the
PUBLIC IDs in the DOCTYPE declaration to a local physical file. That setup
is already in all of our documents. For example, our resources.xml file
contains the following DOCTYPE:
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/sche
ma/dtd/document-v11.dtd">
Your catalog has to know how to map "-//APACHE//DTD Documentation V1.1//EN"
to "/u/xml-schema/document-v11.dtd" or whatever your local file is.
What I added several weeks ago was the URIs (yes, they are CVS-based until
we find some static URI to use instead) that allow the validation to be done
across the internet. This doesn't take away the ability to use a local
catalog, but rather makes it no longer a necessity. My understanding is that
using URIs is the preferable way to do the validation. O'Reilly's "XML in a
Nutshell", 2nd edition, page 32, says "In practice, however, PUBLIC IDs
aren't used very much. Almost all validators rely on the URI to actually
validate the document." The only reason to use the catalog and the PUBLIC ID
is if you are on a machine that doesn't have suitable net access.
> These can (probably will) get out of sync. The dtd should be the one
> used when the document was last modified, shouldn't it? It seems to me
> there is a case for including the schema subtree, including catalog
> file(s) and the dtd subdirectory, in the src/build tree, and maintaining
> the synchronization locally.
Keiron & I discussed this at the time:
http://marc.theaimsgroup.com/?l=fop-dev&m=103726556406364&w=2
http://marc.theaimsgroup.com/?l=fop-dev&m=103726721907599&w=2
http://marc.theaimsgroup.com/?l=fop-dev&m=103730698919444&w=2
and decided against it. Since I did this work, I see that we could use
viewcvs to get a specific revision of the file, so we could control this
using that method. However, it seems to me that DTDs conventionally have a
version number built into their filenames, so I assume that any changes made
on those files are of a bug fix nature as opposed to radical changes that
would be likely to mess up users of the DTD.
It seems to me that we have this set up as well as it can be, but I sure
could be missing something.
Victor Mote
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
Re: src/documentation/README
Posted by "Peter B. West" <pb...@powerup.com.au>.
Keiron Liddle wrote:
> On Tue, 2002-12-10 at 19:17, Victor Mote wrote:
>
>>OK, I see now that I misunderstood your "Sorry, yes" answer to Keiron. If
>>http://forrestbot.cocoondev.org/site/xml-fop should be reflecting changes no
>>more than an hour old made to xml-fop/src/documentation, then it is not
>>working. I just looked for changes that were made about 24 hours ago, and
>>they are not there. Also, as I mentioned, it shows a publish date of 12-7.
>>So I suspect that something is not working. We have one document with a
>>non-standard DTD (my fault, in fact that is what I am trying to work on)
>>that might be messing up the flow. How do I go about troubleshooting this?
>
>
> Judging by the log it might be a DISPLAY problem.
>
> The compliance doc should only cause a broken link.
>
> Who is in charge of the cocoondev site, could they work out what the
> problem is?
>
>
>>>I think Sam Ruby has a script which automatically updates the live site
>>>to the contents of xml-site/targets/*.
>>
>>Should I contact him directly? Also, I still don't know whether
>>xml-site/targets/fop is my final destination. What is best practices for
>>this process? If this is documented somewhere, please excuse me -- I haven't
>>found it yet. Also, I realize that this conversation might be better on
>>forrest-dev. I asked on this list because I think Keiron has already figured
>>most of this out & I am trying to leverage off of that. Thanks very much for
>>your help.
>
>
> Haven't figured out all of it.
> There is no real documentation for the old process, currently we are
> only really replacing the doc generation process.
Keiron, Victor,
I'm still floundering around here, but when I found 'catalog' in
.../documentation/resources/schema, and the dtd in .../schema/dtd, I
began to see a ray of light. It seems to me that such a setup should be
used for all of the DOCTYPE delcarations in the documentation tree. At
the moment we are relying on the system identifier component of the
DOCTYPE declaration, and that is indicating a CVS retrieval - some from
the xml-forrest base, some from xml-cocoon2, last time I looked.
These can (probably will) get out of sync. The dtd should be the one
used when the document was last modified, shouldn't it? It seems to me
there is a case for including the schema subtree, including catalog
file(s) and the dtd subdirectory, in the src/build tree, and maintaining
the synchronization locally.
Peter
--
Peter B. West pbwest@powerup.com.au http://www.powerup.com.au/~pbwest/
"Lord, to whom shall we go?"
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
Re: src/documentation/README
Posted by Jeff Turner <je...@apache.org>.
On Wed, Dec 11, 2002 at 03:15:33PM +0100, Nicola Ken Barozzi wrote:
...
[On why http://forrestbot.cocoondev.org/sites/xml-fop/ wasn't updating]
...
> [java] Exception in thread "main" java.lang.InternalError: Can't
> connect to X11 window server using ':0.0' as the value of the DISPLAY
> variable.
I added a DISPLAY pointing to Xvfb, and it seems to be updating properly
now. If anyone notices a 'Last published' date at the bottom of a page
older than 1 hour (GMT) please let me know.
--Jeff
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
Re: src/documentation/README
Posted by Jeff Turner <je...@apache.org>.
On Wed, Dec 11, 2002 at 03:15:33PM +0100, Nicola Ken Barozzi wrote:
...
[On why http://forrestbot.cocoondev.org/sites/xml-fop/ wasn't updating]
...
> [java] Exception in thread "main" java.lang.InternalError: Can't
> connect to X11 window server using ':0.0' as the value of the DISPLAY
> variable.
I added a DISPLAY pointing to Xvfb, and it seems to be updating properly
now. If anyone notices a 'Last published' date at the bottom of a page
older than 1 hour (GMT) please let me know.
--Jeff
Re: src/documentation/README
Posted by Steven Noels <st...@outerthought.org>.
Nicola Ken Barozzi wrote:
> forwarding to forrest.
>
> Here is the relevant part of the last log:
>
>
> [java] Exception in thread "main" java.lang.InternalError: Can't
> connect to X11 window server using ':0.0' as the value of the DISPLAY
> variable.
ACK - we'll check.
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://radio.weblogs.com/0103539/
stevenn at outerthought.org stevenn at apache.org
Re: src/documentation/README
Posted by Stefan Bodewig <bo...@apache.org>.
On Wed, 11 Dec 2002, Nicola Ken Barozzi <ni...@apache.org> wrote:
> [java] Exception in thread "main" java.lang.InternalError:
> Can't connect to X11 window server using ':0.0' as the value
> of the DISPLAY variable.
quite common on Unix boxes. When you do something with AWT, most Unix
JVMs will need access to an X-Windows-Server (this is at least true
for the Solaris and Linux VMs I know).
If there is none running, you are in trouble, but the solution is
simple: Install Xvfb, start it before you start the script and set the
DISPLAY environment variable correctly.
i.e. before you run the script (or as the first thing inside the
script) do
Xvfb :1 &
DISPLAY :1.0; export DISPLAY
you may need to perform some additional configuration with respect to
authentication, please consult the manual pages 8-)
Stefan
Re: src/documentation/README
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Keiron Liddle wrote:
> On Tue, 2002-12-10 at 19:17, Victor Mote wrote:
>
>>OK, I see now that I misunderstood your "Sorry, yes" answer to Keiron. If
>>http://forrestbot.cocoondev.org/site/xml-fop should be reflecting changes no
>>more than an hour old made to xml-fop/src/documentation, then it is not
>>working. I just looked for changes that were made about 24 hours ago, and
>>they are not there. Also, as I mentioned, it shows a publish date of 12-7.
>>So I suspect that something is not working. We have one document with a
>>non-standard DTD (my fault, in fact that is what I am trying to work on)
>>that might be messing up the flow. How do I go about troubleshooting this?
>
>
> Judging by the log it might be a DISPLAY problem.
>
> The compliance doc should only cause a broken link.
>
> Who is in charge of the cocoondev site, could they work out what the
> problem is?
forwarding to forrest.
Here is the relevant part of the last log:
[java] Exception in thread "main" java.lang.InternalError: Can't
connect to X11 window server using ':0.0' as the value of the DISPLAY
variable.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
Re: src/documentation/README
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Keiron Liddle wrote:
> On Tue, 2002-12-10 at 19:17, Victor Mote wrote:
>
>>OK, I see now that I misunderstood your "Sorry, yes" answer to Keiron. If
>>http://forrestbot.cocoondev.org/site/xml-fop should be reflecting changes no
>>more than an hour old made to xml-fop/src/documentation, then it is not
>>working. I just looked for changes that were made about 24 hours ago, and
>>they are not there. Also, as I mentioned, it shows a publish date of 12-7.
>>So I suspect that something is not working. We have one document with a
>>non-standard DTD (my fault, in fact that is what I am trying to work on)
>>that might be messing up the flow. How do I go about troubleshooting this?
>
>
> Judging by the log it might be a DISPLAY problem.
>
> The compliance doc should only cause a broken link.
>
> Who is in charge of the cocoondev site, could they work out what the
> problem is?
forwarding to forrest.
Here is the relevant part of the last log:
[java] Exception in thread "main" java.lang.InternalError: Can't
connect to X11 window server using ':0.0' as the value of the DISPLAY
variable.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------