duck-streams missing from clojure-contrib.jar file

[Neal]

Hi,

I'm new to Clojure. I've been trying to go through the Programming
Clojure book and have run into a problem that I hope someone can fix.

I'm trying to use duck-streams, but it is missing from the clojure-
contrib JAR file (at least in build #81). I have listed the contents
of the JAR file and confirmed that it is not in there.

All the documentation that I read seems to indicate that duck-streams
is not deprecated.

Thanks for any help,

Neal

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clo...@googlegroups.com
Note that posts from new members are moderated - please be patient with your first post.
To unsubscribe from this group, send email to
clojure+u...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en

[Meikel Brandmeyer]

Hi,

On 21 Apr., 01:37, Neal <neal_degrego...@yahoo.com> wrote:

> All the documentation that I read seems to indicate that duck-streams
> is not deprecated.

c.c.ducks-streams is now named c.c.io.

Sincerely
Meikel

[Alex Osborne]

Hi Neal,

Neal <neal_de...@yahoo.com> writes:

> I'm trying to use duck-streams, but it is missing from the clojure-
> contrib JAR file (at least in build #81). I have listed the contents
> of the JAR file and confirmed that it is not in there.

It sounds like you're using a 1.2 pre-release snapshot build of
clojure-contrib. There's currently some refactoring going on to better
organize contrib, now that it's a little more mature. Most of
clojure.contrib.duck-streams has now become clojure.contrib.io.

I suggest you use the stable 1.1 releases of both Clojure and contrib
for your initial learning as it will better match the book. When 1.2 is
released stable I'm sure there will be a document written that explains
the differences.

I really wish the 1.1.0 release builds were more prominently linked on
the clojure.org website, but you can download them here:

http://build.clojure.org/releases/org/clojure/clojure/1.1.0/clojure-1.1.0.jar
http://build.clojure.org/releases/org/clojure/clojure-contrib/1.1.0/clojure-contrib-1.1.0.jar

Hope that helps,

Alex

[Douglas Philips]

On 2010 Apr 21, at 8:11 AM, Alex Osborne wrote:
> I suggest you use the stable 1.1 releases of both Clojure and contrib
> for your initial learning as it will better match the book. When
> 1.2 is
> released stable I'm sure there will be a document written that
> explains
> the differences.

That isn't as helpful as you might think.

(I'm using 1.1, as conveniently provided by macports.)

Nothing that I can find on either clojure.org or the contrib site http://richhickey.github.com/clojure-contrib/
says what version it is/applies-to.

How would I know if I'm using the stable 1.1 release that I need to
replace clojure.contrib.seq with clojure.contrib.seq-utils, or
clojure.contrib.io with clojure.contrib.duck-stream?

http://richhickey.github.com/clojure-contrib/io-api.html doesn't say:
This document applies to 1.2 (pending), for 1.1 or older see: <url>
nor:
This document applies to 1.2 (pending), it was renamed from
clojure.contrib.duck-stream


--Doug

[Stuart Halloway]

The second level header tells you the branch (e.g. master). On the
left hand side is a list of branches (so you can click on e.g. 1.1.x).

Some ways I see this might be better:

(1) make clear what master currently equals (right now it is 1.2 alpha)
(2) highlight the branch info more with css
(3) push the branch info into the top-level header (and page title)
(4) The overview section for c.c.io could tell about the lineage back
to 1.1.

Which of these (or what else?) would have helped you the most?

Stu

[Alex Osborne]

Stuart Halloway <stuart....@gmail.com> writes:

> The second level header tells you the branch (e.g. master). On the
> left hand side is a list of branches (so you can click on e.g. 1.1.x).
>
> Some ways I see this might be better:
>
> (1) make clear what master currently equals (right now it is 1.2 alpha)
> (2) highlight the branch info more with css
> (3) push the branch info into the top-level header (and page title)
> (4) The overview section for c.c.io could tell about the lineage back
> to 1.1.

I think it might also help to make the stable versions the default
view. I think people new to the language should really be guided to
using the stable releases and documentation rather than snapshots, as
the snapshots may well be in flux and cause lots of confusion.
People choosing to use the bleeding edge git snapshots will know what
the branches are and can specify the one they want.

[Laurent PETIT]

2010/4/21 Alex Osborne <a...@meshy.org>:

> Stuart Halloway <stuart....@gmail.com> writes:
>
>> The second level header tells you the branch (e.g. master). On the
>> left hand side is a list of branches (so you can click on e.g. 1.1.x).
>>
>> Some ways I see this might be better:
>>
>> (1) make clear what master currently equals (right now it is 1.2 alpha)
>> (2) highlight the branch info more with css
>> (3) push the branch info into the top-level header (and page title)
>> (4) The overview section for c.c.io could tell about the lineage back
>> to 1.1.
>
> I think it might also help to make the stable versions the default
> view.  I think people new to the language should really be guided to
> using the stable releases and documentation rather than snapshots, as
> the snapshots may well be in flux and cause lots of confusion.
> People choosing to use the bleeding edge git snapshots will know what
> the branches are and can specify the one they want.

#(swap! % inc)

[Douglas Philips]

On 2010 Apr 21, at 9:31 AM, Stuart Halloway wrote:

> The second level header tells you the branch (e.g. master). On the
> left hand side is a list of branches (so you can click on e.g. 1.1.x).

Wow, that is quite subtle. As you click into contrib from clojure.org
it isn't very noticeable.
It also isn't something you notice if you are, for example, clicking
through from the unversioned clojure.org pages.
An example at random:
Start at: http://clojure.org/macros
then click on the lazy-cat link, which takes you to: http://richhickey.github.com/clojure/clojure.core-api.html#clojure.core/
lazy-cat
and start browsing.

With your focus down 'into' that page you have no idea that you've
jumped into versioned information.

If you start as a beginner, as I did, the stuff on clojure.org is not
versioned (there is no master/1.1.x link in the side bar) and so
having version info appear only in contrib pages is not easy to
notice, particularly if you get there via links from the main page.

> Some ways I see this might be better:
>
> (1) make clear what master currently equals (right now it is 1.2
> alpha)

That would help. Master is pretty generic.

> (2) highlight the branch info more with css

Couldn't hurt, but it it'd be nice if showed in the page title too,
the sidebars are lost when scrolling down into the various pages.

> (3) push the branch info into the top-level header (and page title)

Yup.

> (4) The overview section for c.c.io could tell about the lineage
> back to 1.1.

Not having been along for the ride since (nearly) the beginning,
having those breadcrumbs would be helpful to me.

> Which of these (or what else?) would have helped you the most?

I think having the default, as Alex Osburne suggested, be the stable
release would have made my exploration of 1.1 a lot less painful.

And along those lines, distinguishing between core and contrib is
something that might be important to the maintainers, but not so much
to the users. And, very less useful to newbies trying to get something
useful done.

Trying to figure out that spit is in a contrib library and slurp
isn't? C'mon. I finally broke down and used google, and then when I
saw a thread back in '08 about that, and it still isn't addressed?
Really, easy file I/O is that unimportant to most clojure users?

Having a unified and comprehensive index of functions/macros
(annotated with core/contrib) would also go a long way to making the
clojure documentation environment a lot more useful. Oh, and then
there is the distinction between http://clojure.org/libraries and the
contrib libraries. Yet another place to look? Great, I really don't
have anything better to do than internalize these distinctions? (In
case you can't tell, having burned -hours- of spare time trying to
find my way around docs has been exceptionally frustrating.)

At least for someone like me who is exploring on their own and isn't
getting paid to make this work, having to lose my train of thought for
5-10 minutes while trying to figure out if something is core or
contrib is hugely frustrating and demotivating. Then throw in a "wtf?
why isn't this working in the stable release" only makes it more so
when I'm looking at the wrong docs and didn't even know that there
were versioned docs.

If you want an example of the kind of structure that I do find
helpful, look at docs.python.org. How many times on that page do you
see that you're lookin at the 2.6 docs and that there are links to
others? I'm not saying to make an exact clone, but I think it is fair,
if I am going to complain about this, that I also provide, at least,
an example of something that works and has worked well for years. (I
come to clojure from Lisp and Python, not Java, so I don't have any
Java documentation familiarity to compare/contrast).

[Tom Faulhaber]

Hi all,

(For those who don't know, I'm the one who maintains the autodoc API
documentation.)

There are some great suggestions here and I'll try to pick up as many
as I can. More useful branch names and having the branch in the title
are no brainers and I'll try to get them in soon.

One resource to use is the index included with each API. (See the
index link in the left sidebar.) This has every function, macro and
var in the whole library with a snippet of their doc. I find this to
be pretty useful sometimes, especially when I don't remember which
namespace something's in. I've always wished the Python doc had this
feature!

A couple things I've also been thinking about are building in a search
capability and building a "super-index" of not only core and contrib
but various other external libraries that would link back to their
doc.

Please also understand that Clojure is a young language and things are
still very much under development. We're still understanding what our
"best practice" is and how to approach it. As you point out,
clojure.contrib.io is an example where we're not there yet, but it is
happening. clojure.contrib.io is a precursor for a clojure.io
namespace that will unify these things.

Thanks for the ideas! Keep 'em coming.

Tom

> there is the distinction betweenhttp://clojure.org/librariesand the  

[Glen Stampoultzis]

On Thursday, April 22, 2010, Tom Faulhaber <tomfau...@gmail.com> wrote:

>
> A couple things I've also been thinking about are building in a search
> capability and building a "super-index" of not only core and contrib
> but various other external libraries that would link back to their
> doc.

I think building a super index is a great idea and would be very
useful. The current indexes are great because you can easily search
for a function on one page. Anything that reduces the number of pages
you need to visit to find stuff is useful in my opinion.

The ultimate would be something that let's users contribute their own
comments but that may be going beyond the scope of what you want
autodoc to be.

[Douglas Philips]

On 2010 Apr 21, at 5:04 PM, Tom Faulhaber wrote:
> (For those who don't know, I'm the one who maintains the autodoc API
> documentation.)

Cool, thank you!

> One resource to use is the index included with each API. (See the
> index link in the left sidebar.)

I saw that, but you know, after finding out that "Branches" and
"Overview" and "Namespaces" don't do anything, I had just assumed that
"API Index" didn't do anything either; based on clicking those headers
when first landing on the contrib page. Sigh.

> This has every function, macro and
> var in the whole library with a snippet of their doc. I find this to
> be pretty useful sometimes, especially when I don't remember which
> namespace something's in. I've always wished the Python doc had this
> feature!

Python does come close: http://docs.python.org/genindex-all.html
(It takes a few clicks from the main docs page: library -> index ->
full-index-on-one-page.
It does show you the library location, but not any part of the
individual documentation.)
(I'm used to using the Python 2.4 docs since my day job situation uses
that older version:
http://docs.python.org/release/2.4.4/lib/genindex.html)

> A couple things I've also been thinking about are building in a search
> capability and building a "super-index" of not only core and contrib
> but various other external libraries that would link back to their
> doc.

Having one index that spans the core and the contrib library would be
a huge step forward.
Adding in other stuff would be cool, but I would hope that would not
delay work unifying core/contrib.

> Please also understand that Clojure is a young language and things are
> still very much under development.

Yup.

> We're still understanding what our
> "best practice" is and how to approach it. As you point out,
> clojure.contrib.io is an example where we're not there yet, but it is
> happening. clojure.contrib.io is a precursor for a clojure.io
> namespace that will unify these things.

Looking at the clojure.org front page, there is no "roadmap" link, or
anything that seems to be like that, to know what is on the radar,
etc. The "news" link points to: http://clojure.blogspot.com/ but that
seems to be a few months old. Clicking through the 'dev' link and
bouncing around, I eventually found:
http://www.assembla.com/spaces/clojure/milestones/149827-release-1-2
and it seems that there are only a handful of issues to be resolved
before 1.2 is cut?
Poking around a bit more, I found bug 282 having to do with fixing the
already changed duck-streams to io in test comments. Maybe I missed
some other link(s) that would show a higher level view of what is
planned?

> Thanks for the ideas! Keep 'em coming.

Thank you for listening.

[Alex Osborne]

Douglas Philips <dg...@mac.com> writes:

> Looking at the clojure.org front page, there is no "roadmap" link, or
> anything that seems to be like that, to know what is on the radar,

There's no formal roadmap as such, most open-source projects just don't
tend to work that way.

Working notes and ideas are often posted in the assembla wiki, which
should give you a reasonable idea of the larger things that are possibly
upcoming.

http://www.assembla.com/spaces/clojure/wiki

There's also a todo list which is good for getting a feel of
Rich's long term intentions. Be aware that these are Rich's ideas, not
a plan as such and some of them may have even already been scrapped
(like streams).

http://clojure.org/todo

> bouncing around, I eventually found:
> http://www.assembla.com/spaces/clojure/milestones/149827-release-1-2
> and it seems that there are only a handful of issues to be resolved
> before 1.2 is cut?

The assembla milestone is probably fairly indicative, but not
exhaustive. The impression I have is also that there's not a huge
amount more going into 1.2, mainly finishing off the last little bits
and testing what's already been put in.

As you probably know the most high profile addition to 1.2 are datatypes
and protocols. Rich yesterday posted some new documentation on them.
They've been revised quite a bit since the initial announcement, so the
new documents are worth a look:

http://clojure.org/datatypes
http://clojure.org/protocols

> Maybe I missed some other link(s) that would show a higher level view
> of what is planned?

A lot of discussion happens on the clojure-dev group and through IRC
(#clojure on freenode). You'll need to have submitted a CA to join
the dev group, but everyone can read it through the web interface:

http://groups.google.com/group/clojure-dev

For example, the discussion about some of the renaming happening in
contrib is in these threads:

http://groups.google.com/group/clojure-dev/browse_thread/thread/d7ada6ee885aa9d4
http://groups.google.com/group/clojure-dev/browse_thread/thread/49068754a8c2efb9
http://groups.google.com/group/clojure-dev/browse_thread/thread/b4acea9c95a9cfe9

[Neal]

Stu,

Good book!

It was pretty clear to me that it was a snapshot. It was really a
user error on my part. Now that I have made that error, I won't make
it again.

Thanks,
Neal

On Apr 21, 9:31 am, Stuart Halloway <stuart.hallo...@gmail.com> wrote:
> The second level header tells you the branch (e.g. master). On the  
> left hand side is a list of branches (so you can click on e.g. 1.1.x).
>
> Some ways I see this might be better:
>
> (1) make clear what master currently equals (right now it is 1.2 alpha)
> (2) highlight the branch info more with css
> (3) push the branch info into the top-level header (and page title)
> (4) The overview section for c.c.io could tell about the lineage back  
> to 1.1.
>
> Which of these (or what else?) would have helped you the most?
>
> Stu
>
>
>
>
>
> > On 2010 Apr 21, at 8:11 AM, Alex Osborne wrote:
> >> I suggest you use the stable 1.1 releases of both Clojure and contrib
> >> for your initial learning as it will better match the book.  When  
> >> 1.2 is
> >> released stable I'm sure there will be a document written that  
> >> explains
> >> the differences.
>
> > That isn't as helpful as you might think.
>
> > (I'm using 1.1, as conveniently provided by macports.)
>

> > Nothing that I can find on either clojure.org or the contrib sitehttp://richhickey.github.com/clojure-contrib/

> >  says what version it is/applies-to.
>
> > How would I know if I'm using the stable 1.1 release that I need to  
> > replace clojure.contrib.seq with clojure.contrib.seq-utils, or  
> > clojure.contrib.io with clojure.contrib.duck-stream?
>

> >http://richhickey.github.com/clojure-contrib/io-api.htmldoesn't say:

> >   This document applies to 1.2 (pending), for 1.1 or older see: <url>
> > nor:
> >   This document applies to 1.2 (pending), it was renamed from  
> > clojure.contrib.duck-stream
>
> > --Doug
>
> > --
> > You received this message because you are subscribed to the Google
> > Groups "Clojure" group.
> > To post to this group, send email to clo...@googlegroups.com
> > Note that posts from new members are moderated - please be patient  
> > with your first post.
> > To unsubscribe from this group, send email to
> > clojure+u...@googlegroups.com
> > For more options, visit this group at
> >http://groups.google.com/group/clojure?hl=en
>
> --
> You received this message because you are subscribed to the Google
> Groups "Clojure" group.
> To post to this group, send email to clo...@googlegroups.com
> Note that posts from new members are moderated - please be patient with your first post.
> To unsubscribe from this group, send email to
> clojure+u...@googlegroups.com

> For more options, visit this group athttp://groups.google.com/group/clojure?hl=en

[Neal]

OK. Thanks everyone for your help.
Neal


On Apr 21, 8:11 am, Alex Osborne <a...@meshy.org> wrote:
> Hi Neal,

>
> Neal <neal_degrego...@yahoo.com> writes:
> > I'm trying to use duck-streams, but it is missing from the clojure-
> > contrib JAR file (at least in build #81).  I have listed the contents
> > of the JAR file and confirmed that it is not in there.
>
> It sounds like you're using a 1.2 pre-release snapshot build of
> clojure-contrib.  There's currently some refactoring going on to better
> organize contrib, now that it's a little more mature.  Most of
> clojure.contrib.duck-streams has now become clojure.contrib.io.
>
> I suggest you use the stable 1.1 releases of both Clojure and contrib
> for your initial learning as it will better match the book.  When 1.2 is
> released stable I'm sure there will be a document written that explains
> the differences.
>
> I really wish the 1.1.0 release builds were more prominently linked on
> the clojure.org website, but you can download them here:
>

> http://build.clojure.org/releases/org/clojure/clojure/1.1.0/clojure-1...http://build.clojure.org/releases/org/clojure/clojure-contrib/1.1.0/c...

[Neal]

Alex,

Yes. I was using the snapshot. My bad.

Neal


On Apr 21, 8:11 am, Alex Osborne <a...@meshy.org> wrote:
> Hi Neal,
>

> Neal <neal_degrego...@yahoo.com> writes:
> > I'm trying to use duck-streams, but it is missing from the clojure-
> > contrib JAR file (at least in build #81).  I have listed the contents
> > of the JAR file and confirmed that it is not in there.
>
> It sounds like you're using a 1.2 pre-release snapshot build of
> clojure-contrib.  There's currently some refactoring going on to better
> organize contrib, now that it's a little more mature.  Most of
> clojure.contrib.duck-streams has now become clojure.contrib.io.
>
> I suggest you use the stable 1.1 releases of both Clojure and contrib
> for your initial learning as it will better match the book.  When 1.2 is
> released stable I'm sure there will be a document written that explains
> the differences.
>
> I really wish the 1.1.0 release builds were more prominently linked on
> the clojure.org website, but you can download them here:
>

> http://build.clojure.org/releases/org/clojure/clojure/1.1.0/clojure-1...http://build.clojure.org/releases/org/clojure/clojure-contrib/1.1.0/c...