Maven 1.x XDoc Plugin

allow i18n links

Details

  • Type: Improvement Improvement
  • Status: Closed Closed
  • Priority: Major Major
  • Resolution: Fixed
  • Affects Version/s: None
  • Fix Version/s: 1.9.2
  • Labels:
    None
  • Number of attachments :
    7

Description

Currently, we can't directly use the pom or velocity in user-documentation.

JSL is applied to the user-docs as-is. I suggest having a property called maven.docs.src.templates (defaults to false) that when set to true treats user-docs as templates.

Then, slightly modify the goal xdoc:jelly-transform.

We need to var's:

<j:set var="mergeUserDocs" value="$

{maven.docs.src.templates}

"/>
<j:set var="hasUserDocs" value="$

{maven.docs.src.available}

"/>

If both evaluate to true then velocity:merge the user docs before doing jsl. If they evaluate to false do as before.

It would probably be nice to be able to use jelly as well as user-supplied docs.

  1. Text File
    hrefkey.patch
    19/Aug/05 2:53 AM
    7 kB
    Ignacio G. Mac Dowell
  2. Text File
    last.cumulative.patch
    15/Feb/05 7:33 AM
    15 kB
    Ignacio G. Mac Dowell
  3. Text File
    last.docs.patch
    15/Feb/05 7:32 AM
    3 kB
    Ignacio G. Mac Dowell
  4. Text File
    last.main.patch
    15/Feb/05 7:32 AM
    3 kB
    Ignacio G. Mac Dowell
  5. Text File
    last.test.patch
    15/Feb/05 7:31 AM
    8 kB
    Ignacio G. Mac Dowell
  6. Text File
    plugin.jelly.patch
    11/Feb/05 5:12 AM
    2 kB
    Ignacio G. Mac Dowell
  7. Text File
    plugin.properties.patch
    11/Feb/05 5:13 AM
    0.6 kB
    Ignacio G. Mac Dowell

Activity

Ascending order - Click to sort in descending order
Hide
Permalink
Ignacio G. Mac Dowell added a comment -

Maybe it would be nice to be able to use .jelly also as user-docs. If anybody is interested I'll supply the patch.

Show
Ignacio G. Mac Dowell added a comment - Maybe it would be nice to be able to use .jelly also as user-docs. If anybody is interested I'll supply the patch.
Hide
Permalink
Ignacio G. Mac Dowell added a comment -

Default user-doc-templates to false

Show
Ignacio G. Mac Dowell added a comment - Default user-doc-templates to false
Hide
Permalink
Arnaud Heritier added a comment -

It seems interesting Ignacio.
Can you add a plugin-test and a patch for the documentation please ?

Show
Arnaud Heritier added a comment - It seems interesting Ignacio. Can you add a plugin-test and a patch for the documentation please ?
Hide
Permalink
Ignacio G. Mac Dowell added a comment -

The patch submitted fails when there is a directory with xdocs under the xdocs directory. The problem is that velocity:merge doesn't seem to like generating a file with no parentFile (directory). I am going to submit 4 patches:
1. Tests
2. Src
3. Docs
4. Cumulative (all 3)

for easier review.

regards

Show
Ignacio G. Mac Dowell added a comment - The patch submitted fails when there is a directory with xdocs under the xdocs directory. The problem is that velocity:merge doesn't seem to like generating a file with no parentFile (directory). I am going to submit 4 patches: 1. Tests 2. Src 3. Docs 4. Cumulative (all 3) for easier review. regards
Hide
Permalink
Ignacio G. Mac Dowell added a comment -

Tests for MPXDOC-131

Show
Ignacio G. Mac Dowell added a comment - Tests for MPXDOC-131
Hide
Permalink
Ignacio G. Mac Dowell added a comment -

Src for MPXDOC-131

Show
Ignacio G. Mac Dowell added a comment - Src for MPXDOC-131
Hide
Permalink
Ignacio G. Mac Dowell added a comment -

Docs patch for MPXDOC-131

Show
Ignacio G. Mac Dowell added a comment - Docs patch for MPXDOC-131
Hide
Permalink
Ignacio G. Mac Dowell added a comment -

Cumulative patch with tests, src and docs

Show
Ignacio G. Mac Dowell added a comment - Cumulative patch with tests, src and docs
Hide
Permalink
Brett Porter added a comment -

Ignacio, thanks for putting the effort into this, but for significant changes it does need to be discussed with the dev team first (thanks for approaching us now to do so).

I'm not in favour of this change as it is against the direction we are taking things. To introduce Jelly processing into the source files ties it to an XML format, but we support plain text, docbook, xdoc and more in Maven2 and may backport that to Maven1.

I'd like to discuss your use case on the list to see what alternatives there are.

Show
Brett Porter added a comment - Ignacio, thanks for putting the effort into this, but for significant changes it does need to be discussed with the dev team first (thanks for approaching us now to do so). I'm not in favour of this change as it is against the direction we are taking things. To introduce Jelly processing into the source files ties it to an XML format, but we support plain text, docbook, xdoc and more in Maven2 and may backport that to Maven1. I'd like to discuss your use case on the list to see what alternatives there are.
Hide
Permalink
Ignacio G. Mac Dowell added a comment -

Support for i18n links. Tests and docs included. It might be nice to have them for the item elements in navigation.xml as well. If you think it's worth it I'll send a patch as well.

Anyway, I've seen that you can use your own jsl so if there is not much interest in this issue I can deal with it. That said, IMHO it is interesting to have i18n links.

Thanks

nacho

Show
Ignacio G. Mac Dowell added a comment - Support for i18n links. Tests and docs included. It might be nice to have them for the item elements in navigation.xml as well. If you think it's worth it I'll send a patch as well. Anyway, I've seen that you can use your own jsl so if there is not much interest in this issue I can deal with it. That said, IMHO it is interesting to have i18n links. Thanks nacho
Hide
Permalink
Brett Porter added a comment -

I think this is a good idea.

Show
Brett Porter added a comment - I think this is a good idea.
Hide
Permalink
Lukas Theussl added a comment -

Ignacio,
I have checked your latest patch (hrefkey.patch). Unless I'm missing something, the test that you attached does not produce the desired result (an element <a hrefkey="testlinks.mysite1">empty document</a> is generated instead of <a href="http://mysite1.com">empty document</a>) . If you could fix that we'll include it in our next release.

Show
Lukas Theussl added a comment - Ignacio, I have checked your latest patch (hrefkey.patch). Unless I'm missing something, the test that you attached does not produce the desired result (an element <a hrefkey="testlinks.mysite1">empty document</a> is generated instead of <a href="http://mysite1.com">empty document</a>) . If you could fix that we'll include it in our next release.
Hide
Permalink
Ignacio G. Mac Dowell added a comment -

If i run test03, test04 and the multiproject test against the patched plugin, I do get the desired results.

Are you running the tests against the patched plugin? Another alternative to test is to change maven.xdoc.jsl since it is the only important file that this patch changes (a part from docs and tests).

Show
Ignacio G. Mac Dowell added a comment - If i run test03, test04 and the multiproject test against the patched plugin, I do get the desired results. Are you running the tests against the patched plugin? Another alternative to test is to change maven.xdoc.jsl since it is the only important file that this patch changes (a part from docs and tests).
Hide
Permalink
Lukas Theussl added a comment -

Hmm, seems I forgot to install the plugin before I tested it...

We'll include it in our 1.9.2 release. Thanks!

Show
Lukas Theussl added a comment - Hmm, seems I forgot to install the plugin before I tested it... We'll include it in our 1.9.2 release. Thanks!
Hide
Permalink
Arnaud Heritier added a comment -

Applied. Thanks.

Show
Arnaud Heritier added a comment - Applied. Thanks.

People

  • Assignee:
    Arnaud Heritier
    Reporter:
    Ignacio G. Mac Dowell
Vote (0)
Watch (0)

Dates

  • Created:
    Updated:
    Resolved: