You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@velocity.apache.org by Henning Schmiedehausen <hp...@intermeta.de> on 2006/04/02 13:58:00 UTC
Getting a central location for ASF DTDs
Hi,
as part of the 'next' release of Jakarta Velocity, we want to rework the
docs that are currently in xdoc format. Xdoc is used in some places
inside the ASF, not the last being the base format used by the Jakarta
web site (through Anakia and Velocity) source and the documentation of
many other Apache projects.
Arnaud Heritier and Lukas Theussl have created a DTD for the maven-xdoc
plugin which can transform the XDOC format into XHTML. However, what we
are missing is a central location for this DTD. As this is not "just
part of maven country" and "not just part of Jakarta Velocity", I'd like
to put this DTD into a central location and proposed
'http://www.apache.org/dtds/' as its storage location. As this would be
picked up by the mirrors, this is IMHO a good place.
So the question is: What steps need to be taken to set up such a
location (which would be in the tradition of struts.apache.org/dtds or
avalon.apache.org/dtds ... ;-) ) and give the committers related to the
XDOC stuff (which are probably the maven-xdoc folks and the Jakarta
Velocity people) write access. Or are there objections from the
infrastructure team about such a centralized DTD location?
Best regards
Henning
--
Dipl.-Inf. (Univ.) Henning P. Schmiedehausen INTERMETA GmbH
hps@intermeta.de +49 9131 50 654 0 http://www.intermeta.de/
RedHat Certified Engineer -- Jakarta Turbine Development
Linux, Java, perl, Solaris -- Consulting, Training, Engineering
Social behaviour: Bavarians can be extremely egalitarian and folksy.
-- http://en.wikipedia.org/wiki/Bavaria
Most Franconians do not like to be called Bavarians.
-- http://en.wikipedia.org/wiki/Franconia
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: Getting a central location for ASF DTDs
Posted by David Crossley <cr...@apache.org>.
Roy T. Fielding wrote:
> Henning Schmiedehausen wrote:
>
> >Hi,
> >
> >as part of the 'next' release of Jakarta Velocity, we want to
> >rework the
> >docs that are currently in xdoc format. Xdoc is used in some places
> >inside the ASF, not the last being the base format used by the Jakarta
> >web site (through Anakia and Velocity) source and the documentation of
> >many other Apache projects.
> >
> >Arnaud Heritier and Lukas Theussl have created a DTD for the maven-
> >xdoc
> >plugin which can transform the XDOC format into XHTML. However,
> >what we
> >are missing is a central location for this DTD. As this is not "just
> >part of maven country" and "not just part of Jakarta Velocity", I'd
> >like
> >to put this DTD into a central location and proposed
> >'http://www.apache.org/dtds/' as its storage location. As this
> >would be
> >picked up by the mirrors, this is IMHO a good place.
> >
> >So the question is: What steps need to be taken to set up such a
> >location (which would be in the tradition of struts.apache.org/dtds or
> >avalon.apache.org/dtds ... ;-) ) and give the committers related to
> >the
> >XDOC stuff (which are probably the maven-xdoc folks and the Jakarta
> >Velocity people) write access. Or are there objections from the
> >infrastructure team about such a centralized DTD location?
>
> I object. XML software is friggin broken, including the stuff we
> produce. DTDs are never needed in XML and if you include a full URI
> in the declaration then the idiotic parsers will retrieve it at runtime
> for no good reason. The location needs to be a file relative to the
> documentation just to keep our server from dying.
Projects should be using the Catalog Entity Resolver
so that their applications never need to hit the
network for the DTDs and uses local copies instead.
This is what we do at Cocoon and Forrest.
http://xml.apache.org/commons/components/resolver/
-David
> What they should produce is a RELAX-NG grammar and simply make that
> file available in the distribution for validation. Referencing the
> DTD inside the XDOC/XHTML files is harmful to extensibility.
>
> ....Roy
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: Getting a central location for ASF DTDs
Posted by Daniel Dekany <dd...@freemail.hu>.
Monday, April 3, 2006, 4:43:13 PM, Henning Schmiedehausen wrote:
> IMHO the reason for the abysmal state of documentation in most projects
> using xdoc is not that the format is hard. But that people think that
> "writing xdoc in emacs" is a good thing. It is not. Not even for
> technical people (But then again I might simply not know what I'm
> talking about, I'm not only an emacs user for 15+ years). Just look at
> any arbitrary number of maven xdoc driven web sites out there and the
> quality and amount of docs in these sites.
>
> If you want to write useful documentation, IMHO you want to write it
> like text in a word processor.
Absolutely.
> Something that you can do with some of the more sophisticated XML
> editors. That is why docbook became so popular.
This is why I don't understand why there is no free "visual" docbook
editor with reasonable set of features. Like, on-the-fly spell
checking and chapter outline... There are free versions of much much
more heavy stuff. OK, frankly, I do understand it... "hackers" (guys
with genuine programmers spirit), either think that emacs/vi is
something good in this task (or they think they look more clever and
more important if they use ancient obscure tools), or they don't care
writing documentation too much.
I searched a lot a free DocBook editor (or even a commercial), and so
far my blind-tip is XMLMind XML Editor (XXE) too. I found nothing else
where I have seen hope. Now, these XMLMind guys have a wish list
(http://www.xmlmind.com/xmleditor/wish_list.html), where you can write
e-mails to submit new wishes, or to suggest that a certain already
existing wish is important. I already told them earlier my opinion,
that they could become *The* Documentation Editor of OS projects, just
be adding a few improvements, like on-the-fly spell checking and
outline view (ToC view). This would give them big visibility
advantage, that then brings them a lot of money. So, anybody feels
like me about XXE, don't be lazy to write to them about your
suggestions...
[snip]
--
Best regards,
Daniel Dekany
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: Getting a central location for ASF DTDs
Posted by Mike Kienenberger <mk...@gmail.com>.
On 4/3/06, Henning P. Schmiedehausen <hp...@intermeta.de> wrote:
> >Why do we really need an internet dtd? XMLMind works fine by
> >including the dtd inside the xdcos addon.
>
> Does it? I tried to use just "SYSTEM" identifiers and ended up with
> either having the dtd file in every subdirectory of all sub-projects
> or having to juggle around with "SYSTEM "../../../dtds/xdoc.dtd"
> pathes that change whenever a file is moved. Both is not exactly user
> friendly. Note that the problem is not the editor but the xdoc plugin.
>
> AFAIK, for a DTD we must either have a public/system identifier pair
> or just a system reference. You can't just get a public reference
> alone.
Maybe it's not "up to spec", but PUBLIC is working fine for me. I'm
using a PUBLIC identifier with the dtds in the xdocs addon dtd
directory and it "just works"
Try comparing your current setup to what's in the following attachment
and see if you can figure out what the difference is. I've only been
using it with the also-non-existent maven identifier, but I don't see
why that would matter.
http://wiki.apache.org/myfaces-data/attachments/EditXdocs/attachments/XMLMind_XDOC_Myfaces.zip
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: Getting a central location for ASF DTDs
Posted by "Henning P. Schmiedehausen" <hp...@intermeta.de>.
"Mike Kienenberger" <mk...@gmail.com> writes:
>Henning,
>Why do we really need an internet dtd? XMLMind works fine by
>including the dtd inside the xdcos addon.
Does it? I tried to use just "SYSTEM" identifiers and ended up with
either having the dtd file in every subdirectory of all sub-projects
or having to juggle around with "SYSTEM "../../../dtds/xdoc.dtd"
pathes that change whenever a file is moved. Both is not exactly user
friendly. Note that the problem is not the editor but the xdoc plugin.
AFAIK, for a DTD we must either have a public/system identifier pair
or just a system reference. You can't just get a public reference
alone.
And while it would be trivial to convert the DTD into an XML schema
and then use all the good "use an entity resolver that is not broken"
advice, it would also rob us of XMLMind, because the free version only
supports a very small subset of XML schemas. For arbitrary support,
you need the professional version and I simply can't see people
spending > 200 bucks just to contribute to open source software.
IMHO, there are three possible solutions (there might be more, but the whole thing really starts to tire me)
- screw it. Don't reference a DTD and let people who want to use
XMLMind figure out all by themselves that they have to associate the
xml files with the XDOC dtd and style sheets (see Wills' first and
second posting in this thread, about this being non-intuitive without
a DTD.
- use an XSD. Which leaves us with XDOC exactly where we started (no
tool support) but now all the XML lawyers can have a ball, because we
abandoned the "evil DTD".
- Work around the infrastructure people. Add a PUBLIC identifier and
hack the xdoc plugin to "somehow" support this identifier without
accessing the net. Then add a public location somewhere under
jakarta.apache.org/velocity and be done.
All three suck but the first two screw our users. I'll go with the third.
Best regards
Henning
--
Dipl.-Inf. (Univ.) Henning P. Schmiedehausen INTERMETA GmbH
hps@intermeta.de +49 9131 50 654 0 http://www.intermeta.de/
RedHat Certified Engineer -- Jakarta Turbine Development -- hero for hire
Linux, Java, perl, Solaris -- Consulting, Training, Development
Social behaviour: Bavarians can be extremely egalitarian and folksy.
-- http://en.wikipedia.org/wiki/Bavaria
Most Franconians do not like to be called Bavarians.
-- http://en.wikipedia.org/wiki/Franconia
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: Getting a central location for ASF DTDs
Posted by Mike Kienenberger <mk...@gmail.com>.
On 4/3/06, Henning Schmiedehausen <hp...@intermeta.de> wrote:
> I think that the point is moot here. There are tools out there and there
> is a way to validate. As the infra people object to a generic
> solution, I will discuss this further with Maven xdoc and Velocity to
> find a solution on the outside. Sucks, but then again I don't want to
> make a religious war out of that issue.
Henning,
Why do we really need an internet dtd? XMLMind works fine by
including the dtd inside the xdcos addon.
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: Getting a central location for ASF DTDs
Posted by Henning Schmiedehausen <hp...@intermeta.de>.
IMHO the reason for the abysmal state of documentation in most projects
using xdoc is not that the format is hard. But that people think that
"writing xdoc in emacs" is a good thing. It is not. Not even for
technical people (But then again I might simply not know what I'm
talking about, I'm not only an emacs user for 15+ years). Just look at
any arbitrary number of maven xdoc driven web sites out there and the
quality and amount of docs in these sites.
If you want to write useful documentation, IMHO you want to write it
like text in a word processor. Something that you can do with some of
the more sophisticated XML editors. That is why docbook became so popular.
And getting a free (as in free beer) XML editor that is able to use
arbitrary XML schemas and is cross platform and can do WYSIWYG editing
is not really an easy thing. Trust me, I tried in the last few weeks.
The only thing that comes close seems to be XMLMind and there you are
stuck with DTDs unless you hand out serious money for uncrippled XML
schema support.
I think that the point is moot here. There are tools out there and there
is a way to validate. As the infra people object to a generic
solution, I will discuss this further with Maven xdoc and Velocity to
find a solution on the outside. Sucks, but then again I don't want to
make a religious war out of that issue.
However, the "all tools are broken, you should use <xxx> instead" advice
I've gotten multiple times now is neither helpful nor realistic. I don't
want to write XML software. I want to use existing software to write XML
formatted docs. Which in the end seems to be the real mistake to begin
with. :-/
Best regards
Henning
Jochen Wiedmann schrieb:
> On 4/3/06, Henning Schmiedehausen <hp...@intermeta.de> wrote:
>
>> XMLSpy is expensive and only runs on Windows. We are trying to make xdoc
>> documentation more accessible, not less.
>
> And what is the problem in writing xdoc with emacs? Validates fine
> against an XML schema. (nXML mode)
>
> Jochen
>
> --
> Whenever you find yourself on the side of the
> majority, it is time to pause and reflect.
> (Mark Twain)
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: Getting a central location for ASF DTDs
Posted by Jochen Wiedmann <jo...@gmail.com>.
On 4/3/06, Henning Schmiedehausen <hp...@intermeta.de> wrote:
> XMLSpy is expensive and only runs on Windows. We are trying to make xdoc
> documentation more accessible, not less.
And what is the problem in writing xdoc with emacs? Validates fine
against an XML schema. (nXML mode)
Jochen
--
Whenever you find yourself on the side of the
majority, it is time to pause and reflect.
(Mark Twain)
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: Getting a central location for ASF DTDs
Posted by Henning Schmiedehausen <hp...@intermeta.de>.
XMLSpy is expensive and only runs on Windows. We are trying to make xdoc
documentation more accessible, not less.
Best regards
Henning
Jochen Wiedmann schrieb:
> Roy T. Fielding wrote:
>
>> I object. XML software is friggin broken, including the stuff we
>> produce. DTDs are never needed in XML and if you include a full URI
>> in the declaration then the idiotic parsers will retrieve it at runtime
>> for no good reason. The location needs to be a file relative to the
>> documentation just to keep our server from dying.
>
> Roy, traffic to apache.org can be avoided quite simple: Use an URI like
>
> http://namespaces.apache.org/jakarta/velocity/...
>
> Note, that namespaces.apache.org isn't resolvable via DNS.
>
> As you fear, this will lead to problems on the users side. But I do believe,
> that it's finally time for people to learn using entity resolvers.
>
>
>> What they should produce is a RELAX-NG grammar and simply make that
>> file available in the distribution for validation. Referencing the
>> DTD inside the XDOC/XHTML files is harmful to extensibility.
>
> Forcing people not to use a DTD doesn't sound like a practical option (it
> possibly is for you). Additionally, the problem is quite the same with XML
> Schema.
>
>
> Henning Schmiedehausen wrote:
>
>> Not referencing it breaks the XML editors which use the DTD to validate
>> the docs. Relax NG and XML Schema are nice things but where are the
>> tools?
>
> Are you kidding? Ever used XML Spy or a beast like that? Ever used JAXB? In
> contrary, DTD's are (fortunately) dying out.
>
>> If an application decides to load a known DTD at runtime, then IMHO the
>> application is broken. Not the specification.
>
> It's not as easy as you think, in particular, because XML parsing frequently
> occurs in external components, which you can hardly control. The most
> practical solution are entity resolvers, indeed.
>
>
> Jochen
>
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: Getting a central location for ASF DTDs
Posted by Jochen Wiedmann <jo...@gmail.com>.
Roy T. Fielding wrote:
> I object. XML software is friggin broken, including the stuff we
> produce. DTDs are never needed in XML and if you include a full URI
> in the declaration then the idiotic parsers will retrieve it at runtime
> for no good reason. The location needs to be a file relative to the
> documentation just to keep our server from dying.
Roy, traffic to apache.org can be avoided quite simple: Use an URI like
http://namespaces.apache.org/jakarta/velocity/...
Note, that namespaces.apache.org isn't resolvable via DNS.
As you fear, this will lead to problems on the users side. But I do believe,
that it's finally time for people to learn using entity resolvers.
> What they should produce is a RELAX-NG grammar and simply make that
> file available in the distribution for validation. Referencing the
> DTD inside the XDOC/XHTML files is harmful to extensibility.
Forcing people not to use a DTD doesn't sound like a practical option (it
possibly is for you). Additionally, the problem is quite the same with XML
Schema.
Henning Schmiedehausen wrote:
> Not referencing it breaks the XML editors which use the DTD to validate
> the docs. Relax NG and XML Schema are nice things but where are the
> tools?
Are you kidding? Ever used XML Spy or a beast like that? Ever used JAXB? In
contrary, DTD's are (fortunately) dying out.
> If an application decides to load a known DTD at runtime, then IMHO the
> application is broken. Not the specification.
It's not as easy as you think, in particular, because XML parsing frequently
occurs in external components, which you can hardly control. The most
practical solution are entity resolvers, indeed.
Jochen
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: Getting a central location for ASF DTDs
Posted by Joshua Slive <jo...@slive.ca>.
On 4/2/06, Henning Schmiedehausen <hp...@intermeta.de> wrote:
> Is the DTD traffic really killing the servers? Or is that more of a
> political issue?
It is about 6% of all hits to our main webserver in March. That is
not "killing the servers", but it is substantial and annoying, given
its pointlessness.
See:
http://people.apache.org/~henkp/analog/www/2006/03/
Joshua.
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: Getting a central location for ASF DTDs
Posted by Henning Schmiedehausen <hp...@intermeta.de>.
Hi,
there are some interesting points. The main problem IMHO with system
identifiers that relatively point to a local file is, that you have to
juggle the pathes all the time. You are always fixing up the DTD
location path if you move a file up or down in the file hierarchy. You
don't have that problem with an external URI.
Not referencing it breaks the XML editors which use the DTD to validate
the docs. Relax NG and XML Schema are nice things but where are the
tools?
If you object strongly, I'd really like to see a possible alternative.
We finally have some sort of tool set which is able to edit xdoc files
without resorting to a text editor and typing <section> manually.
If an application decides to load a known DTD at runtime, then IMHO the
application is broken. Not the specification.
We have a number of DTD locations all over the ASF (I can cite three or
four off the top of my head). Personally I'd prefer to coordinate with
the infra team for a centralized location instead of using a project
location. The ASF infrastructure survives struts.apache.org/dtds, so I
see no reason why it shouldn't survive a centralized location for the
XDOC DTD.
Is the DTD traffic really killing the servers? Or is that more of a
political issue?
Best regards
Henning
On Sun, 2006-04-02 at 13:14 -0700, Roy T. Fielding wrote:
> On Apr 2, 2006, at 4:58 AM, Henning Schmiedehausen wrote:
>
> > Hi,
> >
> > as part of the 'next' release of Jakarta Velocity, we want to
> > rework the
> > docs that are currently in xdoc format. Xdoc is used in some places
> > inside the ASF, not the last being the base format used by the Jakarta
> > web site (through Anakia and Velocity) source and the documentation of
> > many other Apache projects.
> >
> > Arnaud Heritier and Lukas Theussl have created a DTD for the maven-
> > xdoc
> > plugin which can transform the XDOC format into XHTML. However,
> > what we
> > are missing is a central location for this DTD. As this is not "just
> > part of maven country" and "not just part of Jakarta Velocity", I'd
> > like
> > to put this DTD into a central location and proposed
> > 'http://www.apache.org/dtds/' as its storage location. As this
> > would be
> > picked up by the mirrors, this is IMHO a good place.
> >
> > So the question is: What steps need to be taken to set up such a
> > location (which would be in the tradition of struts.apache.org/dtds or
> > avalon.apache.org/dtds ... ;-) ) and give the committers related to
> > the
> > XDOC stuff (which are probably the maven-xdoc folks and the Jakarta
> > Velocity people) write access. Or are there objections from the
> > infrastructure team about such a centralized DTD location?
>
> I object. XML software is friggin broken, including the stuff we
> produce. DTDs are never needed in XML and if you include a full URI
> in the declaration then the idiotic parsers will retrieve it at runtime
> for no good reason. The location needs to be a file relative to the
> documentation just to keep our server from dying.
>
> What they should produce is a RELAX-NG grammar and simply make that
> file available in the distribution for validation. Referencing the
> DTD inside the XDOC/XHTML files is harmful to extensibility.
>
> ....Roy
>
--
Dipl.-Inf. (Univ.) Henning P. Schmiedehausen INTERMETA GmbH
hps@intermeta.de +49 9131 50 654 0 http://www.intermeta.de/
RedHat Certified Engineer -- Jakarta Turbine Development
Linux, Java, perl, Solaris -- Consulting, Training, Engineering
Social behaviour: Bavarians can be extremely egalitarian and folksy.
-- http://en.wikipedia.org/wiki/Bavaria
Most Franconians do not like to be called Bavarians.
-- http://en.wikipedia.org/wiki/Franconia
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: Getting a central location for ASF DTDs
Posted by "Roy T. Fielding" <fi...@gbiv.com>.
On Apr 2, 2006, at 4:58 AM, Henning Schmiedehausen wrote:
> Hi,
>
> as part of the 'next' release of Jakarta Velocity, we want to
> rework the
> docs that are currently in xdoc format. Xdoc is used in some places
> inside the ASF, not the last being the base format used by the Jakarta
> web site (through Anakia and Velocity) source and the documentation of
> many other Apache projects.
>
> Arnaud Heritier and Lukas Theussl have created a DTD for the maven-
> xdoc
> plugin which can transform the XDOC format into XHTML. However,
> what we
> are missing is a central location for this DTD. As this is not "just
> part of maven country" and "not just part of Jakarta Velocity", I'd
> like
> to put this DTD into a central location and proposed
> 'http://www.apache.org/dtds/' as its storage location. As this
> would be
> picked up by the mirrors, this is IMHO a good place.
>
> So the question is: What steps need to be taken to set up such a
> location (which would be in the tradition of struts.apache.org/dtds or
> avalon.apache.org/dtds ... ;-) ) and give the committers related to
> the
> XDOC stuff (which are probably the maven-xdoc folks and the Jakarta
> Velocity people) write access. Or are there objections from the
> infrastructure team about such a centralized DTD location?
I object. XML software is friggin broken, including the stuff we
produce. DTDs are never needed in XML and if you include a full URI
in the declaration then the idiotic parsers will retrieve it at runtime
for no good reason. The location needs to be a file relative to the
documentation just to keep our server from dying.
What they should produce is a RELAX-NG grammar and simply make that
file available in the distribution for validation. Referencing the
DTD inside the XDOC/XHTML files is harmful to extensibility.
....Roy
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org