clojure.org to-do list
Alex Miller
Sean Corfield
> than hide these away I have dumped this list here:
> http://dev.clojure.org/display/doc/clojure.org+TODO+list
That's a pretty comprehensive list Alex!
A couple of things jumped out at me that I thought were worth getting feedback:
* I agree with most of the suggestions about navigation and grouping
items. I see you suggest keeping the Google Group and IRC links in the
top right but I wonder if putting a "Community" link up there and
grouping all the community resources together (on the community page)
makes more sense - with the "community support" stuff at the top
(mailing list, IRC details etc). That seems to be common with other
language sites (or at least ones I've dealt with recently).
* Getting started... The current getting started page dives into
github and the CLR port and the wiki... without actually explaining
how to download and install Clojure. Further down your TODO list, you
mention that namespaces come up pretty much as soon as you start
writing Clojure (which is true - and intimidating to many, depending
on their background). I wonder if we can do something about the
Getting Started experience that makes for an easier on-ramp as well as
dealing with the namespace stuff in a gentle manner?
I've had really good lucky getting people started with Leiningen: it
handles the download / dependency / classpath stuff automatically, it
handles the namespace issue (by creating project trees for you) and it
encourages testing (by creating the test tree in the project). It also
makes the REPL a no-brainer.
If we want the Getting Started experience to be as painless as
possible, might we perhaps consider standardizing on a build tool of
some sort?
--
Sean A Corfield -- (904) 302-SEAN
Railo Technologies, Inc. -- http://getrailo.com/
An Architect's View -- http://corfield.org/
"If you're not annoying somebody, you're not really alive."
-- Margaret Atwood
Alex Miller
>> I also have a big list of things that I have NOT gotten around to. Rather
>> than hide these away I have dumped this list here:
>> http://dev.clojure.org/display/doc/clojure.org+TODO+list
>
> That's a pretty comprehensive list Alex!
>
> A couple of things jumped out at me that I thought were worth getting feedback:
>
> * I agree with most of the suggestions about navigation and grouping
> items. I see you suggest keeping the Google Group and IRC links in the
> top right but I wonder if putting a "Community" link up there and
> grouping all the community resources together (on the community page)
> makes more sense - with the "community support" stuff at the top
> (mailing list, IRC details etc). That seems to be common with other
> language sites (or at least ones I've dealt with recently).
That seems reasonable.
>> * Getting started... The current getting started page dives into
> github and the CLR port and the wiki... without actually explaining
> how to download and install Clojure.
Yes.
> Further down your TODO list, you
> mention that namespaces come up pretty much as soon as you start
> writing Clojure (which is true - and intimidating to many, depending
> on their background). I wonder if we can do something about the
> Getting Started experience that makes for an easier on-ramp as well as
> dealing with the namespace stuff in a gentle manner?
Colin's blog here
(http://blog.8thlight.com/articles/2010/12/6/clojure-libs-and-namespaces-require-use-import-and-ns)
is exactly what I wish I had read when I first started.
> I've had really good lucky getting people started with Leiningen: it
> handles the download / dependency / classpath stuff automatically, it
> handles the namespace issue (by creating project trees for you) and it
> encourages testing (by creating the test tree in the project). It also
> makes the REPL a no-brainer.
Yep, this also would have made my life easier when I started. I have
a deep Java background but I can imagine many of the initial steps are
mystifying if you're not coming from a JVM background.
>> If we want the Getting Started experience to be as painless as
> possible, might we perhaps consider standardizing on a build tool of
> some sort?
Don't get crazy! :) I don't think there's any need to standardize a
build tool. But I think Leiningen or Cake are great choices for the
first user creating their first project.
Sean Corfield
> Colin's blog here
> (http://blog.8thlight.com/articles/2010/12/6/clojure-libs-and-namespaces-require-use-import-and-ns)
> is exactly what I wish I had read when I first started.
Yes, and as folks can see from my comment there, I didn't understand
the interaction of :as and :only until Colin explained it to me in the
next comment!
> Don't get crazy! :) I don't think there's any need to standardize a
> build tool. But I think Leiningen or Cake are great choices for the
> first user creating their first project.
Do they perhaps warrant examples on the Getting Started page then?
Alex Miller
are pretty good (lein's mostly defers to lein) - they just need to be
more visible from the main site.
http://dev.clojure.org/display/doc/Getting+Started
Andy Fingerhut
I'm interested in at least starting to look at what would be necessary
for the items involving the cheat sheet you describe.
Unfortunately, when I tried to get the LaTeX in the .zip file, the one
that is one of the files attached to the Clojure Google group, I got
"The page you navigated to does not exist." I've tried clicking on
several other files attached to the group. All of the .zip files I
tried showed the same problem. None of the non-zip files I tried had
any problems at all. Does anyone know what might have caused that?
If someone has a copy of clojure-cheat-sheet.zip, could you send it to
me off-list?
Thanks,
Andy
Andy Fingerhut
disallowed uploading files associated with Google groups, and plans to
disallow downloading them some time this month. The suggested
replacement is to use Google Sites or Google Docs instead.
I just downloaded a .zip of "all downloadable content", but it did not
include any of the existing .zip files that are there now.
Andy
Alex Miller
> --
> You received this message because you are subscribed to the Google Groups
> "Clojure Dev" group.
> To post to this group, send email to cloju...@googlegroups.com.
> To unsubscribe from this group, send email to
> clojure-dev...@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/clojure-dev?hl=en.
>
>
Alex Miller
a link at the top of the page:
http://clojure.org/cheatsheet
The zip file download includes both the .tex and the .pdf.
Andy Fingerhut
structure. The intent is that this program could be the original
source that is maintained in the future when cheat sheet changes are
desired, and then updated HTML and PDF files with clickable links to
the on-line docs could be generated from those.
The current results can be seen here:
http://homepage.mac.com/jafingerhut/files/private/clojure/cheatsheet-v1.3.html
http://homepage.mac.com/jafingerhut/files/private/clojure/cheatsheet-v1.3.pdf
Things that work: The LaTeX file generated is nearly the same as Steve
Tayon's color version, except for some vertical whitespace
differences, and the lack of a footer.
The HTML file generated has the same HTML structure as the one at:
except I've left out the clojure.org header/footer/sidebar.
You can download the source and a shell script run.sh for generating
the output (assuming you have an appropriate LaTeX installation -- see
comments in run.sh for some MacPorts packages that worked for me on a
Mac):
http://homepage.mac.com/jafingerhut/files/private/clojure/cheatsheet-1.3.tar.gz
Things still missing:
No footer with version number, date, and attributions at the bottom.
The visual layout of my LaTeX file is a little bit different than the
existing LaTeX version 1.21. This can be tweaked.
No links yet for functions in clojure.string, clojure.set,
clojure.zip, except for a few incorrect ones for names that are also
in clojure.core.
No links from the Reader Macros section.
No links for a few other things here and there: set! catch finally new
throw-if Classname/ Classname.
Let me know if you have any suggestions for improvements that aren't
already on my "things missing" list.
Andy
Alex Miller
http://clojure.org/cheatsheet - even with some flaws, it's better than
the version that was there.
One really weird thing is that links stop being links at a horizontal
line below Strings / Letters. Any html/css guru out there know how to
track that down? This might be related to some css in
http://www.wikispaces.com/s/gz/2jqk2803-internal.css that is setting
the height of the widget containing the html in the page. But I am
just barely CSS-aware - I would appreciate any help tracking that
down.
Another big issue with the current links are that they go to the
deprecated richhickey github site. Please s/richhickey/clojure/ and
that will be fixed.
The bare html output is pretty close to what currently gets sucked
into the clojure.org wiki as embedded html. That version has this
form:
<script language="JavaScript" type="text/javascript">
//<![CDATA[
document.write('<style type="text/css"> @media screen { .page {
width: 600px; display: inline; } .gap {clear: both;} }
code { font-family: monospace; } .page { clear:
both; page-break-after: always; page-break-inside: avoid;
} .column { float: left; width: 50%; } .header {
text-align: center; } .header h2 { font-style: italic;
} h1 { font-size: 1.8em; } h2 { font-size: 1.4em;
} h3 { font-size: 1.2em; } .section { margin:
0.5em; padding: 0.5em; padding-top: 0;
background-color: #ebebeb; } table { width: 100%;
border-collapse: collapse; } td, .single_row { padding: 0
0.5em; vertical-align: top; } tr.odd, .single_row {
background-color: #f5f5f5; } tr.even { background-color:
#fafafa; } .footer { float: right; text-align: right;
border-top: 1px solid gray; } #foot {clear: both;} <\/style>')
//]]>
</script>
<div class="page">
...
</div>
so it's pretty close to what you're generating. If you could generate
this embeddable version as well, that would minimize the chance for
error when moving it into the wiki.
Alex
Tom Hickey
I put in a workaround for the issue with the links not being
functional lower on the page. The fix only works if you're not logged
in as a wikispaces member (I didn't have time yesterday to get it
working in both cases, but figured this would cater for the general
use case).
Cheers,
Tom
On Feb 21, 2:56 pm, Alex Miller <a...@puredanger.com> wrote:
> This looks GREAT Andy! In fact, I uploaded it tohttp://clojure.org/cheatsheet- even with some flaws, it's better than
>
> One really weird thing is that links stop being links at a horizontal
> line below Strings / Letters. Any html/css guru out there know how to
> >http://homepage.mac.com/jafingerhut/files/private/clojure/cheatsheet-...
> > Things that work: The LaTeX file generated is nearly the same as Steve
> > Tayon's color version, except for some vertical whitespace differences, and
> > the lack of a footer.
>
> > The HTML file generated has the same HTML structure as the one at:
>
> >http://clojure.org/cheatsheet
>
> > except I've left out the clojure.org header/footer/sidebar.
>
> > You can download the source and a shell script run.sh for generating the
> > output (assuming you have an appropriate LaTeX installation -- see comments
> > in run.sh for some MacPorts packages that worked for me on a Mac):
>
Mark Engelberg
misclassified under transients:
All the 'Change' and Iteration constructs were probably meant to be
under a different header.
Andy Fingerhut
I wasn't attempting to change the contents of this table at all yet, except for a few things I found that were apparently obsolete (e.g. nthrest and rfirst I'm guessing existed at one time in the past, but no longer -- they were included in the version I generated that Alex Miller published most recently, but not in the patch for CLJ-758).
http://dev.clojure.org/jira/browse/CLJ-758
If people have recommendations for changing it, it is now more straightforward to update the HTML and LaTeX/PDF consistently with each other. It looks like the functions in the 'Change' category for transients are the same as the 'Change' category for Sequences / Seq in, Seq out. Many functions occur in more than one place in the sheet, but you are right that it doesn't make any sense to have those under transients, since those functions give errors when attempted on a transient data structure.
Perhaps the best thing would be to remove the 'Change' and Iterate categories completely under Transients? All of the functions mentioned there also seem to be mentioned in appropriate places elsewhere in the table.
Thanks,
Andy