commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stephen Colebourne <scolebou...@btopenworld.com>
Subject Re: old style html in javadoc Was: [jira] Commented: (IO-86) Add FileFinder back into Commons IO
Date Mon, 24 Jul 2006 01:33:04 GMT
The concept that XML (XHTML in this case) is human readable is highly dubious, and has become
accepted wisdom far too easily.
 
 The first point is that it isn't 'bad' HTML, its just normal HTML. Every HTML tool going
has to be able to cope with this sort of layout so any tool arguments fail pretty quickly.
 
 So it comes down to readability, which is much more of a stylistic choice. Personally, I
strive to avoid unecessary clutter, only including unecessary things (eg. additionl brackets)
if I judge it aids understanding.
 
 Here, the end paragraphs tell a human nothing, and the start paragraphs get in the way (delaying
the eye from reaching the first meaningful word).
 
 In the end, this is about human interaction with that piece of text (in any editor including
eclipse). And HCI would suggest getting the eye to the most meaningful piece of information
(the actual text, not the tag) quickly. ie. remove the unecessary clutter.
 
 And its not a break tag, its a paragraph tag. That really would be breaking the HTML model.
 
 Stephen
 
 PS. All of [io] uses <p> between paragraph style now (and it was 95%+ before the discussion
started)
 

----- Original Message ----
From: Henri Yandell <flamefew@gmail.com>
Ugh. The bad html makes it less readable as source for me (and I'm
using vim so definitely a target  for the more readableness I think).

Definitely minor - but the correct solution would be to use <br/>
instead of <p>, I believe. That achieves what is wanted in this
javadoc (a break) without it becoming 90s style html.

Hen

On 7/23/06, Stephen Colebourne (JIRA) <jira@apache.org> wrote:
>     [ http://issues.apache.org/jira/browse/IO-86?page=comments#action_12422889 ]
>
> Stephen Colebourne commented on IO-86:
> --------------------------------------
>
> Its only a small addition to [io] and appears to make sense now.
>
> One minor nit is that the most of the [io] code doesn't use XHTML, but instead:
>   Para1
>   <p>
>   Para2
>   <p>
>   Para3
> This is done to make the javadoc more readable when viewing it as source.
>
> I also think that there should be some way to perform subclass processing before and
after the find.
>
> > Add FileFinder back into Commons IO
> > -----------------------------------
> >
> >                 Key: IO-86
> >                 URL: http://issues.apache.org/jira/browse/IO-86
> >             Project: Commons IO
> >          Issue Type: New Feature
> >    Affects Versions: 1.2
> >            Reporter: Niall Pemberton
> >             Fix For: 1.3
> >
> >         Attachments: FileFinder.java, FileFinderTestCase.java
> >
> >
> > I'd like to propose adding a "FileFinder" back into Commons IO. This is a simplified
version of what was recently moved out of Commons IO into the "finder" component currently
in the sandbox.
> > I believe this is a simpler, more generic implementation than the finder component
and therefore would be considered suitable for inclusion in Commons IO. Although simpler it
could be used as the basis for achieving the finder component's aims - namely to emulate the
unix find command.
>
> --
> This message is automatically generated by JIRA.
> -
> If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
> -
> For more information on JIRA, see: http://www.atlassian.com/software/jira
>
>
>
> ---------------------------------------------------------------------
> 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





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