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

[Chris Pine]

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 with `Time.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

 

[Florian Gross]

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

 

[Josef 'Jupp' SCHUGT]

Hi!

* Florian Gross:

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

 

[Josef 'Jupp' SCHUGT]

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

 

[Josef 'Jupp' SCHUGT]

--/9DWx/yDrRhgMJTb
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

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:

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html>
<head><meta content="0;url=/index.rbx" http-equiv="refresh"></head>
<body><a href="index.rbx">go ahead...</a></body>
</html>

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'

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
--
E-Mail: .--- ..- .--. .--. .--.-. --. -- -..- .-.-.- -.. .
http://oss.erdfunkstelle.de/ruby/ - German comp.lang.ruby FAQ
http://rubyforge.org/users/jupp/ - Ruby projects at Rubyforge

--/9DWx/yDrRhgMJTb
Content-Type: text/plain; charset=us-ascii
Content-Description: SuggestedChanges.diff
Content-Disposition: attachment; filename=difflog

--- ../L2P/Learning-To-Program-2004-02-29-22:12:13 Sun Feb 29 23:11:11 2004
+++ index.rbx Mon Mar 1 15:43:01 2004
@@ -13,7 +13,8 @@
require 'stringio'


-LINKADDR = "//pine.fm/LearnToProgram/" # was ENV['REDIRECT_URL']
+LINKFILE = "./index.rbx"
+LINKPATH = File.basename(LINKFILE)


class TutorialWebPage
@@ -77,7 +78,7 @@

def selfLink (chap = nil)
# REQUEST_URI includes "?Chapter=Foo"
- LINKADDR+'?Chapter='+(chap ? getChapter(chap) : '')
+ LINKFILE+'?Chapter='+(chap ? getChapter(chap) : '')
end

def makeLink (name, methodName)
@@ -490,8 +491,8 @@
END_PARAGRAPH
end
ul do
- li {'<a href="'+LINKADDR+'SciTEGlobal.properties">Global Properties</a>'}
- li {'<a href="'+LINKADDR+'ruby.properties">Ruby Properties</a>'}
+ li {'<a href="'+LINKPATH+'SciTEGlobal.properties">Global Properties</a>'}
+ li {'<a href="'+LINKPATH+'ruby.properties">Ruby Properties</a>'}
end
para do <<-END_PARAGRAPH
It would also be a good idea to create a folder somewhere to keep
@@ -4648,7 +4649,7 @@
end
para do <<-END_PARAGRAPH
The pages you see (all valid XHTML 1.1) are generated by
- <a href="#{LINKADDR}?ShowTutorialCode=true">this Ruby program</a>.
+ <a href="#{LINKFILE}?ShowTutorialCode=true">this Ruby program</a>.
It may not be the prettiest code around, but
it has some neat features. For example, all of the
code samples are actually being run every time you view
@@ -4757,11 +4758,12 @@
tocString = 'Table of Contents'
tutTitle = 'Learn to Program'

- puts '<?xml version="1.0" encoding="UTF-8"?>'
+ puts '<?xml version="1.0" encoding="us-ascii"?>'
puts '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">'
htmlxmlns=>'http://www.w3.org/1999/xhtml', 'xml:lang'=>'en') do
head do
- linkrel=>'stylesheet', :type=>'text/css', :href=>LINKADDR+'tutorial.css')
+ linkrel=>'stylesheet', :type=>'text/css', :href=>LINKPATH+'tutorial.css')
+ meta('http-equiv' =>'content-type', :content=>'text/html; charset=us-ascii')
title do
tutTitle + ', by Chris Pine'
end

--/9DWx/yDrRhgMJTb--