<div dir="ltr">I would disagree that most people are lazy readers in this case.&nbsp; I personally have skimmed the entire Scribble manual and read the @-reader part in detail and I couldn&#39;t figure it out.&nbsp; The same with tables.&nbsp; It certainly isn&#39;t obvious that the only way to actually make a table is to literally call make-table with all of its vagaries and getting exactly the right (listof (listof ...)) figured out without an example.&nbsp; [And, the examples we do find are often obscured behind a level of abstraction that we in turn have to figure out.&nbsp; It might be good coding, but not so good as an example.]<br>
<br>I also know that things take time and I&#39;m sure we&#39;ll have a Scribble Guide and better examples over time.&nbsp; And, I do appreciate the quick responses I tend to get on the list.<br><br>There are many of us with PLaneT packages who are trying to catch up with Version 4.0.&nbsp; I&#39;m pretty much there except for the documentation and it has been rough going for complex collections.&nbsp; I think the thing that would have helped the most is for someone to show us a canonical PLaneT package, with documentation, that you guys have looked over and said, &quot;Yes, that&#39;s the right way to do it.&quot;<br>
<br>Doug<br><br>P.S.&nbsp; Please understand that all of this is indended as constructive criticism.&nbsp; We&#39;re all trying to improve the tools we have/provide.<br><br><div class="gmail_quote">On Thu, Sep 11, 2008 at 7:22 PM, Eli Barzilay <span dir="ltr">&lt;<a href="mailto:eli@barzilay.org">eli@barzilay.org</a>&gt;</span> wrote:<br>
<blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><div class="Ih2E3d">On Sep 11, Jay McCarthy wrote:<br>
</div><div class="Ih2E3d">&gt; On Thu, Sep 11, 2008 at 7:08 PM, Eli Barzilay &lt;<a href="mailto:eli@barzilay.org">eli@barzilay.org</a>&gt; wrote:<br>
</div><div class="Ih2E3d">&gt; &gt; There&#39;s this example, which is pretty explicit:<br>
&gt; &gt;<br>
&gt; &gt; &nbsp;@foo{The prefix: @&quot;@&quot;.} &nbsp; &nbsp; reads as &nbsp;(foo &quot;The prefix: @.&quot;)<br>
&gt;<br>
&gt; Now that you show them, these should have helped me a lot. But as I<br>
&gt; read through I saw @foo and said, &quot;But I&#39;m not writing a call or<br>
&gt; something inside a call, ignore it.&quot; If I were an extreme reader, I<br>
&gt; should have noticed. But I&#39;m lazy documentation reader and didn&#39;t<br>
&gt; see it. (In fact, I&#39;m sure its been there the last 6 or 7 times I&#39;ve<br>
&gt; tried to remember this and I&#39;ve missed it every time.)<br>
<br>
</div>(Yes it has, the whole thing didn&#39;t change much since it was in<br>
doc.txt form. &nbsp;But the fact that you missed it so many times is what<br>
makes me think that there&#39;s a problem in the current organization of<br>
the text.)<br>
<div class="Ih2E3d"><br>
&gt; Clearly something is wrong, but it&#39;s probably me. Forgive my honesty<br>
&gt; :)<br>
<br>
</div>Well, I think that most people are lazy readers when it comes to<br>
reference manuals. &nbsp;You want to get to the point that gives you what<br>
you want. &nbsp;Since the reader chapter reads almost like a story with<br>
lots of examples, I think that a simpler &quot;quick intro&quot; paragraph will<br>
be a good thing.<br>
<div><div></div><div class="Wj3C7c"><br>
--<br>
 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;((lambda (x) (x x)) (lambda (x) (x x))) &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;Eli Barzilay:<br>
 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;<a href="http://www.barzilay.org/" target="_blank">http://www.barzilay.org/</a> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; Maze is Life!<br>
</div></div></blockquote></div><br></div>