[ANN] Learn to Program -- A Tutorial for the Future Programmer

ruby-talk
1

I finally finished it! I received a great deal of encouragement this last
month, so I made that push, and it’s done. Yes, it took me a sesqui-year to
finish, but we had a baby during that time, and it threw things off for a
while.

It has also been moved to a new (and permanent) space:

http://pine.fm/LearnToProgram/

What is it? It’s a tutorial for teaching programming (using Ruby, of
course) to the non-programmer. It has been tested on several
non-programmers, and it seems to be a success. Also, all of the code
examples are executed every time the page is loaded, and the output (and
possibly scripted user input) are captured and displayed as well, so the
parts with rand' or withTime.now’ are dynamic!

If you get a chance, I’d love to hear any comments/corrections you might
have.

If you linked to the old tutorial, please update your links.

If you know of anyone interested in programming, but not knowing where to
begin, point them to this tutorial and let me know how it goes!

Hope you like it,

Chris

2

Chris Pine wrote:

http://pine.fm/LearnToProgram/
Hope you like it,

Definitely. This is very nice and I’m sure I’ll use it in the future –
are there any plans for translations yet? I could maybe do one to German.

Oh, and in chapter 4 where you’re referring to the inaccurateness of
Floats the example shows the precisely correct -8.05. Maybe it would be
better to move this hint to the “More Arithmetic” section in Chapter 5?

More nitpicking:

In Chapter 5:

  • “(I added the parenthases to the other lines to get rid of all the
    warnings it was giving me.)” – Typo
  • “One thing to be wary of, though: rand will complain if you try to
    give it a number greater than 2147483647 (which happens to be 2**31 -
    1).” – This seems to have been fixed. (Works in 1.8.1 for me.)

In Chapter 10:

  • You’re doing this:
    isEven = !isEven # Toggle from even to odd, or odd to even.
    You haven’t explained “!”, but you did explain “not”. (And “not” does
    also look better IMHO.) So it would probably be better to use “not”
    instead.

Comments seem to be a bit hard to read. (They’re white on gray.)

Regards,
Florian Gross

3

Hi!

  • Florian Gross:

Chris Pine wrote:

http://pine.fm/LearnToProgram/
Hope you like it,

Definitely. This is very nice and I’m sure I’ll use it in the
future – are there any plans for translations yet? I could maybe
do one to German.

Companies like an infamous one with US HQ near Seattle and DE HQ near
Munich use a three-step process for translation:

  1. Doing a translation.

  2. Reviewing if technical description is okay (differences result
    from different language versions having different interfaces,
    different bugs, missing features, etc.).

  3. Reviewing language style (involves contacting those involved in
    step 3)

I have done 1 and 2 (mostly texts of that infamous company) - always
with the tendency to remove the most annoying style issues.

Would it be okay if I do 1 (IMO that’s the hard task) then you do
step 2 and step 3 and contact me if you don’t understand my
translation.

Iterate with exchanged roles as long as necessary (fortunately we
don’t have the same restrictions a company has :-).

If that’s okay I start translation after positive feedback.

Josef ‘Jupp’ SCHUGT

···

–
E-Mail: .— …- .–. .–. .–.-. --. – -…- .-.-.- -… .
http://oss.erdfunkstelle.de/ruby/ - German comp.lang.ruby FAQ
http://rubyforge.org/users/jupp/ - Ruby projects at Rubyforge

4

Thanks for the nitpicking!

All fixed.

Every time I update Ruby on my server, things break (and “broken” things,
like rand, get fixed), and it’s hard to find every problem.

On the one hand, this is a wonderful thing, because the tutorial is always
totally relevant. On the other hand, it’s a bit of a pain.

Thanks for taking a look at it.

Chris

5

On a German Translation:

···

===============================================

You can get the code which generates every page in the tutorial here:

http://pine.fm/LearnToProgram/?ShowTutorialCode=true

It’s all just one gigantic program. As far as translation is concerned, I
wouldn’t know where to start. In the games I have worked on, we separate
all of the text into a few files and just translate those. Here, though,
the text is almost the whole program.

Also, because all of the code is live, I have to make changes all over every
time I update Ruby on my server. I wouldn’t be able to do the same in
German (though maybe my wife could; she is not a native speaker, but she is
fluent in German).

If you want, you may certainly take all of the code and maintain your own
version of it. (All I ask is that you provide a clear link to the
original.)

You need Apache set up to allow you to execute *.rbx files.

The tutorial consists of five files:

http://pine.fm/LearnToProgram/index.rbx
http://pine.fm/LearnToProgram/PoweredByRuby.png
http://pine.fm/LearnToProgram/ruby.properties
http://pine.fm/LearnToProgram/SciTEGlobal.properties
http://pine.fm/LearnToProgram/tutorial.css

That’s it!

So would anyone like to maintain a German site yourself? I would, of
course, link to it from my front page. Or, looking at my code, is there
something I could do to make translation easier?

Chris

6

Hi!

  • Chris Pine:

It’s all just one gigantic program. As far as translation is
concerned, I wouldn’t know where to start.

Porting Trados to Linxu perhaps >;->

In the games I have worked on, we separate all of the text into a
few files and just translate those. Here, though, the text is
almost the whole program.

As long as you know where the strings occur in the software that
works quite fine but if you only have the strings that ain’t funny.

Also, because all of the code is live, I have to make changes all
over every time I update Ruby on my server. I wouldn’t be able to
do the same in German (though maybe my wife could; she is not a
native speaker, but she is fluent in German).

If all the text is in one location that can be downloaded this no
problem. Download a snapshot, translate it, download new snapshot,
find differences, update translation, redo.

If you want, you may certainly take all of the code and maintain
your own version of it. (All I ask is that you provide a clear
link to the original.)

I will take a closer look at the source.

So would anyone like to maintain a German site yourself? I would,
of course, link to it from my front page.

I’ll ask the guy who hosts the German comp.lang.ruby FAQ to host
this. But first some translation must be done.

One step after another.

Josef ‘Jupp’ SCHUGT

···

–
E-Mail: .— …- .–. .–. .–.-. --. – -…- .-.-.- -… .
http://oss.erdfunkstelle.de/ruby/ - German comp.lang.ruby FAQ
http://rubyforge.org/users/jupp/ - Ruby projects at Rubyforge

7

Hi!

I think it makes sense to have a handy abbreviation for ‘Learn to
Program’. L2P seems appropriate.

  • Chris Pine:

You need Apache set up to allow you to execute *.rbx files.

I’m using thttpd. It runs anything that is marked world executable
and matches a CGI-specifying regexp. Cute feature :->

BTW: I would love to see that someone explains to me how to make
index.rbx a default start page for thttpd. I presently use this as a
workaround:

go ahead...

This issue does not have high priority because the above works good
enough and the intended target system is running Apache.

Let’s come to the BUTs. It seems as if there are some preliminaries
before actually starting translation.

Or, looking at my code, is there something I could do to make
translation easier?

The first issue is not so much a translation but a portability one.
You are using absolute URLs to refer to different parts of the
tutorial. This requires changes to the source as soon as the tutorial
is located elsewhere (due to whatever reason). A better solution is
using

LINKFILE = "./index.rbx"
LINKPATH = File.basename(LINKFILE)

And modifying the links appropiately (diff is attached).

Next issue is encoding. As far as I can see you only use iso-646-us
so it seems to be a good idea to change

<?xml version="1.0" encoding="UTF-8"?>

into

<?xml version="1.0" encoding="us-ascii"?>

and adding

meta('http-equiv' =>'content-type',
     :content=>'text/html; charset=us-ascii')

to the source. That better shows what to replace by the charset that
is actually used (be it utf-8, iso-8859-15, iso-2022-jp-2, or
koi8-r). utf-8 is too generic to decide wether it is a formal
requirement or an actual charset.

Line length:

  1. Normal text: Consider keeping it below 80 chars a line whenever
    possible (vim: ‘set tw=79’) - my fetish is called ‘console’ :slight_smile:

  2. Source: Keep it below 70 characters a line. A number of browsers
    have default setups that require scrolling when code lines are
    longer than this.

On colors used: I am not sure if that still poses a problem but the
ones used are mostly not Web safe. Web save colors have 00, 33, 66,
99, CC, FF as their constituents. Netscape optimized GIFs use these
colors (you perhaps did see the number 216 - that’s 6 to the third).

Comment on diff:

‘…/L2P/Learning-To-Program-2004-02-29-22:12:13’ is the snapshot
taken (obvious date and time). ‘index.rbx’ is the updated version I
will use as a basis for translation.

Now switching to translation mode until the empire of technical
problems strike back.

Josef ‘Jupp’ SCHUGT

difflog (2.17 KB)

···

–
E-Mail: .— …- .–. .–. .–.-. --. – -…- .-.-.- -… .
http://oss.erdfunkstelle.de/ruby/ - German comp.lang.ruby FAQ
http://rubyforge.org/users/jupp/ - Ruby projects at Rubyforge