Merge branch 'master' of https://github.com/Akuli/python-tutorial

Akuli · Akuli · commit ae91cf22943a · 2016-11-13T18:56:34.000+02:00
diff --git a/lists-and-tuples.md b/lists-and-tuples.md
@@ -145,7 +145,7 @@ None
 ```
 
 This is the same thing that happened way back when [we assigned
-print's return value to a variable](using-functions.md).
+print's return value to a variable](using-functions.md#return-values).
 
 ## What is what?
 
diff --git a/using-functions.md b/using-functions.md
@@ -29,20 +29,31 @@ Hello World!
 
 But what exactly is print?
 
+## What are functions?
+
+Let's see what happens if we type `print` without the `('Hello')` part.
+
 ```py
 >>> print
 <built-in function print>
 >>> 
 ```
 
-In Python 3, print is a function. Functions do something when they are
+We could also type `print(print)`, it would do the same thing. Python
+replied to us with some information about print wrapped in `<>`.
+
+As we can see, print is a function. Functions do something when they are
 **called** by typing their name and parentheses. Inside the
 parentheses, we can pass some arguments too. In `print("hello")` the
 function is `print` and we give it one argument, which is `"hello"`.
 
-Functions are sometimes thoght of as difficult to understand, but they
-really are not. They just do something when they are called. But if we
-do `x = print('hello')`, what is x?
+Functions are easy to understand, They simply **do something when they
+are called**. Functions run immediately when we call them, so the
+text appears on the screen right away when we run `print(something)`.
+
+## Return values
+
+If we do `x = print('hello')`, what is x?
 
 ```py
 >>> x = print('hello')
@@ -58,8 +69,7 @@ explained in more detail:
 - In `x = print('hello')`, the right side is processed first.
 - `print('hello')` calls the print function with the argument
     `'hello'`.
-- The function runs **immediately** when it's called. It shows the word
-    hello.
+- The function runs. It shows the word hello.
 - The print function **returns** None. All functions need to return
     something, and print returns None because there's no need to return
     anything else.
@@ -68,17 +78,46 @@ explained in more detail:
     there, and the assignment now looks like `x = None`.
 - x is now None.
 
+Now we understand what a return value is. When we call the function,
+Python "replaces" `function(args)` with whatever the function returns.
+
 Calling a function without assigning the return value to anything (e.g.
 `print('hello')` instead of `x = print('hello')`) simply throws away
-the return value. The interactive `>>>` prompt also echoes the return
-value back if it's not None.
+the return value. The interactive `>>>` prompt doesn't echo the return
+value back because it's None.
 
 Of course, `x = print('hello')` is useless compared to `print('hello')`
 because the print function always returns None and we can do `x = None`
 without any printing.
 
+Not all functions return None. The input function can be used for
+getting a string from the user.
+
+```py
+>>> x = input("Enter something:")
+Enter something:hello
+>>> x
+'hello'
+>>> 
+```
+
+`input("Enter something:")` showed the text `Enter something:` on the
+screen and waited for me to type something. I typed hello and pressed
+Enter. Then input returned the hello I typed as a string and it was
+assigned to x.
+
+Usually we want to add a space after the `:`, like this:
+
+```py
+>>> x = input("Enter something: ")  # now there's space between : and where i type
+Enter something: hello
+>>> 
+```
+
+## More about print
+
 We can also print an empty line by calling print without any
-arguments:
+arguments.
 
 ```py
 >>> print()
@@ -97,7 +136,7 @@ world
 ```
 
 If we want to print a backslash, we need to **escape** it by typing
-two backslashes:
+two backslashes.
 
 [comment]: # (For some reason, GitHub's syntax highlighting doesn't)
 [comment]: # (work here.)
@@ -123,37 +162,14 @@ Unlike with `+`, the arguments don't need to be strings.
 >>> 
 ```
 
-Not all functions return None. The input function can be used for
-getting a string from the user.
-
-```py
->>> x = input("Enter something:")
-Enter something:hello
->>> x
-'hello'
->>> 
-```
-
-`input("Enter something:")` showed the text `Enter something:` on the
-screen and waited for me to type something. I typed hello and pressed
-Enter. Then input returned the hello I typed as a string and it was
-assigned to x.
-
-Usually we want to add a space after the `:`, like this:
-
-```py
->>> x = input("Enter something: ")  # now there's space between : and where i type
-Enter something: hello
->>> 
-```
-
 ## Summary
 
 - `function()` calls a function without any arguments, and
     `function(1, 2, 3)` calls a function with 1, 2 and 3 as arguments.
-    `x = function()` calls a function, and assigns the return value of
-    the call to x.
 - When a function is called, it does something and returns something.
+- `function(stuff)` is "replaced" with the return value in the code
+    that called it. For example, `x = function()` calls a function, and
+    then does `x = the_return_value` and the return value ends up in x.
 - Python comes with `print` and `input`. They are built-in functions.
 
 ***
diff --git a/what-is-programming.md b/what-is-programming.md
@@ -97,6 +97,11 @@ any way. You'll get an error message that tells you what's wrong and
 where. Even professional programmers do mistakes and get error messages
 all the time, and there's nothing wrong with it.
 
+If you want to know what some piece of code in this tutorial does just
+**try it and see**. It's practically impossible to break anything
+accidentally with code in this tutorial, so you are free to try out all
+the examples however you want and change them to do whatever you want.
+
 Even though a good tutorial is an important part about learning to
 program, you also need to learn to make your own things. Use what you
 have learned, and create something with it.
@@ -113,7 +118,7 @@ rest of this tutorial only if you don't understand the code.
     character on your keyboard and press the key, holding down shift or AltGr
     as needed.
 - Make sure you understand everything you read.
-- Don't fear mistakes.
+- Experiment with things freely and don't fear mistakes.
 - Error messages are your friends.
 - Let me know if you have trouble with this tutorial.
 - Now we're ready to [install Python](installing-python.md) and
@@ -122,3 +127,5 @@ rest of this tutorial only if you don't understand the code.
 ***
 
 You may use this tutorial at your own risk. See [LICENSE](LICENSE).
+
+[Back to the list of contents](README.md#list-of-contents)
