From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Christopher Allan Webber Newsgroups: gmane.lisp.guile.devel Subject: Re: Ideas for a Guile tutorial to go with the new site Date: Wed, 16 Dec 2015 08:33:30 -0600 Message-ID: <878u4umolr.fsf@dustycloud.org> References: <87k2qkjh74.fsf@dustycloud.org> <87egenmp2v.fsf@dustycloud.org> <87zixahean.fsf@gmail.com> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1450277646 602 80.91.229.3 (16 Dec 2015 14:54:06 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Wed, 16 Dec 2015 14:54:06 +0000 (UTC) Cc: guile-devel To: alex.sassmannshausen@gmail.com Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Wed Dec 16 15:54:05 2015 Return-path: Envelope-to: guile-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1a9DSh-0006Tj-O7 for guile-devel@m.gmane.org; Wed, 16 Dec 2015 15:53:51 +0100 Original-Received: from localhost ([::1]:47762 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9DSh-0002hy-1J for guile-devel@m.gmane.org; Wed, 16 Dec 2015 09:53:51 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:38926) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9DSe-0002he-2S for guile-devel@gnu.org; Wed, 16 Dec 2015 09:53:49 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1a9DSa-0001Uz-12 for guile-devel@gnu.org; Wed, 16 Dec 2015 09:53:48 -0500 Original-Received: from dustycloud.org ([2600:3c02::f03c:91ff:feae:cb51]:38652) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9DSZ-0001Ur-SV for guile-devel@gnu.org; Wed, 16 Dec 2015 09:53:43 -0500 Original-Received: from earlgrey (localhost [127.0.0.1]) by dustycloud.org (Postfix) with ESMTPS id 7C6EA26799; Wed, 16 Dec 2015 09:53:42 -0500 (EST) In-reply-to: <87zixahean.fsf@gmail.com> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2600:3c02::f03c:91ff:feae:cb51 X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Developers list for Guile, the GNU extensibility library" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Original-Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.devel:18097 Archived-At: Alex Sassmannshausen writes: > That's looking pretty good. Personally I'm not sure about the > positioning of the bit about text editors =E2=80=94 it feels like it is= a little > tangential to getting Guile up and running. It feels like perhaps it > should be mentioned later (e.g. when you actually mention storing stuff > in a .scm file? > > (also, it kind of acts as a mental barrier to just firing up Guile and > having a go =E2=80=94 which is, I think, the playful feeling you want t= o instil > in your readership?) I think you're right probably. I tried to make it an "optional" section. On the other hand, realizing why Guile is really nice to work in requires having a pretty decent setup, so it might be worth the time investment to mention it there. I'm not sure yet... I think maybe once more content has come after it, we can re-evaluate and refactor. Would that make sense? For now, I've broken up the editor and readline part into its own clearly marked as "optional" section. > I definitely still think this is a really cool way to go. I'd probably > think that you'll want to walk a fine line between playfulness and over > the top childishness =E2=80=94 and that line will be different for diff= erent > people I guess! 8-| Yeah it will. I'll be tuning towards my own personal preferences, and hopefully that aligns with enough people. > But I think it's a cool initiative, that would have really helped me if > it had been available on the Guile website when I first started learnin= g > Guile. Yay! > As an aside, what's the best way to pass you "editorial" feedback (typo= s > and such) =E2=80=94 as git patches or as inline corrections? Either works; but git patches are nice. I tried to set up the format of documentation so that patching it should be easy while keeping the source readable. To demonstrate, here's an example: (p [You also might build up some fun toys while running through this tutorial. You might want to play with them and re-use them without having to type them in all over again. This is where your text editor comes into play! Try opening a new file, we'll call it "sandbox.scm". When you build something in this tutorial you'd like to use over and over again without retyping it between REPL sessions, you can put it here. Let's try putting something there now:]) What you'll notice is that each new sentence starts on its own line. Sentences which have characters which continue beyond line 79 "wrap", but are indented to be clear that they align with a previous sentence. This is an unusual convention, but I think a sane one: my usual temptation is to use emacs' fill-paragraph technique to keep things looking nice in plaintext, but that can entirely rearrange paragraphs, and in my experience makes merging changes hard. I heard the recommendation a while ago that keeping a sentence on its own line is a better way to go for version-controlled documentation, but usually that ends up flying off beyond column 80, and I hate that. So the above approach merges the two. That seems like useful information to document, so I'll do that now. :) Patches welcome. Please include an update to the copyright line including your name if you do so, and acknowledge that you're okay with it being dual licensed under the LGPL and GFDL!