You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by Lukas Theussl <lt...@apache.org> on 2005/10/03 20:56:24 UTC
What is an xdoc?
Hi everybody,
As some of you may have noticed, I have recently worked on the
validation goal for xdocs in the m1 xdoc plugin. The task is now
practically complete, with the validate goal doing what I intended it to do.
Now I'd like to raise the question in the subject, I am not aware of any
normative definition of an xdoc? I have adapted the xhtml1-transitional
dtd to include all the elements used in xdoc documents that I am aware
of. In the current state, all xdoc sources for all m1 plugins get
validated by the xdoc:validate goal (as implemented in the current
1.10-SNAPSHOT m1 xdoc plugin), and AFAICT, the resulting html documents
are all valid xhtml1-transitional.
However, I don't want to take the sole responsibility for defining what
an xdoc is... ;) It would be nice if I could get some feedback about
whether what I did is sensible, any omissions, extensions, etc. I have
put a few notes about xdoc validation here: [1], the maven-xdoc.dtd file
can be found in SVN in the src/dtd/ directory of the m1 xdoc plugin.
Finally, I suppose that in m2 xdocs follow the same format as in m1 and
that the validation routines will be implemented following the same
rules. If this is the case, then the dtd files should be kept
synchronized between the two versions in the future.
Any comments will be appreciated,
Lukas
[1]
http://people.apache.org/~ltheussl/maven-stage-site/reference/plugins/xdoc/reference/xdocs.html#Validation
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
RE: What is an xdoc?
Posted by Arnaud HERITIER <ah...@gmail.com>.
>
> > The only problem I saw in the DTD is the tags
> goals/goal/name/description tag which isn't an xdoc tag.
>
> Well, that brings up exactly the question that I asked: how
> do you know it's not an xdoc tag? Where is that defined? I
> didn't find anything on the Anakia site so I assumed that
> anything that gets transformed into a valid xhtml1 document
> by maven is a valid xdoc.
No, The reference was : http://jakarta.apache.org/site/jakarta-site2.html
>
> > I never understood why these files are directly
> transformed in the site.jsl but I didn't find the time to change it.
>
> OK, I think we should decide what to do about that before
> publishing the dtd. I would favor putting the goals
> transformation into the plugin plugin. Anybody aware of some
> side effects that might have?
+1
I don't think that it will create side-effects if we inform users to upgrade both plugins.
The only think to do : find the time to do it ;-)
Arnaud
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: What is an xdoc?
Posted by Lukas Theussl <lt...@apache.org>.
> In fact an xdoc is only a XHTML 1.0 document with some changes to use sections/subsections.
I understood that, that's why I used the xhtml1 dtd as a base. In fact,
all additions to xhtml1 are given just at the last few lines of the dtd
file.
> The only problem I saw in the DTD is the tags goals/goal/name/description tag which isn't an xdoc tag.
Well, that brings up exactly the question that I asked: how do you know
it's not an xdoc tag? Where is that defined? I didn't find anything on
the Anakia site so I assumed that anything that gets transformed into a
valid xhtml1 document by maven is a valid xdoc.
> I never understood why these files are directly transformed in the site.jsl but I didn't find the time to change it.
OK, I think we should decide what to do about that before publishing the
dtd. I would favor putting the goals transformation into the plugin
plugin. Anybody aware of some side effects that might have?
-Lukas
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
RE: What is an xdoc?
Posted by Arnaud HERITIER <ah...@gmail.com>.
Hi Lukas,
A Xdoc is a format comming from Anakia Project (if I have a good memory).
This format was used a lot in jakarta projects to write their documentations.
http://jakarta.apache.org/site/jakarta-site2.html
In fact an xdoc is only a XHTML 1.0 document with some changes to use sections/subsections.
The only problem I saw in the DTD is the tags goals/goal/name/description tag which isn't an xdoc tag.
goals.xml documents aren't xdocs files. They are created by the plugin-plugin.
These files are intermediate files that should be converted in xdoc (like changes.xml, ...) or the plugin-plugin should
generate xdoc files directly.
I never understood why these files are directly transformed in the site.jsl but I didn't find the time to change it.
Arnaud
>
> Hi everybody,
>
> As some of you may have noticed, I have recently worked on
> the validation goal for xdocs in the m1 xdoc plugin. The task
> is now practically complete, with the validate goal doing
> what I intended it to do.
>
> Now I'd like to raise the question in the subject, I am not
> aware of any normative definition of an xdoc? I have adapted
> the xhtml1-transitional dtd to include all the elements used
> in xdoc documents that I am aware of. In the current state,
> all xdoc sources for all m1 plugins get validated by the
> xdoc:validate goal (as implemented in the current
> 1.10-SNAPSHOT m1 xdoc plugin), and AFAICT, the resulting html
> documents are all valid xhtml1-transitional.
>
> However, I don't want to take the sole responsibility for
> defining what an xdoc is... ;) It would be nice if I could
> get some feedback about whether what I did is sensible, any
> omissions, extensions, etc. I have put a few notes about xdoc
> validation here: [1], the maven-xdoc.dtd file can be found in
> SVN in the src/dtd/ directory of the m1 xdoc plugin.
>
> Finally, I suppose that in m2 xdocs follow the same format as
> in m1 and that the validation routines will be implemented
> following the same rules. If this is the case, then the dtd
> files should be kept synchronized between the two versions in
> the future.
>
>
> Any comments will be appreciated,
> Lukas
>
>
> [1]
> http://people.apache.org/~ltheussl/maven-stage-site/reference/
> plugins/xdoc/reference/xdocs.html#Validation
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org For
> additional commands, e-mail: dev-help@maven.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org