Vincent Siveton wrote:
Nope. The code passed the encoding parameter *only* if it was not empty.
You're right, I forgot that the Maven JVM might be running with a
different default encoding than the system default that would be picked
by javadoc if "encoding" wasn't specified.
Yes but I think it is not the correct behaviour according the javadoc
tool documentation.
Agreed, the behavior was different from the native javadoc tool. My hope
was to convince you that the interface of the underlying tool should not
prescribe the interface of the Maven plugin.
Some other examples: Say we have a reporting tool whose output encoding
unconditionally defaults to Latin-1 or whatever, i.e. has a different
logic than javadoc. Now I put that together with the Javadoc plugin in
my site generation. Further assume, my source encoding is UTF-8 so the
Javadoc plugin will use this for output by your commit. Using their
default values, these two plugins will use different encodings for their
outputs. To get a consistent site (which I would call a best practice,
something Maven says to promote) I would need to explicitly tell both
plugins to use the same encoding. So my question here is, why do I need
to do this extra XML clutter when another Maven philosophy says
convention over configuration? Why couldn't this two plugins or more
general all Maven report plugins adhere to some nice convention?
Knowing this problem, we came up with a proposal for Report Encoding
Configuration [0] which, as far as I remember, wasn't rejected or
otherwise commented both on dev@ and on @user. There is also a JIRA
issue where users have wished for UTF-8 as default report encoding
(MSITE-224).
The Javadoc plugin is currently breaking with the proposal. As a matter
of consistency, we might need to adjust the proposal if the community
doesn't accept it's current form. But I wonder how the alternative would
look like? Have all report plugins mimic the Javadoc plugin? What do
those plugins that require no "encoding" parameter but only have a
"docencodign" thingy? What would be their default output encoding,
platform encoding while the Javadoc plugin defaults to the
user-specified source encoding?
Again, I feel consistency among our plugins is more important than
mimicing the underlying tool since I believe this has impact on the way
users perceive Maven: Is it a dumb wrapper over external tools with some
glue in between or a build system on its own where all parts fit nicely
together without first going through clutterly configurations?
The encoding convention is to specify encoding to make build
reproducibility.
That was the result for the input/source encoding, primarily to prevent
existing builds from breaking. Taking
a) Maven's aim for build reproducibility and
b) Maven's philosophy of convention over configuration
together, I still don't call the current way ideal.
For the report output encoding however, we have more luck: Defaulting it
to some fixed encoding won't break builds since the output is consumed
by browsers and HTML provides means to specify the charset to the
browser. So why don't we take the chance and get us reproducible sites,
by default?
Benjamin
[0] http://docs.codehaus.org/display/MAVEN/Reporting+Encoding+Configuration
Disclaimer: I don't want to upset anybody. There are just some ideas
that I read somewhere on the Maven site that really caught me. Whereever
I feel these ideals are violated, I try to get prevent that, maybe
sometimes to passionately.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
