Changed all heading levels + added control flow

01-frontpage.md

@@ -1,12 +1,10 @@
-# Python
-
-## Introduction
+# A Byte of Python
 
 'A Byte of Python' is a free book on programming using the Python language. It serves as a tutorial or guide to the Python language for a beginner audience. If all you know about computers is how to save text files, then this is the book for you.
 
 (Note that this book is primarily for the still-in-common-use Python 2.x but teaches you to write in a way that is upgradable to Python 3.x. If you don't know what that means, please ignore the previous sentence ;-))
 
-### Who Reads A Byte of Python?
+## Who Reads A Byte of Python?
 
 Here are what people are saying about the book:
 
@@ -96,11 +94,11 @@ Here are what people are saying about the book:
 >
 > -- _Justin LoveTrue_ says in a [Facebook community page](http://www.facebook.com/pythonlang/posts/406873916788)
 
-#### Even NASA
+### Even NASA
 
 The book is even used by NASA! It is being used in their [Jet Propulsion Laboratory](http://dsnra.jpl.nasa.gov/software/Python/byte-of-python/output/byteofpython_html/) with their Deep Space Network project.
 
-### Academic Courses
+## Academic Courses
 
 This book is/was being used as instructional material in various educational institutions:
 
@@ -113,7 +111,7 @@ This book is/was being used as instructional material in various educational ins
 - 'Geoprocessing' course at [Michigan State University](http://www.msu.edu/~ashton/classes/825/index.html)
 - 'Multi Agent Semantic Web Systems' course at the [University of Edinburgh](http://homepages.inf.ed.ac.uk/ewan/masws/)
 
-### License
+## License
 
 This book is licensed under the [Creative Commons Attribution-Share Alike 3.0 Unported](http://creativecommons.org/licenses/by-sa/3.0/deed.en_US) license.
 
@@ -129,21 +127,21 @@ Please note:
 - Attribution *must* be shown in the introductory description and front page of the document by linking back to <http://www.swaroopch.com/notes/Python> and clearly indicating that the original text can be fetched from this location.
 - All the code/scripts provided in this book is licensed under the [3-clause BSD License](http://www.opensource.org/licenses/bsd-license.php) unless otherwise noted.
 
-### Read Now
+## Read Now
 
 You can [read the book online](http://www.swaroopch.com/notes/Python_en-Preface).
 
-### Buy the Book
+## Buy the Book
 
 [A printed hardcopy of the book can be purchased](http://www.swaroopch.com/buybook) for your offline reading pleasure, and to support the continued development and improvement of this book.
 
-### Download
+## Download
 
 - [PDF](http://files.swaroopch.com/python/byte_of_python.pdf)
 - [Full source](https://github.com/swaroopch/byte_of_python)
 
 **If you wish to support the continued development of this book, please consider [buying a hardcopy](http://www.swaroopch.com/buybook)**.
 
-### Read the book in your native language
+## Read the book in your native language
 
 If you are interested in reading or contributing translations of this book to other human languages, please see the [Translations page](#translations).

04-installation.md

@@ -1,6 +1,6 @@
-## Installation
+# Installation
 
-### For Linux and BSD users
+## For Linux and BSD users
 
 If you are using a distribution of Linux such as Ubuntu, Fedora, OpenSUSE, Debian, CentOS or {put your choice here}, or a BSD system such as FreeBSD, then it is most likely you already have Python installed on your system.
 
@@ -29,7 +29,7 @@ In this case, you have two ways of installing Python on your system.
 - Install the binary packages using the package management software that comes with your OS, such as `apt-get` in Ubuntu/Debian and other Debian-based distros, `yum` in Fedora, `pkg_add` in FreeBSD, etc. Note that you will need an internet connection to use this method. Alternatively, you can download the binaries from somewhere else and then copy to your computer and install it.
 - You can compile Python from the [source code](http://www.python.org/download/) and install it. The compilation instructions are provided at the website.
 
-### For Windows Users
+## For Windows Users
 
 Visit <http://www.python.org/download/> and download the latest version. The installation is just like any other Windows-based software.
 
@@ -37,7 +37,7 @@ Visit <http://www.python.org/download/> and download the latest version. The ins
 
 An interesting fact is that majority of Python downloads are by Windows users. Of course, this doesn't give the complete picture since almost all Linux users will have Python installed already on their systems by default.
 
-#### DOS Prompt
+### DOS Prompt
 
 If you want to be able to use Python from the Windows command line i.e. the DOS prompt, then you need to set the PATH variable appropriately.
 
@@ -62,11 +62,11 @@ For Windows 7:
 #. If the value was `%SystemRoot%\system32;` It will now become `%SystemRoot%\system32;C:\Python27`
 #. Click ok and you are done. No restart is required.
 
-### For Mac OS X Users
+## For Mac OS X Users
 
 Mac OS X Users will find Python already installed on their system. Open the `Terminal.app` and run `python -V` and follow the advice in the above Linux and BSD section.
 
-### Summary
+## Summary
 
 For Linux and BSD systems, you probably already have Python installed on your system.  Otherwise, you can install it using the package management software that comes with your distribution. For a Windows system, installing Python is as easy as downloading the installer and double-clicking on it. From now on, we will assume that you have Python installed on your system.
 

05-first-steps.md

@@ -1,10 +1,10 @@
-## First Steps
+# First Steps
 
 We will now see how to run a traditional 'Hello World' program in Python. This will teach you how to write, save and run Python programs.
 
 There are two ways of using Python to run your program - using the interactive interpreter prompt or using a source file. We will now see how to use both of these methods.
 
-### Using The Interpreter Prompt
+## Using The Interpreter Prompt
 
 Start the interpreter on the command line by entering `python` at the shell prompt.
 
@@ -26,7 +26,7 @@ Notice that Python gives you the output of the line immediately! What you just e
 
 *How to Quit the Interpreter Prompt:* If you are using a Linux or Unix shell, you can exit the interpreter prompt by pressing `ctrl-d` or entering `exit()` (note: remember to include the parentheses, '()') followed by the `enter` key. If you are using the Windows command prompt, press `ctrl-z` followed by the `enter` key.
 
-### Choosing An Editor
+## Choosing An Editor
 
 Before we move on to writing Python programs in source files, we need an editor to write the source files. The choice of an editor is crucial indeed. You have to choose an editor as you would choose a car you would buy. A good editor will help you write Python programs easily, making your journey more comfortable and helps you reach your destination (achieve your goal) in a much faster and safer way.
 
@@ -46,7 +46,7 @@ I repeat once again, please choose a proper editor - it can make writing Python
 
 *For Emacs users:* There is a good introduction on how to [make Emacs a powerful Python IDE by Pedro Kroger](http://pedrokroger.net/2010/07/configuring-emacs-as-a-python-ide-2/).
 
-### Using A Source File
+## Using A Source File
 
 Now let's get back to programming. There is a tradition that whenever you learn a new programming language, the first program that you write and run is the 'Hello World' program - all it does is just say 'Hello World' when you run it. As Simon Cozens (the author of the amazing 'Beginning Perl' book) puts it, it is the 'traditional incantation to the programming gods to help you learn the language better' :) .
 
@@ -56,7 +56,7 @@ If you are using Sublime Text, type the below lines and do `File` --- `Save`, ch
 
 ~~~python
 #!/usr/bin/python
-#Filename: helloworld.py
+Filename: helloworld.py
 
 print 'Hello World'
 ~~~
@@ -89,7 +89,7 @@ The standard for Python is:
 
 `#!/usr/bin/env python`
 
-### How It Works
+## How It Works
 
 Let us consider the first two lines of the program. These are called *comments* - anything to the right of the `#` symbol is a comment and is mainly useful as notes for the reader of the program.
 
@@ -99,7 +99,7 @@ Python does not use comments except for the special case of the first line here.
 
 The comments are followed by a Python *statement*. Here we call the `print` *function* which just prints the text `'Hello World'`. We will learn about functions in a [later chapter](#functions), what you should understand now is that whatever you supply in the parentheses will be printed back to the screen. In this case, we supply `'Hello World'` which is referred to as a string - don't worry, we will explore these terminologies in detail later.
 
-#### Executable Python Programs
+### Executable Python Programs
 
 This applies only to Linux and Unix users but Windows users might be curious as well about the first line of the program. First, we have to give the program executable permission using the `chmod` command then *run* the source program.
 
@@ -137,7 +137,7 @@ This method is very useful if you want to write scripts you can run anytime, any
 
 *Caution:* With regard to Python, a program, script or software all mean the same thing.
 
-### Getting Help
+## Getting Help
 
 If you need quick information about any function or statement in Python, then you can use the built-in `help` functionality. This is very useful especially when using the interpreter prompt. For example, run `help(print)` - this displays the help for the print function which is used to print things to the screen.
 
@@ -147,6 +147,6 @@ Similarly, you can obtain information about almost anything in Python. Use `help
 
 In case you need to get help for operators like `return`, then you need to put those inside quotes such as `help('return')` so that Python doesn't get confused on what we're trying to do.
 
-### Summary
+## Summary
 
 You should now be able to write, save and run Python programs at ease. Now that you are a Python user, let's learn some more Python concepts.

07-operators-expressions.md

@@ -1,10 +1,10 @@
-## Operators and Expressions
+# Operators and Expressions
 
 Most statements (logical lines) that you write will contain *expressions*. A simple example of an expression is `2 + 3`. An expression can be broken down into operators and operands.
 
 *Operators* are functionality that do something and can be represented by symbols such as `+` or by special keywords. Operators require some data to operate on and such data is called *operands*. In this case, `2` and `3` are the operands.
 
-### Operators
+## Operators
 
 We will briefly take a look at the operators and their usage:
 
@@ -161,7 +161,7 @@ Note that you can evaluate the expressions given in the examples using the inter
 
     `x = True; y = False; x or y` returns `True`. Short-circuit evaluation applies here as well.
 
-#### Shortcut for math operation and assignment
+### Shortcut for math operation and assignment
 
 It is common to run a math operation on a variable and then assign the result of the operation back to the variable, hence there is a shortcut for such expressions:
 
@@ -179,7 +179,7 @@ as:
 
 Notice that `var = var operation expression` becomes `var operation= expression`.
 
-### Evaluation Order
+## Evaluation Order
 
 If you had an expression such as `2 + 3 * 4`, is the addition done first or the multiplication? Our high school maths tells us that the multiplication should be done first. This means that the multiplication operator has higher precedence than the addition operator.
 
@@ -283,23 +283,23 @@ The operators which we have not already come across will be explained in later c
 
 Operators with the *same precedence* are listed in the same row in the above table. For example, `+` and `-` have the same precedence.
 
-### Changing the Order Of Evaluation
+## Changing the Order Of Evaluation
 
 To make the expressions more readable, we can use parentheses. For example, `2 + (3 * 4)` is definitely easier to understand than `2 + 3 * 4` which requires knowledge of the operator precedences. As with everything else, the parentheses should be used reasonably (do not overdo it) and should not be redundant, as in `(2 + (3 * 4))`.
 
 There is an additional advantage to using parentheses - it helps us to change the order of evaluation. For example, if you want addition to be evaluated before multiplication in an expression, then you can write something like `(2 + 3) * 4`.
 
-### Associativity
+## Associativity
 
 Operators are usually associated from left to right. This means that operators with the same precedence are evaluated in a left to right manner. For example, `2 + 3 + 4` is evaluated as `(2 + 3) + 4`. Some operators like assignment operators have right to left associativity i.e. `a = b = c` is treated as `a = (b = c)`.
 
-### Expressions
+## Expressions
 
 Example:
 
 ~~~python
 #!/usr/bin/python
-# Filename: expression.py
+ Filename: expression.py
 
 length = 5
 breadth = 2
@@ -323,6 +323,6 @@ The length and breadth of the rectangle are stored in variables by the same name
 
 Also, notice how Python 'pretty-prints' the output. Even though we have not specified a space between `'Area is'` and the variable `area`, Python puts it for us so that we get a clean nice output and the program is much more readable this way (since we don't need to worry about spacing in the strings we use for output). This is an example of how Python makes life easy for the programmer.
 
-### Summary
+## Summary
 
 We have seen how to use operators, operands and expressions - these are the basic building blocks of any program. Next, we will see how to make use of these in our programs using statements.

fabfile.py

@@ -47,6 +47,11 @@ MARKDOWN_FILES = [
         'slug': "python_en-operators_and_expressions",
         'title': "Python : Operators and Expressions",
     },
+    {
+        'file': '08-control-flow.md',
+        'slug': "python_en-control_flow",
+        'title': "Python : Control Flow",
+    },
 ]
 
 
@@ -167,8 +172,7 @@ def markdown_to_html(source_text, upload_assets_to_s3=False):
     """Convert from Markdown to HTML; optional: upload images, etc. to S3."""
     args = ['pandoc',
             '-f', 'markdown',
-            '-t', 'html5',
-            '-S']
+            '-t', 'html5']
     p = subprocess.Popen(args, stdin=subprocess.PIPE, stdout=subprocess.PIPE)
     output = p.communicate(source_text)[0]
 
@@ -285,7 +289,6 @@ def html():
             '-f', 'markdown',
             '-t', 'html5',
             '-o', '{}.html'.format(FULL_PROJECT_NAME),
-            '-S',
             '-s',
             '--toc'] + [i['file'] for i in MARKDOWN_FILES]
     local(' '.join(args))
@@ -298,8 +301,8 @@ def epub():
     args = ['pandoc',
             '-f', 'markdown',
             '-t', 'epub',
-            '-o', '{}.epub'.format(FULL_PROJECT_NAME),
-            '-S'] + [i['file'] for i in MARKDOWN_FILES]
+            '-o', '{}.epub'.format(FULL_PROJECT_NAME)] + \
+        [i['file'] for i in MARKDOWN_FILES]
     # TODO --epub-cover-image
     # TODO --epub-metadata
     # TODO --epub-stylesheet
@@ -315,8 +318,8 @@ def pdf():
             '-f', 'markdown',
             # https://github.com/jgm/pandoc/issues/571
             #'-t', 'pdf',
-            '-o', '{}.pdf'.format(FULL_PROJECT_NAME),
-            '-S'] + [i['file'] for i in MARKDOWN_FILES]
+            '-o', '{}.pdf'.format(FULL_PROJECT_NAME)] + \
+        + [i['file'] for i in MARKDOWN_FILES]
     local(' '.join(args))
     if AWS_ENABLED:
         upload_output_to_s3('{}.pdf'.format(FULL_PROJECT_NAME))
@@ -328,8 +331,8 @@ def docx():
     args = ['pandoc',
             '-f', 'markdown',
             '-t', 'docx',
-            '-o', '{}.docx'.format(FULL_PROJECT_NAME),
-            '-S'] + [i['file'] for i in MARKDOWN_FILES]
+            '-o', '{}.docx'.format(FULL_PROJECT_NAME)] + \
+        [i['file'] for i in MARKDOWN_FILES]
     local(' '.join(args))
     if AWS_ENABLED:
         upload_output_to_s3('{}.docx'.format(FULL_PROJECT_NAME))
@@ -341,8 +344,8 @@ def odt():
     args = ['pandoc',
             '-f', 'markdown',
             '-t', 'odt',
-            '-o', '{}.odt'.format(FULL_PROJECT_NAME),
-            '-S'] + [i['file'] for i in MARKDOWN_FILES]
+            '-o', '{}.odt'.format(FULL_PROJECT_NAME)] + \
+        [i['file'] for i in MARKDOWN_FILES]
     local(' '.join(args))
     if AWS_ENABLED:
         upload_output_to_s3('{}.odt'.format(FULL_PROJECT_NAME))