Maven Doxia

Create an xdoc DTD or XSD for maven 2

Details

  • Type: Task Task
  • Status: Closed Closed
  • Priority: Major Major
  • Resolution: Fixed
  • Affects Version/s: None
  • Fix Version/s: 1.1
  • Component/s: Module - Xdoc
  • Labels:
    None
  • Number of attachments :
    0

Description

In Maven 1, a valid xdoc was defined to be something that was converted into a valid xhtml document by the m1 xdoc plugin. I guess in m2 the same procedure should be applied to doxia. We need to identify the features that 1) should be added 2) should be removed with respect to the m1 xdoc dtd.

Issue Links

This issue is related to:
DOXIA-130 Macro renaming Major Closed
DOXIA-129 Allow correctly head element in xdoc Major Closed
This issue supercedes:
DOXIA-97 Xdoc DTD does not allow the <macro> directive Major Closed
This issue is depended upon by:
DOXIA-141 Add missing references for FML XDOC Major Closed
DOXIA-89 Doxia Macro syntax for xdoc sucks Major Closed
DOXIA-263 Improve validation of input documents Major Closed
DOXIA-104 Support use of custom properties in XDOC files Critical Closed

Activity

Ascending order - Click to sort in descending order
Hide
Permalink
Lukas Theussl added a comment -

One feature to be added: the macro directive, see DOXIA-97.

Show
Lukas Theussl added a comment - One feature to be added: the macro directive, see DOXIA-97.
Hide
Permalink
Lukas Theussl added a comment -

Some links for reference:

http://maven.apache.org/dtd/xdoc_1_0.dtd
http://maven.apache.org/maven-1.x/plugins/xdoc/reference/xdocs.html
MPXDOC-192

IIRC, an m1 xdoc differs from a valid xhtml1-transitional only by the addition of the following elements:
<section>, <subsection>, <source>, <escapeXml>, <navbar>.

I guess the latter two are candidates for removal...

Show
Lukas Theussl added a comment - Some links for reference: http://maven.apache.org/dtd/xdoc_1_0.dtd http://maven.apache.org/maven-1.x/plugins/xdoc/reference/xdocs.html MPXDOC-192 IIRC, an m1 xdoc differs from a valid xhtml1-transitional only by the addition of the following elements: <section>, <subsection>, <source>, <escapeXml>, <navbar>. I guess the latter two are candidates for removal...
Hide
Permalink
Lukas Theussl added a comment -

A minor point: in m1 an email attribute is required for the author tag, I think this should be relaxed and be made optional.

Show
Lukas Theussl added a comment - A minor point: in m1 an email attribute is required for the author tag, I think this should be relaxed and be made optional.
Hide
Permalink
Vincent Siveton added a comment -

For the log, the main differences between m1 and xhtml1-transitional are:

  • added properties element which has author and title element
  • elements already mentioned

The differences between m1 and m2 DTD are:

  • removed head, escapeXml and navbar elements
  • added macro element

The critical problem to have a DTD is the macro element which is dynamic. I propose to change the xdoc parser to handle the following:

<macro name="snippet">
        <parameter name="id" value="toto"/>
        <parameter name="url" value="http://myserver.org/toto.xml"/>
      </macro>

instead of:

<macro name="snippet" id="toto" url="http://myserver.org/toto.xml"/>

WDYT?

Show
Vincent Siveton added a comment - For the log, the main differences between m1 and xhtml1-transitional are:
  • added properties element which has author and title element
  • elements already mentioned
The differences between m1 and m2 DTD are:
  • removed head, escapeXml and navbar elements
  • added macro element
The critical problem to have a DTD is the macro element which is dynamic. I propose to change the xdoc parser to handle the following: 
<macro name="snippet">
        <parameter name="id" value="toto"/>
        <parameter name="url" value="http://myserver.org/toto.xml"/>
      </macro>
instead of: 
<macro name="snippet" id="toto" url="http://myserver.org/toto.xml"/>
WDYT?
Hide
Permalink
Lukas Theussl added a comment -
  • I was not aware that <head> was not allowed in m2 xdocs, is there a reason for it? See MSITE-230.
  • For backward compatibility, shouldn't we keep the escapeXml and navbar elements? The DTD would validate them but we don't have to implement them, ie they would simply be ignored by the parser.
  • I agree with the macro renaming, that would also solve DOXIA-89.
Show
Lukas Theussl added a comment -
  • I was not aware that <head> was not allowed in m2 xdocs, is there a reason for it? See MSITE-230.
  • For backward compatibility, shouldn't we keep the escapeXml and navbar elements? The DTD would validate them but we don't have to implement them, ie they would simply be ignored by the parser.
  • I agree with the macro renaming, that would also solve DOXIA-89.
Hide
Permalink
Vincent Siveton added a comment -

> * I was not aware that <head> was not allowed in m2 xdocs, is there a reason for it? See MSITE-230.

Dont know.

> * For backward compatibility, shouldn't we keep the escapeXml and navbar elements? The DTD would validate them but we don't have to implement them, ie they would simply be ignored by the parser.

Doxia is in alpha version so I dont see any problems for the backward compatibility. I think we could remove them.

Show
Vincent Siveton added a comment - > * I was not aware that <head> was not allowed in m2 xdocs, is there a reason for it? See MSITE-230. Dont know. > * For backward compatibility, shouldn't we keep the escapeXml and navbar elements? The DTD would validate them but we don't have to implement them, ie they would simply be ignored by the parser. Doxia is in alpha version so I dont see any problems for the backward compatibility. I think we could remove them.
Hide
Permalink
Lukas Theussl added a comment -

I know doxia is still alpha but we are about to change that ...

The question is, should every xdoc that was valid in m1 also be valid in m2 (even if not all features are implemented)? Or in other words, if someone provides us, some time in the future, with an implementation of escapeXml and navbar, should we accept it as a new feature or reject it categorically? If we allow it in principle then it should go into the DTD. I guess that the effect of both can be mimicked by some macro, so it's not necessary to have them. I also think we should remove them, for the sake of simplicity, but we should be clear about it, because users will always come up with some "... but it should be possible to do that..."...

Show
Lukas Theussl added a comment - I know doxia is still alpha but we are about to change that ... The question is, should every xdoc that was valid in m1 also be valid in m2 (even if not all features are implemented)? Or in other words, if someone provides us, some time in the future, with an implementation of escapeXml and navbar, should we accept it as a new feature or reject it categorically? If we allow it in principle then it should go into the DTD. I guess that the effect of both can be mimicked by some macro, so it's not necessary to have them. I also think we should remove them, for the sake of simplicity, but we should be clear about it, because users will always come up with some "... but it should be possible to do that..."...
Hide
Permalink
Vincent Siveton added a comment -

IMHO like m2 doesnt support them at all, we dont need to add them in the DTD.
But it is easy to add them in the xdoc parser and provides a log info. WDYT?

Show
Vincent Siveton added a comment - IMHO like m2 doesnt support them at all, we dont need to add them in the DTD. But it is easy to add them in the xdoc parser and provides a log info. WDYT?
Hide
Permalink
Vincent Siveton added a comment -

As discussed on IRC, provide an XSD sounds better.

Show
Vincent Siveton added a comment - As discussed on IRC, provide an XSD sounds better.
Hide
Permalink
Vincent Siveton added a comment -

Updated title

Show
Vincent Siveton added a comment - Updated title
Hide
Permalink
Vincent Siveton added a comment -

I added xsd files in r703144

Show
Vincent Siveton added a comment - I added xsd files in r703144

People

Vote (0)
Watch (0)

Dates

  • Created:
    Updated:
    Resolved:
Atlassian JIRA (v4.4.3#663-r165197) | Report a problem
Powered by a free Atlassian JIRA open source license for Codehaus. Try JIRA - bug tracking software for your team.