commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Craig McClanahan <craig...@gmail.com>
Subject Re: Javadoc formatting style
Date Mon, 07 Feb 2005 02:22:42 GMT
The standard HTML format is *not* the only output format you can get
with Javadocs -- it is quite feasible to render alternative XML-based
formats that can then be transformed using standard XML technologies
-- but that only works if the markup created by Javadocs comments is
well formed.

In addition, the lack of rigor that HTML requires has always been my
least favorite thing about the web in general -- I wish we'd started
with a culture that requires well formed XML in the first place.  Not
having done so has had a *direct* impact on the portability of
documents across browsers, and that impact has been negative overall.

The same mistake has essentially been made with RSS -- instead of
being disciplined about what they produce, RSS providers have expected
the newsfeed readers to go through incredible contortions to read
invalid feeds.  That philosophy is backwards.

I prefer to set a good example on things like this, rather than
contributing to the problem.

Craig



On Mon, 07 Feb 2005 15:06:49 +1300, Simon Kitching <skitching@apache.org> wrote:
> On Sun, 2005-02-06 at 17:18 -0800, Craig McClanahan wrote:
> > As should be evident from my own recent practice :-), I'm also +1 on
> > the first (XHTML) approach.
> 
> Can I ask those supporters of the XHTML style why they prefer it?
> 
> Personally I think it:
> * increases the text size of the source file
> * is harder to write manually (and harder to write correctly)
> * makes the docs in the source file harder to read
> * might be easier for the javadoc app to parse, but that
>   makes no difference to us users of javadoc; the javadoc
>   tool support for HTML-style isn't going away.
> and
> * has no effect whatsoever on the generated html pages
> 
> Not that it's a *huge* deal, but HTML-style just seems a bit better all
> around. Yet quite a few people obviously do prefer XHTML-style. Is it
> just for the "purity"?
> 
> Regards,
> 
> Simon
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
> 
>

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message