maven-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Hervé BOUTEMY <herve.bout...@free.fr>
Subject Re: [VOTE] Release Maven Javadoc Plugin version 2.5
Date Sat, 02 Aug 2008 13:11:39 GMT
Le samedi 02 août 2008, Benjamin Bentmann a écrit :
> Vincent Siveton wrote:
> > So by default, we have now:
> > - encoding = ${project.build.sourceEncoding}
> > - docencoding = ${project.reporting.outputEncoding}
> > - charset = null
> >
> > And if charset == null, charset = docencoding
>
> Yes, as per MJAVADOC-182 and MJAVADOC-206, i.e. setting "docencoding" is
> usually sufficient to control the report output.
>
> > Also, I noticed in the Javadoc tool documentation:
> > -encoding "If this option is not specified, the platform default
> > converter is used."
> > Ok Hervé displays a warn about build platform dependent if null but
> > the -encoding param is not passed in the Javadoc tool.
>
> Hm, AbstractJavadocMojo.java:3527 is the line where the mojo's encoding
> parameter is passed to javadoc.
>
> > -docencoding "If you omit this option but use -encoding, then the
> > encoding of the generated HTML files is determined by -encoding."
> > We need to reflect this logic and NOT using UTF-8 which is actually the
> > default.
>
> But using UTF-8 as the default was the whole intention of MJAVADOC-206.
> Let's consider the bigger picture, i.e. the entire site generation
> process: Other report generation plugins might have no "encoding"
> parameter (e.g. because they don't read the sources), so those plugins
> cannot mimic the logic of the javadoc tool. Say foo-maven-plugin is such
> a report plugin and we have this POM snippet:
>
>    <properties>
>      <p.b.sourceEncoding>Big5</p.b.sourceEncoding>
>    </properties>
>    <reporting>
>      <plugins>
>        <plugin>
>          <artifactId>maven-javadoc-plugin</artifactId>
>        </plugin>
>        <plugin>
>          <artifactId>foo-maven-plugin</artifactId>
>        </plugin>
>      </plugins>
>    </reporting>
>
> This states "Dear Maven, my source files are Big5 but I want my site in
> UTF-8 (the proposed default for project.report.outputEncoding [0])". Now
> comes the Javadoc Plugin and uses its own historic/proprietary logic to
> render the report in Big5 while all the other reports are rendered in
> UTF-8?
>
> Maven plugins often provide a facade over other tools and I feel, in the
> spirit of convention over configuration and any other Maven philosophy,
> we have the right to make the plugin behave differently than the
> underlying tool. The overall design goal should be to get a smooth build
> with as less XML clutter as possible, not to dumbly mimic another tools
> command line (which was designed for a completely different use case
> than a Maven build).
>
> Just my two cents, maybe Hervé has something else to say.
you perfectly summed up the whole logic behind "Report Encoding Configuration" 
proposal [0], then its Jira issue MNG-3608 [1]
(I forgot to link it to MJAVADOC-206: done now)

Hervé

>
>
> Benjamin
>
>
> [0] http://docs.codehaus.org/display/MAVEN/Reporting+Encoding+Configuration
[1] http://jira.codehaus.org/browse/MNG-3608

>
> ---------------------------------------------------------------------
> 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


Mime
View raw message