From ruby-talk-admin@ruby-lang.org Fri Dec 16 03:01:50 2005 Received: from kankan.nagaokaut.ac.jp (kankan.nagaokaut.ac.jp [133.44.2.24]) by blade.nagaokaut.ac.jp (8.12.3/8.12.3/Debian-6.6) with ESMTP id jBFI1oZk030456; Fri, 16 Dec 2005 03:01:50 +0900 Received: from funfun.nagaokaut.ac.jp (funfun.nagaokaut.ac.jp [133.44.2.201]) by kankan.nagaokaut.ac.jp (Postfix) with ESMTP id 4C8325ACA; Fri, 16 Dec 2005 03:01:55 +0900 (JST) Received: from localhost (localhost.nagaokaut.ac.jp [127.0.0.1]) by funfun.nagaokaut.ac.jp (Postfix) with ESMTP id 67068F04850; Fri, 16 Dec 2005 03:01:55 +0900 (JST) Received: from voscc.nagaokaut.ac.jp (voscc.nagaokaut.ac.jp [133.44.1.100]) by funfun.nagaokaut.ac.jp (Postfix) with ESMTP id 2D3FBF0484A; Fri, 16 Dec 2005 03:01:54 +0900 (JST) Received: from beryllium.ruby-lang.org (beryllium.ruby-lang.org [210.163.138.100]) by voscc.nagaokaut.ac.jp (Postfix) with ESMTP id 38BB0630024; Fri, 16 Dec 2005 03:01:54 +0900 (JST) Received: from beryllium.ruby-lang.org (beryllium.ruby-lang.org [127.0.0.1]) by beryllium.ruby-lang.org (Postfix) with ESMTP id 377CC33F32; Fri, 16 Dec 2005 03:01:19 +0900 (JST) Received: from localhost (beryllium.ruby-lang.org [127.0.0.1]) by beryllium.ruby-lang.org (Postfix) with ESMTP id 8BF0933F87 for ; Fri, 16 Dec 2005 03:01:06 +0900 (JST) Received: from beryllium.ruby-lang.org ([127.0.0.1]) by localhost (beryllium.ruby-lang.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 17447-07 for ; Fri, 16 Dec 2005 03:01:06 +0900 (JST) Received: from pop-cowbird.atl.sa.earthlink.net (pop-cowbird.atl.sa.earthlink.net [207.69.195.68]) by beryllium.ruby-lang.org (Postfix) with ESMTP id B7B0833F80 for ; Fri, 16 Dec 2005 03:01:03 +0900 (JST) Received: from dialup-4.238.19.83.dial1.orlando1.level3.net ([4.238.19.83] helo=mydesk.domain.cxm) by pop-cowbird.atl.sa.earthlink.net with esmtp (Exim 3.36 #10) id 1EmxPU-0001CI-00 for ruby-talk@ruby-lang.org; Thu, 15 Dec 2005 13:00:56 -0500 Delivered-To: ruby-talk@ruby-lang.org Date: Fri, 16 Dec 2005 03:01:08 +0900 Posted: Thu, 15 Dec 2005 13:01:55 -0500 From: Steve Litt Reply-To: ruby-talk@ruby-lang.org Subject: Re: GetoptLong example To: ruby-talk@ruby-lang.org (ruby-talk ML) Message-Id: <200512151301.55491.slitt@earthlink.net> In-Reply-To: <5cd596d60512150705n273e0af8yb39817265d9612ad@mail.gmail.com> References: <200512141939.34072.slitt@earthlink.net> <200512150847.55896.slitt@earthlink.net> <5cd596d60512150705n273e0af8yb39817265d9612ad@mail.gmail.com> X-ML-Name: ruby-talk X-Mail-Count: 89 X-MLServer: fml [fml 4.0.3 release (20011202/4.0.3)]; post only (only members can post) X-ML-Info: If you have a question, send e-mail with the body "help" (without quotes) to the address ruby-talk-ctl@ruby-lang.org; help= User-Agent: KMail/1.6.1 X-Original-To: ruby-talk@ruby-lang.org Organization: Troubleshooters.com Content-Disposition: inline X-Virus-Scanned: by amavisd-new-20030616-p10 (Debian) at ruby-lang.org X-Spam-Checker-Version: SpamAssassin 3.0.3 (2005-04-27) on beryllium.ruby-lang.org X-Spam-Level: X-Spam-Status: No, score=-14.1 required=7.0 tests=AWL,BAYES_00,BLARS00, BLARS_SPAM00,CONTENT_TYPE_PRESENT,RCVDFRMLOCALIP,RCVD_IN_BLARS, RCVD_IN_BLARS_HOOPS,RCVD_IN_BLARS_SPAM autolearn=ham version=3.0.3 Mime-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit Precedence: bulk Lines: 77 List-Id: ruby-talk.ruby-lang.org List-Software: fml [fml 4.0.3 release (20011202/4.0.3)] List-Post: List-Owner: List-Help: List-Unsubscribe: X-Virus-Scanned: by AMaViS snapshot-20020531 On Thursday 15 December 2005 10:06 am, Jim Freeze wrote: > Hi Steve > > On 12/15/05, Steve Litt wrote: > > I came across OptionParser. I tried reading the documentation, > > but I saw no simple proof of concept to get me started. I > > therefore opted for GetoptLong. At least it's not a total > > stranger, I've used it in C and Perl. > > > > Perhaps I just came across the wrong documentation. > > > > I'd like to have the OptionParser documentation contain a proof > > of concept, and a couple more examples that follow logically, > > without skipping steps. > > Is this the documentation that you are referring to that needs > improvement: > > > http://rubyforge.org/docman/view.php/632/233/posted-docs.index.ht >ml > > Please help me out and post some comments on what you like and > don't like. I am still making improvements in the docs. Hi Jim, I'm pretty sure those are the docs I couldn't fathom. IMHO what you need is a quickstart -- all code, no theory. Start with the simplest possible program that the user can paste into his editor and then give him the command line to run, and show the expected output. I think the idea is to get the user to say "hey, I can do this". Once he's hooked, he has incentive to dig into the incredibly rich array of tools you offer. Personally, when I write documentation on Troubleshooters.Com, I always start with a "Hello World" and then, one feature at a time, I move from the known to the unknown (my wife's a teacher :-). Another thing. I usually show full programs (in blue background) so the user can paste them into his editor and run them immediately, and then the expected results in yellow background so the user can compare his results to the expected results. Once the user sees both the code and the results, he can then figure out why it works like it does, and he can also experiment with the code to learn even more. For an example of how I write my documentation, see this: http://www.troubleshooters.com/codecorn/ruby/basictutorial.htm Please keep in mind that I'm displaying this as an example of my documentation methods, not as an example of particularly good Ruby documentation. I wrote most of this material with less than a week's Ruby experience, and before I signed up with this mailing list. In fact, a companion document called "Ruby the Right Way" was my reason for my "They say I write Ruby like Perl" post. If any of you have the book "Samba Unleashed", the chapters with my name on them are another good example of my documentation methods. In summary -- IMHO a quickstart would be the catalyst to greater acceptance of OptionParser. Use whole but tiny programs, without error checking and the like, to make your points. That way the user can cut and paste right onto his box and follow your examples on his own. Within 10 minutes the user understands the power of OptionParser and is ready to learn more. Thanks SteveT Steve Litt http://www.troubleshooters.com slitt@troubleshooters.com