Thank you for the suggestions! I have started incorporating some, more to come in the next days :-)
2014-11-22 16:58 GMT+01:00 John Benediktsson <mrj...@gmail.com>: > Hi Andrea, > > Wow, great contribution!! > > Some comments: > > You might avoid naming your factorial word "!" or at least make a small > comment to your readers that it shadows the "!" token that is used for > comments in the code (preventing its use as comments). > > IN: scratchpad ! a comment > IN: scratchpad : ! ( n -- n ) ; > IN: scratchpad ! not a comment! > > One could argue that we should use a more standard "//" or "#" like other > languages, but such is some legacy decision somewhere along the way. Might > be worth changing at some point. > > Also in that section, you might mention the breadth of the standard library, > your ``prod`` word is defined in the ``sequences`` vocabulary as > ``product``. And is possibly more efficient because it uses a binary reduce > that for large numbers keeps more of them smaller for longer, resulting in > less bignum multiplication. > > On the syntax section, it might be fun to give an example of using SYNTAX:. > I have a few on my blog to help give you some ideas: > > http://re-factor.blogspot.com/2010/08/fat-arrows.html > http://re-factor.blogspot.com/2014/06/swift-ranges.html > http://re-factor.blogspot.com/2010/07/rolling-dice.html > > It's a useful beginner lesson to teach that Factor is "tokens that parse" > and that "{" isn't just some list literal embedded in the language, but that > you can see how it works, change it, or replace it, or build it yourself as > an addon. A small exception to that might be number and string literals > which right now are built directly into the parser. > > On the github.tutorial section, I would also suggest mentioning our editor > support works for vocabularies, so for example after doing > ``scaffold-work``, you might just type: > > IN: scratchpad "github.tutorial" edit > > For new users, this will prompt with a list of editors to choose from > (rather than needing to explicitly USE: it like you do in the tutorial). > After that point, it will open the file directly in the editor. For words, > it opens the file they are defined in (``\ foo where`` if you're curious how > that works) and tries in most editors to bring the cursor to the proper line > number. > > You can also use ``"vocab" edit-tests`` to get to the tests file, ``"vocab" > edit-docs`` to open the documentation file, etc. > > When you mention ``boa`` constructors, you might also demonstrate that these > are equivalent (allowing easy generation of constructor words for the common > case): > > : <movie> ( title director actors -- movie ) movie boa ; > > C: <movie> movie > > Since Factor parses tokens between one or more whitespace characters, these > are equivalent if you prefer the second for readability: > > TUPLE: band { keyboards string read-only } { guitar string read-only } > { bass string read-only } { drums string read-only } ; > > TUPLE: band > { keyboards string read-only } > { guitar string read-only } > { bass string read-only } > { drums string read-only } ; > > For your later prime example with fry quotations, I'd also provide this > example which uses ``with`` to capture the notion of currying something > under the stack in this use case: > > : prime? ( n -- ? ) 2 over sqrt [a,b] [ divisor? ] with any? not ; > > Your ``safe-head`` word can be captured instead of using exceptions and > recover, by just doing ``short head`` which mins with length of sequence > (avoiding the exception, unless ``n`` is negative). > > Good http examples, I'd also point you to this post which shows some use of > forms and validation: > > http://re-factor.blogspot.com/2010/08/hello-web.html > > Looks like you've put a lot of effort into this and I love it, great job! > I'm going to make a post linking to this on my blog! > > Best, > John. > > > > > > > > > > > > > > > > > > On Sat, Nov 22, 2014 at 6:36 AM, Andrea Ferretti <ferrettiand...@gmail.com> > wrote: >> >> Hello, >> >> I have written a Factor tutorial, which you can find at >> >> http://andreaferretti.github.io/factor-tutorial/ >> >> (source https://github.com/andreaferretti/factor-tutorial ) >> >> Factor has a lot of documentation in the listener, but I have tried to >> cover some topics that are present in the official docs, but scattered >> throughout it, so that they were not clear to me at the beginning. >> These include for instance: >> >> - the central concept is function composition, the stack is more of a >> detail >> - how simple is to deploy program and scripts >> - what tools are there: linter, inspector, unit testing support, >> reverse lookup of function uses... >> - what model of multithreading and async I/O are used >> - how to make use of multiple cores >> - in what sense Factor has an object system >> and more >> >> I was able to answer some of those - especially multithreading - >> thanks to the help I got on this list. >> >> I am sure there are many mistakes - after all, I am still a beginner >> with Factor - and many things that can be improved, both in the >> exposition and in the choice of examples. But I wanted to get it out >> eventually, even with something to be retouched later. >> >> I intend to improve it in the future, and any suggestion is welcome - >> or even better, you can file pull requests! >> >> Best, >> Andrea >> >> >> ------------------------------------------------------------------------------ >> Download BIRT iHub F-Type - The Free Enterprise-Grade BIRT Server >> from Actuate! Instantly Supercharge Your Business Reports and Dashboards >> with Interactivity, Sharing, Native Excel Exports, App Integration & more >> Get technology previously reserved for billion-dollar corporations, FREE >> >> http://pubads.g.doubleclick.net/gampad/clk?id=157005751&iu=/4140/ostg.clktrk >> _______________________________________________ >> Factor-talk mailing list >> Factor-talk@lists.sourceforge.net >> https://lists.sourceforge.net/lists/listinfo/factor-talk > > > > ------------------------------------------------------------------------------ > Download BIRT iHub F-Type - The Free Enterprise-Grade BIRT Server > from Actuate! Instantly Supercharge Your Business Reports and Dashboards > with Interactivity, Sharing, Native Excel Exports, App Integration & more > Get technology previously reserved for billion-dollar corporations, FREE > http://pubads.g.doubleclick.net/gampad/clk?id=157005751&iu=/4140/ostg.clktrk > _______________________________________________ > Factor-talk mailing list > Factor-talk@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/factor-talk > ------------------------------------------------------------------------------ Download BIRT iHub F-Type - The Free Enterprise-Grade BIRT Server from Actuate! Instantly Supercharge Your Business Reports and Dashboards with Interactivity, Sharing, Native Excel Exports, App Integration & more Get technology previously reserved for billion-dollar corporations, FREE http://pubads.g.doubleclick.net/gampad/clk?id=157005751&iu=/4140/ostg.clktrk _______________________________________________ Factor-talk mailing list Factor-talk@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/factor-talk
