Branch merged.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/basic_python/list_tuples.rst Mon Aug 24 23:33:26 2009 +0530
@@ -0,0 +1,506 @@
+Lists and Tuples
+================
+
+Lists
+-----
+
+Python provides an intuitive way to represent a group items, called *Lists*. The
+items of a *List* are called its elements. Unlike C/C++, elements can be of any
+type. A *List* is represented as a list of comma-sepated elements with square
+brackets around them::
+
+ >>> a = [10, 'Python programming', 20.3523, 23, 3534534L]
+ >>> a
+ [10, 'Python programming', 20.3523, 23, 3534534L]
+
+
+Common List Operations
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following are some of the most commonly used operations on *Lists*.
+
+
+~~~~~~~~
+Indexing
+~~~~~~~~
+
+Individual elements of a *List* can be accessed using an index to the element.
+The indices start at 0. One can also access the elements of the *List* in reverse
+using negative indices.::
+
+ >>> a[1]
+ 'Python programming'
+ >>> a[-1]
+ 3534534L
+
+It is important to note here that the last element of the *List* has an index of
+-1.
+
+
+~~~~~~~~~~~~~
+Concatenating
+~~~~~~~~~~~~~
+
+Two or more *Lists* can be concatenated using the + operator::
+
+ >>> a + ['foo', 12, 23.3432, 54]
+ [10, 'Python programming', 20.3523, 'foo', 12, 23.3432, 54]
+ >>> [54, 75, 23] + ['write', 67, 'read']
+ [54, 75, 23, 'write', 67, 'read']
+
+
+~~~~~~~
+Slicing
+~~~~~~~
+
+A *List* can be sliced off to contain a subset of elements of the *List*. Slicing
+can be done by using two indices separated by a colon, where the first index is
+inclusive and the second index is exclusive. The resulting slice is also a *List*.::
+
+ >>> num = [1, 2, 3, 4, 5, 6, 7, 8, 9]
+ >>> num[3:6]
+ [4, 5, 6]
+ >>> num[0:1]
+ [1]
+ >>> num[7:10]
+ [7, 8, 9]
+
+The last example showed how to access last 3 elements of the *List*. There is a
+small catch here. The second index 10 actually refers to the 11th element of the
+*List* which is still valid, even though it doesn't exist because the second
+index is exclusive and tells the Python interpreter to get the last element of
+the *List*. But this can also be done in a much easier way using negative indices::
+
+ >>> num[-3:-1]
+ [7, 8, 9]
+
+Excluding the first index implies that the slice must start at the beginning of
+the *List*, while excluding the second index includes all the elements till the
+end of the *List*. A third parameter to a slice, which is implicitly taken as 1
+is the step of the slice. It is specified as a value which follows a colon after
+the second index::
+
+ >>> num[:4]
+ [1, 2, 3, 4]
+ >>> num[7:]
+ [8, 9]
+ >>> num[-3:]
+ [7, 8, 9]
+ >>> num[:]
+ [1, 2, 3, 4, 5, 6, 7, 8, 9]
+ >>> num[4:9:3]
+ [5, 8]
+ >>> num[3::2]
+ [4, 6, 8]
+ >>> num[::4]
+ [1, 5, 9]
+
+
+~~~~~~~~~~~~~~
+Multiplication
+~~~~~~~~~~~~~~
+
+
+A *List* can be multiplied with an integer to repeat itself::
+
+ >>> [20] * 5
+ [20, 20, 20, 20, 20]
+ >>> [42, 'Python', 54] * 3
+ [42, 'Python', 54, 42, 'Python', 54, 42, 'Python', 54]
+
+
+~~~~~~~~~~
+Membership
+~~~~~~~~~~
+
+**in** operator is used to find whether an element is part of the *List*. It
+returns **True** if the element is present in the *List* or **False** if it is not
+present. Since this operator returns a Boolean value it is called a Boolean
+operator::
+
+ >>> names = ['Guido', 'Alex', 'Tim']
+ >>> 'Tim' in names
+ True
+ >>> 'Adam' in names
+ False
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Length, Maximum and Minimum
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Length of a *List* can be found out using the len function. The max function
+returns the element with the largest value and the min function returns the
+element with the smallest value::
+
+ >>> num = [4, 1, 32, 12, 67, 34, 65]
+ >>> len(num)
+ 7
+ >>> max(num)
+ 67
+ >>> min(num)
+ 1
+
+
+~~~~~~~~~~~~~~~~~
+Changing Elements
+~~~~~~~~~~~~~~~~~
+
+Unlike Strings *Lists* are mutable, i.e. elements of a *List* can be manipulated::
+
+ >>> a = [1, 3, 5, 7]
+ >>> a[2] = 9
+ >>> a
+ [1, 3, 9, 7]
+
+
+~~~~~~~~~~~~~~~~~
+Deleting Elements
+~~~~~~~~~~~~~~~~~
+
+An element or a slice of a *List* can be deleted by using the **del** statement::
+
+ >>> a = [1, 3, 5, 7, 9, 11]
+ >>> del a[-2:]
+ >>> a
+ [1, 3, 5, 7]
+ >>> del a[1]
+ >>> a
+ [1, 5, 7]
+
+
+~~~~~~~~~~~~~~~~
+Assign to Slices
+~~~~~~~~~~~~~~~~
+
+In the same way, values can be assigned to individual elements of the *List*,
+a *List* of elements can be assigned to a slice::
+
+ >>> a = [2, 3, 4, 5]
+ >>> a[:2] = [0, 1]
+ [0, 1, 4, 5]
+ >>> a[2:2] = [2, 3]
+ >>> a
+ [0, 1, 2, 3, 4, 5]
+ >>> a[2:4] = []
+ >>> a
+ [0, 1, 4, 5]
+
+The last two examples should be particularly noted carefully. The last but one
+example insert elements or a list of elements into a *List* and the last example
+deletes a list of elements from the *List*.
+
+
+None, Empty Lists, and Initialization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An *Empty List* is a *List* with no elements and is simply represented as
+[]. A *None List* is one with all elements in it being **None**. It serves
+the purpose having a container list of some fixed number of elements with
+no value::
+
+ >>> a = []
+ >>> a
+ []
+ >>> n = [None] * 10
+ >>> n
+ [None, None, None, None, None, None, None, None, None, None]
+
+
+Nested Lists
+~~~~~~~~~~~~
+
+As mentioned earlier, a List can contain elements of any data type. This also
+implies a *List* can have a *Lists* themselves as its elements. These are
+called as *Nested Lists*. There is no limit on the depth of the *Nested Lists*::
+
+ >>> a = [1, [1, 2, 3], 3, [1, [1, 2, 3]], 7]
+
+
+List Methods
+~~~~~~~~~~~~
+
+A method is a function that is coupled to an object. More about objects
+and its methods are discussed in Advanced Python module. In general, a
+method is called like::
+
+ object.method(arguments)
+
+For now, it is enough to know that a list of elements is an object and
+so *List* methods can be called upon them. Also some of the methods change
+the *List* in-place, meaning it modifies the existing list instead of creating
+a new one, while other methods don't. It must be noted as we run through
+the *List* methods.
+
+Some of the most commonly used *List* methods are as follows:
+
+
+~~~~~~
+append
+~~~~~~
+
+The *append* method is used to append an object at the end of the list::
+
+ >>> prime = [2, 3, 5]
+ >>> prime.append(7)
+ >>> prime
+ [2, 3, 5, 7]
+
+It is important to note that append changes the *List* in-place.
+
+
+~~~~~
+count
+~~~~~
+
+The *count* method returns the number of occurences of a particular element
+in a list::
+
+ >>> [1, 4, 4, 9, 9, 9].count(9)
+ 3
+ >>> tlst = ['Python', 'is', 'a', 'beautiful', 'language']
+ >>> tlst.count('Python')
+ 1
+
+
+~~~~~~
+extend
+~~~~~~
+
+The *extend* method extends the list on which it is called by the list supplied
+as argument to it::
+
+ >>> a = [1, 2, 3]
+ >>> b = [4, 5, 6]
+ >>> a.extend(b)
+ [1, 2, 3, 4, 5, 6]
+
+This is an in-place method. This method is equivalent to using the + operator, but
+using the + operator returns a new list.
+
+
+~~~~~
+index
+~~~~~
+
+The *index* method returns the index position of the element in the list
+specified as argument::
+
+ >>> a = [1, 2, 3, ,4, 5]
+ >>> a.index(4)
+ 3
+
+
+~~~~~~
+insert
+~~~~~~
+
+The *insert* method is used to insert an element specified as the second
+argument to the list at the position specified by the first argument::
+
+ >>> a = ['Python', 'is', 'cool']
+ >>> a.insert(2, 'so')
+ >>> a
+ ['Python', 'is', 'so', 'cool']
+
+The *insert* method changes the *List* in-place.
+
+
+~~~
+pop
+~~~
+
+The *pop* method removes an element from the list. The index position
+of the element to be removed can be specified as an argument to the
+*pop* method, if not it removes the last element by default::
+
+ >>> a = [1, 2, 3, 4, 5]
+ >>> a.pop()
+ >>> a
+ 5
+ >>> a.pop(2)
+ >>> a
+ 3
+
+The *pop* method changes the *List* in-place.
+
+
+~~~~~~
+remove
+~~~~~~
+
+The *remove* method removes the first occurence of an element supplied as a
+parameter::
+
+ >>> a = [1, 2, 3, 4, 2, 5, 2]
+ >>> a.remove(2)
+ >>> a
+ [1, 3, 4, 2, 5, 2]
+
+
+~~~~~~~
+reverse
+~~~~~~~
+
+The *reverse* method reverses elements in the list. It is important to note
+here that *reverse* method changes the list in-place and doesn't return any
+thing::
+
+ >>> a = ['guido', 'alex', 'tim']
+ >>> a.reverse()
+ >>> a
+ ['tim', 'alex', 'guido']
+
+
+~~~~
+sort
+~~~~
+
+The *sort* method is used to sort the elements of the list. The *sort* method
+also sorts in-place and does not return anything::
+
+ >>> a = [5, 1, 3, 7, 4]
+ >>> a.sort()
+ >>> a
+ [1, 3, 4, 5, 7]
+
+In addition to the sort method on a *List* object we can also use the built-in
+**sorted** function. This function takes the *List* as a parameter and returns
+a sorted copy of the list. However the original list is left intact::
+
+ >>> a = [5, 1, 3, 7, 4]
+ >>> b = sorted(a)
+ >>> b
+ [1, 3, 4, 5, 7]
+ >>> a
+ [5, 1, 3, 7, 4]
+
+
+List Comprehensions
+~~~~~~~~~~~~~~~~~~~
+
+List Comprehension is a convenvience utility provided by Python. It is a
+syntatic sugar to create *Lists*. Using *List Comprehensions* one can create
+*Lists* from other type of sequential data structures or other *Lists* itself.
+The syntax of *List Comprehensions* consists of a square brackets to indicate
+the result is a *List* within which we include at least one **for** clause and
+multiple **if** clauses. It will be more clear with an example::
+
+ >>> num = [1, 2, 3]
+ >>> sq = [x*x for x in num]
+ >>> sq
+ [1, 4, 9]
+ >>> all_num = [1, 2, 3, 4, 5, 6, 7, 8, 9]
+ >>> even = [x for x in all_num if x%2 == 0]
+
+The syntax used here is very clear from the way it is written. It can be
+translated into english as, "for each element x in the list all_num,
+if remainder of x divided by 2 is 0, add x to the list."
+
+
+Tuples
+------
+
+*Tuples* are sequences just like *Lists*, but they are immutable. In other
+words *Tuples* provides a way to represent a group of items, where the group
+of items cannot be changed in any way. The syntax of a *Tuple* is also very
+similar to *List*. A *Tuple* is represented with the list of items, called
+elements of the *Tuple* separated by comma, with the entire list being enclosed
+in parenthesis. It is not compulsory to use parenthesis around a *Tuple* but
+it may be necessary in some of the cases::
+
+ >>> a = 1, 2, 3
+ >>> a
+ (1, 2, 3)
+ >>> b = 1,
+ >>> b
+ (1,)
+
+It is interesting to note the second example. Just a value followed by a comma
+automatically makes that an element of a *Tuple* with only one element. It is
+also important to note that, irrespective of input having a parenthesis, the
+output always has a parenthesis.
+
+The first example is also known as *Tuple packing*, because values are being
+packed into a tuple. It is also possible to do *Tuple unpacking* which is more
+interesting. It is better to understand that by example. Say we have a
+co-ordinate pair from which we need to separate x and y co-ordinates::
+
+ >>> a = (1, 2)
+ >>> x, y = a
+ >>> x
+ 1
+ >>> y
+ 2
+
+*Tuple unpacking* also has several other use-cases of which the most interesting
+one is to swap the values of two variables. Using programming languages like C
+would require anywhere around 10 lines of code and an extra temporary variable
+to do this (including all the #include stuff). Python does it in the most
+intuitive way in just one line. Say we want to swap the co-ordinates in the
+above example::
+
+ >>> x, y = y, x
+ >>> x
+ 2
+ >>> y
+ 1
+
+Common Tuple Operations
+~~~~~~~~~~~~~~~~~~~~~~~
+
+There is no need to introduce all the *Tuple* operations again, since *Tuples*
+support the following operations that *List* supports in exactly the same way:
+
+ * Indexing
+ * Concatenating
+ * Slicing
+ * Membership
+ * Multiplication
+ * Length, Maximum, Minimum
+
+The following examples illustrate the above operations::
+
+ >>> a = (1, 2, 3, 4, 5, 6)
+ >>> a[5]
+ 6
+ >>> b = (7, 8, 9)
+ >>> a + b
+ (1, 2, 3, 4, 5, 6, 7, 8, 9)
+ >>> a[3:5]
+ (4, 5)
+ >>> 5 in a
+ True
+ >>> c = (1,)
+ >>> c * 5
+ (1, 1, 1, 1, 1)
+ >>> len(a)
+ 6
+ >>> max(a)
+ 6
+ >>> min(a)
+ 1
+
+However the following *List* operations are not supported by *Tuples* because
+*Tuples* cannot be changed once they are created:
+
+ * Changing elements
+ * Deleting elements
+ * Assigning to slices
+
+Similarity to *Lists* leads to the questions like, why not *Lists* only? Why do
+we even want *Tuples*? Can we do the same with *Lists*? And the answer is **Yes**
+we can do it, but *Tuples* are helpful at times, like we can return Tuples from
+functions. They are also returned by some built-in functions and methods. And
+also there are some use cases like co-ordinate among other things. So *Tuples*
+are helpful.
+
+
+Conclusion
+----------
+
+This section on *Lists* and *Tuples* introduces almost all the necessary
+machinary required to work on *Lists* and *Tuples*. Topics like how to
+iterate through these data structures will be introduced in the later
+sections.
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/latex/handout.rst Mon Aug 24 23:33:26 2009 +0530
@@ -0,0 +1,795 @@
+LaTeX
+=====
+
+Introduction
+------------
+LaTeX is a typesetting program that is excellent for producting scientific and mathematical documents of high typographical quality. It is also suitable for producing all sorts of other documents, from simple letters to complete books. LaTeX uses TeX as its formatting engine.
+
+
+TeX & LaTeX
+~~~~~~~~~~~
+
+TeX
++++
+
+TeX is a typesetting system designed and mostly written by Donald Knuth. It was designed with two goals in mind-
+
+1. To allow anybody to produce high-quality books using a reasonable amount of effort.
+2. To provide a system that would give the exact same results on all computers, now and in the future
+
+It’s also a Turing-complete programming language, in the sense that it supports the if-else construct, it can calculate (the calculations are performed while compiling the document), etc., but you would find it very hard to make anything else but typesetting with it. The fine control TeX offers makes it very powerful, but also difficult and time-consuming to use.
+
+TeX is renowned for being extremely stable, for running on many different kinds of computers, and for being virtually bug free.
+
+The version number of TeX is converging to π and is now at 3.1415926.
+
+The characters T, E, X in the name come from capital Greek letters tau, epsilon, and chi, as the name of TeX derives from the Greek: τέχνη (skill, art, technique); for this reason, TeX's creator Donald Knuth promotes a /tɛx/ pronunciation
+
+LaTeX
++++++
+LaTeX is a macro package based on TeX created by Leslie Lamport. It was intended to provide a high-level language that provides access to TeX. It essentially comprises a collection of TeX macros and a program to process LaTeX documents. For the end-users, it is much simpler to use than TeX. It has become the dominant method for using TeX (relatively few people write in TeX anymore).
+
+LaTeX is pronounced either as "Lah-tech" or "Lay-tech"
+
+WYSIWG vs. WYSIWM
+~~~~~~~~~~~~~~~~~
+The Advantages-
+
+ * It is free (both as in free-beer and free-speech)
+ * It is platform independent.
+ * It is very stable.
+ * LaTeX is ASCII and any text editor of your choice can be used to view and edit the source.
+ * The typesetting is better, especially the maths.
+ * It encourages Authors to write well-structured texts, since specifying structure is an integral part of how LaTeX works.
+ * LaTeX is extensible. If you want a new feature, you can look around for a free add-on or write one yourself.
+
+and some Disadvantages -
+
+ * Font selection is difficult
+ * LaTeX's not good at flowing text around pictures.
+ * LaTeX encourages (almost insists on) structured writing and the separation of style from content. This is not the way that many people (especially non-programmers) are used to working.
+ * Without a WYSIWYG front end, it's not always easy to find out how to do things.
+
+LaTeX Source
+~~~~~~~~~~~~
+
+::
+
+ %hello.tex - First LaTeX document
+ \documentclass{article}
+
+ \begin{document}
+ Hello, World!
+ \end{document}
+
+
+Spaces
+++++++
+
+LaTeX ignores whitespaces. Multiple white spaces are treated as one space. An empty line between two lines of text is considered as a change of paragraphs.
+
+Special Characters
+++++++++++++++++++
+
+The characters ``~ # $ % ^ & _ { } \`` have special meanings associated with them.
+
+These characters can be used in your document by adding a prefix backslash. ``\~ \# \% \$ \^ \& \_ \{ \} \textbackslash``
+
+Comments
+++++++++
+
+% character is used to insert comments into a LaTeX document. All the text from the % character to the end of that line is ignored by LaTeX.
+
+
+LaTeX Commands
+++++++++++++++
+
+* LaTeX commands are case sensitive.
+* They start with a backslash ``\``
+* They come in two formats
+
+ - a backslash followed by a name consisting of letters only. These command names are terminated by any non-letter.
+ - a backslash followed by exactly one non-character.
+
+* Some commands need to be given a parameter, which is enclosed in curly braces ``{ }``
+* Some command support optional parameters, which are added after the name in square brackets ``[ ]``
+
+LaTeX Environments
+++++++++++++++++++
+
+Environments are similar in their role, to commands, except that they effect a larger part of the document.
+
+* They begin with a ``\begin`` and end with a ``\end``
+* Nested environments are generally supported
+
+Anything in LaTeX can be expressed in terms of Commands and Environments.
+
+Hello, World!
+~~~~~~~~~~~~~
+
+::
+
+ %hello.tex - First LaTeX document
+ \documentclass{article}
+
+ \begin{document}
+ Hello, World!
+ \end{document}
+
+Now, look at what each line does.
+
+
+``%hello.tex - First LaTeX document``
+
+ This line is a comment. Comments in LaTeX begin with a %
+
+``\documentclass{article}``
+
+ This line is a command and sets the documentclass to be used for this document to ``article``. If you want to change the appearance of the document, you simply have to change the documentclass.
+
+
+``\begin{document}``
+
+ This line is the beginning of a LaTeX environment called ``document``. It informs LaTeX that the content of the document is beginning. Anything between the ``\documentclass`` line and this line is called the *preamble*
+
+``Hello, World!``
+
+ This is the text that is displayed in the document.
+
+``\end{document}``
+
+ The ``document`` environment ends here. It tells LaTeX that the document is complete and anything written after this line will be ignored by LaTeX.
+
+Compiling & Output
+~~~~~~~~~~~~~~~~~~
+``latex`` command can be used to get ``dvi`` output. But, we shall be using ``pdflatex`` all through this document and producing ``pdf`` output.
+
+::
+
+ $pdflatex hello.tex
+
+ Output written on hello.pdf (1 page, 5733 bytes).
+ Transcript written on hello.log.
+
+.. .. image:: sample/hello.jpg
+
+
+
+Document Structure
+------------------
+
+This section gives a basic idea about the general sturcture of a LaTeX document. LaTeX is different from other typesetting software in that, it requires the user to specify the logical and semantic structure of the text. Therefore, it helps (almost forces) the author to organize his text better and hence improving the structure and clarity of the document.
+
+``\documentclass``
+~~~~~~~~~~~~~~~~~~
+
+The type of the document to be created is specified using the ``\documentclass`` command.
+::
+
+ \documentclass[options]{class}
+
+Here, ``class`` defines the type of document that is to be created. The LaTeX distribution provides a variety of document class, that can be used for a variety of purposes. The ``options`` parameter customizes various properties of the document. The options have to be separated by commas.
+
+For example ``\documentclass[11pt, twoside, a4paper]{article}`` produces a document of the article class with the base font size as eleven points, and to produce a layout suitable for double sided printing on A4 paper.
+
+Some of the document classes that are available in LaTeX are ``article, report, book, slides, letter``
+
+
+The document environment
+~~~~~~~~~~~~~~~~~~~~~~~~
+The text of the document is enclosed in between the commands ``\begin{document}`` and ``\end{document}`` which identify the beginning and the end of the document respectively.
+
+The reason for marking off the beginning of your text is that LaTeX allows you to insert extra setup specifications before it. The reason for marking off the end of your text is to provide a place for LaTeX to be programmed to do extra stuff automatically at the end of the document, like making an index.
+
+A useful side-effect of marking the end of the document text is that you can store comments or temporary text underneath the \end{document} in the knowledge that LaTeX will never try to typeset them
+
+Preamble
+~~~~~~~~
+Everything written in between the ``\documentclass`` command and the ``\begin{document}`` command is called the Preamble. It normally contains commands that effect the whole document.
+
+Packages
+~~~~~~~~
+
+While writing your document, you will probably find that there are some areas where basic LaTeX cannot solve your problem. If you want to include graphics, coloured text or source code from a file into your document, you need to enhance the capabilities of LaTeX. Such enhancements are called packages. Packages are activated with the
+::
+
+ \usepackage[options]{package}
+
+command, where package is the name of the package and options is a list of keywords that trigger special features in the package. Some packages come with the LaTeX2e distribution and others are provided separately. You can even write your own packages, if and when required.
+
+Top Matter
+~~~~~~~~~~
+
+At the beginning of most documents there will be information about the document itself, such as the title and date, and also information about the authors, such as name, address, email etc. All of this type of information within Latex is collectively referred to as top matter. Although never explicitly specified (there is no \topmatter command) you are likely to encounter the term within Latex documentation.
+
+An example::
+
+ \documentclass[11pt,a4paper,oneside]{report}
+ \title{LaTeX - A Howto}
+ \author{The FOSSEE Team}
+ \date{August 2009}
+ \maketitle
+
+The ``\title``, ``\author`` and ``\date`` commands are self-explanaotry. You put the title, author name, and date in curly braces after the relevant command. If no date command is used, today's date is insert by default.
+
+Topmatter is always finished by the ``\maketitle`` command
+
+Abstract
+~~~~~~~~
+
+As most research papers have an abstract, there are predefined commands for telling LaTeX which part of the content makes up the abstract. This should appear in its logical order, therefore, after the top matter, but before the main sections of the body. This command is available for the document class article and report, but not book.
+::
+
+ \documentclass{article}
+ \begin{abstract}
+ Your abstract goes here...
+ \end{abstract}
+ \begin{document}
+ ...
+ \end{document}
+
+By default, LaTeX will use the word “Abstract” as a title for your abstract, if you want to change it into anything else, e.g. “Executive Summary”, add the following line in the preamble::
+
+ \renewcommand{\abstractname}{Executive Summary}
+
+Sectioning Commands
+~~~~~~~~~~~~~~~~~~~
+
+The commands for inserting sections are fairly intuitive. Of course, certain commands are appropriate to different document classes. For example, a book has chapters but an article doesn’t.
+
+Examples::
+
+ \Chapter{LaTeX}
+
+ \section{Introduction}
+
+ \subsection{TeX & LaTeX}
+
+ \subsubsection{TeX}
+
+Notice that you do not need to specify section numbers. LaTeX will sort that out for you! Also, for sections, you do not need to markup which content belongs to a given block, using \begin and \end commands, for example.
+
+All the titles of the sections are added automatically to the table of contents (if you decide to insert one). But if you make manual styling changes to your heading, for example a very long title, or some special line-breaks or unusual font-play, this would appear in the Table of Contents as well, which you almost certainly don’t want. LaTeX allows you to give an optional extra version of the heading text which only gets used in the Table of Contents and any running heads, if they are in effect. This optional alternative heading goes in [square brackets] before the curly braces.
+::
+
+ \section[Short Title]{This is a very long title and the Short Title will appear in the Table of Contents.}
+
+Section Numbering
++++++++++++++++++
+
+You don't need to explicitly do any section numbering as LaTeX does it automatically. Parts get roman numerals, Chapters and Sections get decimal numbering and Appendices are lettered. You can change the depth to which section numbering occurs, which is set to 2 by default.
+
+For example, if you want only the Parts, Chapters and Sections to be numbered and not the subsections, subsubsections etc., you can set the ``secnumdepth`` to 1 using the ``\setcounter`` command.
+::
+
+ \setcounter{secnumdepth}{1}
+
+To get an unnumbered section heading which does not go into the Table of Contents, follow the command name with an asterisk before the opening curly brace.
+::
+
+ \subsection*{Introduction}
+
+All the divisional commands from ``\part*`` to ``\subparagraph*`` have this “starred” version which can be used on special occasions for an unnumbered heading when the setting of ``secnumdepth`` would normally mean it would be numbered.
+
+Appendices
+~~~~~~~~~~
+
+The separate numbering of appendices is also supported by LaTeX. The \appendix macro can be used to indicate that following sections or chapters are to be numbered as appendices.
+::
+
+ \appendix
+ \chapter{First Appendix}
+
+ \appendix
+ \section{First Appendix}
+
+Table of Contents
+~~~~~~~~~~~~~~~~~
+
+All auto-numbered headings get entered in the Table of Contents (ToC) automatically. Just add the command ``\tableofcontents`` at the point where you want it placed.
+
+The counter ``tocdepth`` specifies what depth to take the ToC to. It can be set using the ``\setcounter`` command as shown below.
+::
+
+ \setcounter{tocdepth}{3}
+
+If you want the unnumbered section to be in the table of contents anyway, use the ``\addcontentsline`` command like this.
+::
+
+ \section*{Introduction}
+ \addcontentsline{toc}{section}{Introduction}
+
+Entries for the ToC are recorded each time you process your document, and re- produced the next time you process it, so you need to re-run LaTeX one extra time to ensure that all ToC pagenumber references are correctly calculated. We’ve already seen how to use the optional argument to the sectioning commands to add text to the ToC which is slightly different from the one printed in the body of the document. It is also possible to add extra lines to the ToC, to force extra or unnumbered section headings to be included.
+
+
+Bibliography
+~~~~~~~~~~~~
+Any good research paper will have a whole list of references. LaTeX, therefore, has a sane way to manage your references. There are two ways to insert references into your LaTeX document:
+
+1. You can embed them within the doucment itself. It's simpler, but it can be time consuming if you are writing several papers about similar subjects so that you often have to cite the same references
+2. You can store them in an external BibTeX file and then link them to your current document. You can also use a BibTeX style to define how they should appear. This way you create a small databases of the references you might need, and use them as and when you need to cite them.
+
+We shall discuss this in more detail in the Bibliography section.
+
+Including files
+~~~~~~~~~~~~~~~
+When you are working on a large document, you might want to split the input files into multiple files. LaTeX has three methods for inserting one file into another when compiling.
+
+1. ``\input``
+
+ It is equivalent to an automatic cut-paste just before compiling. To include ``file1.tex`` in our document, we just say
+ ::
+
+ \input{file1}
+
+
+2. ``\include``
+
+ It is similar to the ``\input`` command, except that it inserts a new page, each time it is executed. So, it is useful for inserting large blocks like new chapters. To inlcude chapter1.tex in our document, we say
+ ::
+
+ \include{chapter1}
+
+3. ``\includeonly``
+
+ This command is useful in restricting the ``\include`` commands that we wish to be executed. For example, if we have ``\include{chapter1}``, ``\include{chapter2}`` and ``\include{chapter3}`` in the document, but we wish to just verify the changes made to ``chapter1.tex`` and ignore the other chapters for a while, we could add the following command to the preamble.
+ ::
+
+ \includeonly{chapter1}
+
+A note on filenames
++++++++++++++++++++
+
+Never use filenames or directories that contain spaces. Make filenames as long or short as you would like, but strictly avoid spaces. Stick to upper or lower case letters (without accents), the digits, the hyphen and the full stop or period.
+
+Typesetting Text
+----------------
+
+Line and Page Breaks
+~~~~~~~~~~~~~~~~~~~~
+
+Books are often typeset with each line having the same length. LaTeX inserts the necessary line breaks and spaces between words by optimizing the con- tents of a whole paragraph. If necessary, it also hyphenates words that would not fit comfortably on a line. How the paragraphs are typeset depends on the document class.
+
+In special cases it might be necessary to order LaTeX to start a newline.
+
+``\\`` or ``\newline`` starts a newline without starting a new paragraph.
+
+``\\*`` additionally prohibits a page break after the line break.
+
+[Optional material::
+
+ \linebreak[n], \nolinebreak[n], \pagebreak[n], \nopagebreak[n]
+
+ \hyphenation
+
+ \mbox
+
+]
+
+Symbols & More Special Characters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Quotation Marks
++++++++++++++++
+
+You should not use the " for quotation marks as you would on a typewriter. In publishing there are special opening and closing quotation marks. In A LaTeX, use two ` (grave accent) for opening quotation marks and two ' (vertical quote) for closing quotation marks. For single quotes you use just one of each.
+::
+
+ `` Here is an example of putting `text' in quotes ''
+
+“ Here is an example of putting ‘text’ in quotes ”
+Need to include an image as example. ?
+
+Dashes and Hyphens
+++++++++++++++++++
+
+LaTeX has four kinds of dashes. Three of them can be accessed with different number of consecutive dashes. The fourth one is a mathematical symbol, the minus sign.
+::
+
+ The names of these dashes are: `-' hyphen, `--' en-dash, `---' em-dash and `$-$' minus sign.
+
+The names for these dashes are: ‘‐’ hyphen, ‘–’ en-dash, ‘—’ em-dash and ‘−’ minus sign.
+
+Tilde(~)
+++++++++
+
+A character often seen in web addresses is the tilde. To generate this in LaTeX you can use ``\~`` but the result ˜ is not really what you want. Try ``$\sim$`` instead.
+::
+
+ http://www.rich.edu/\~{}bush\\
+ http://www.clever.edu/$\sim$demo
+
+
+http://www.rich.edu/˜bush
+
+http://www.clever.edu/~demo
+
+Ellipsis
+++++++++
+
+On a typewriter, a comma or a period takes the same amount of space as any other letter. In book printing, these characters occupy only a little space and are set very close to the preceding letter. Therefore, you cannot enter ‘ellipsis’ by just typing three dots, as the spacing would be wrong. Instead, there is a special command for these dots. It is called ``\ldots``
+
+Emphasized Words
+~~~~~~~~~~~~~~~~
+
+If a text is typed using a typewriter, important words are emphasized by underlining them.
+::
+
+ \underline{text}
+
+In printed books, however, words are emphasized by typesetting them in an *italic* font. LaTeX provides the command
+::
+
+ \emph{text}
+
+to emphasize text. If you use emphasizing inside emphasized text, LaTeX uses normal font for emphasizing.
+::
+
+ \emph{This is emphasized text, and \emph{this is emphasized text with normal font}, within emphasized text.}
+
+*This is emphasized text, and* this is emphasized text with normal font, *within emphasized text.*
+
+
+Cross References
+~~~~~~~~~~~~~~~~
+
+In books, reports and articles, there are often cross-references to figures, tables and special segments of text. LaTeX provides the following commands for cross referencing::
+
+ \label{marker}, \ref{marker} and \pageref{marker}
+
+where ``marker`` is an identifier chosen by the user. LaTeX replaces ``\ref`` by the number of the section, subsection, figure, table, or theorem after which the corresponding ``\label`` command was issued. ``\pageref`` prints the page number of the page where the ``\label`` command occurred.
+
+As with the section titles, the numbers from the previous run are used. Therefore, to get the correct numbering, you will need to compile twice.
+
+
+Footnotes
+~~~~~~~~~
+
+With the command::
+
+ \footnote{footnote text}
+
+a footnote is printed at the foot of the current page. Footnotes should always be put after the word or sentence they refer to. Footnotes referring to a sentence or part of it should therefore be put after the comma or period.
+
+[optional::
+
+ \marginpar - Margin notes.
+
+]
+
+
+Itemize, Enumerate, and Description
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+::
+
+ \begin{enumerate}
+ \item You can mix the list environments to your taste:
+
+ \begin{itemize}
+ \item But it might start to look silly.
+ \item[-] With a dash.
+ \end{itemize}
+
+ \item Therefore remember:
+
+ \begin{description}
+ \item[Stupid] things will not become smart
+ because they are in a list.
+ \item[Smart] things, though, can be
+ presented beautifully in a list
+ \end{description}
+
+ \end{enumerate}
+
+1. You can mix the list environments to your taste:
+
+ * But it might start to look silly
+
+ - With a dash.
+
+2. Therefore remember:
+
+ **Stupid** things will not become smart because they are in a list
+
+ **Smart** things, though, can be presented beautifully in a list.
+
+
+
+Flushleft, Flushright, and Center
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The environments ``flushleft`` and ``flushright`` generate paragraphs that are either left- or right-aligned. The ``center`` environment generates centered text.
+
+
+Quote, Quotation, and Verse
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``quote`` environment is useful for quotes, important phrases and examples.
+::
+
+ A typographical rule of thumb for the line length is:
+ \begin{quote}
+ On average, no line should
+ be longer than 66 characters.
+ \end{quote}
+ This is why LaTeX pages have
+ such large borders by default
+ and also why multicolumn print
+ is used in newspapers.
+
+A typographical rule of thumb for the line length is:
+
+ On average, no line should be longer than 66 characters.
+
+This is why LaTeX pages have such large borders by default and also why multicolumn print is used in newspapers.
+
+
+There are two similar environments: the quotation and the verse environments. The quotation environment is useful for longer quotes going over several paragraphs, because it indents the first line of each paragraph.
+
+The verse environment is useful for poems where the line breaks are important. The lines are separated by issuing a \\\\ at the end of a line and an empty line after each verse.
+
+
+
+Abstract
+~~~~~~~~
+In scientific publications it is customary to start with an abstract which gives the reader a quick overview of what to expect. LaTeX provides the abstract environment for this purpose. Normally abstract is used in documents typeset with the article document class.
+::
+
+ \begin{abstract}
+ The abstract abstract.
+ \end{abstract}
+
+Verbatim
+~~~~~~~~
+Text that is enclosed between ``\begin{verbatim}`` and ``\end{verbatim}`` will be directly printed, as if typed on a typewriter, with all line breaks and spaces, without any LaTeX command being executed.
+::
+
+ \begin{verbatim}
+ 10 PRINT "HELLO WORLD ";
+ 20 GOTO 10
+ \end{verbatim}
+
+
+10 PRINT "HELLO WORLD ";
+
+20 GOTO 10
+
+
+Within a paragraph, similar behavior can be accessed with
+::
+
+ \verb+text+
+
+The + is just an example of a delimiter character. You can use any character except letters, * or space.
+
+The starred verstion of the verbatim environment emphasizes the spaces in the text.
+::
+
+ \begin{verbatim*}
+ 10 PRINT "HELLO WORLD ";
+ 20 GOTO 10
+ \end{verbatim*}
+
+10␣PRINT␣"HELLO␣WORLD␣";
+
+20␣GOTO␣10
+
+Tables, Figures and Captions
+----------------------------
+
+The ``\tabular`` environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The tabular environment can be used to typeset beautiful tables with optional horizontal and vertical lines. LaTeX determines the width of the columns automatically.
+::
+
+ \begin{tabular}[pos]{table spec}
+
+The table spec argument defines the format of the table. Use an ``l`` for a column of left-aligned text, ``r`` for right-aligned text, and ``c`` for centred text; ``p{width}`` for a column containing justified text with line breaks, and ``|`` for a vertical line.
+
+If the text in a column is too wide for the page, LaTeX won’t automatically wrap it. Using ``p{width}`` you can define a special type of column which will wrap-around the text as in a normal paragraph.
+
+The pos argument specifies the vertical position of the table relative to the baseline of the surrounding text. Use either of the letters ``t`` , ``b`` and ``c`` to specify table alignment at the top, bottom or center.
+
+Within a tabular environment, ``&`` jumps to the next column, ``\\`` starts a new line and ``\hline`` inserts a horizontal line. You can add partial lines by using the ``\cline{i-j}``, where ``i`` and ``j`` are the column numbers the line should extend over.
+
+::
+
+ \begin{tabular}{|r|l|}
+ \hline
+ 7C0 & hexadecimal \\
+ 3700 & octal \\ \cline{2-2}
+ 11111000000 & binary \\
+ \hline \hline
+ 1984 & decimal \\
+ \hline
+ \end{tabular}
+
+[include an image of a table, as example]
+
+Importing Graphics
+~~~~~~~~~~~~~~~~~~
+
+Strictly speaking, LaTeX cannot manage pictures directly: in order to introduce graphics within documents, LaTeX just creates a box with the same size of the image you want to include and embeds the picture, without any other processing. This means you will have to take care that the images you want to include are in the right format to be included. This is not such a hard task because LaTeX supports the most common picture formats around.
+
+We need to load the ``graphicx`` package in the preamble of the document to be able to include images.
+::
+
+ \usepackage{graphicx}
+
+When compiling with ``pdflatex`` command, (which we assume is being used all through this course) you can insert **jpg**, **png** and **pdf** files.
+
+::
+
+ \includegraphics[optional arguments]{imagename}
+
+A few ``optional arguments``:
+
+ ``width=xx``
+ specify the width of the imported image to ``xx``.
+
+ ``height=xx``
+ specify the height of the imported image to ``xx``.
+ Specifying only the width or height of the image will scale the image whilst maintaining the aspect ratio.
+
+ ``keepaspectratio``
+ This can be either set to true or false. When set to true, it will scale the image according to both width and height, without distorting the image so that it does not exceed both the width and the height dimensions.
+
+ ``scale=xx``
+ Scale the image by a factor of ``xx``. For eg. ``scale=2``, will double the image size.
+
+ ``angle=xx``
+ This option can be used to rotate the image by ``xx`` degrees, anti-clockwise.
+
+
+Floats
+~~~~~~
+
+Figures and Tables need special treatment, because they cannot be broken across pages. One method would be to start a new page every time a figure or a table is too large to fit on the present page. This approach would leave pages partially empty, which looks very bad.
+
+The solution to this problem is to ‘float’ any figure or table that does not fit on the current page to a later page, while filling the current page with body text. LaTeX offers two environments for floating bodies; one for tables and one for figures. To take full advantage of these two environments it is important to understand approximately how LaTeX handles floats internally.
+
+Any material enclosed in a figure or table environment will be treated as floating matter.
+::
+
+ \begin{figure}[placement specifier] or
+ \begin{table}[placement specifier]
+
+Both float environments support an optional parameter called the placement specifier. This parameter is used to tell LaTeX about the locations to which the float is allowed to be moved. A placement specifier is constructed by building a string of float-placing permissions.
+
++-----------+-------------------------------------------------------------------+
+| Specifier | Permission |
++-----------+-------------------------------------------------------------------+
+| h | Place the float here |
+| | (approximately at the same point it occurs in the source text) |
++-----------+-------------------------------------------------------------------+
+| t | Position at the top of the page. |
++-----------+-------------------------------------------------------------------+
+| b | Position at the bottom of the page. |
++-----------+-------------------------------------------------------------------+
+| p | Put on a special page for floats only. |
++-----------+-------------------------------------------------------------------+
+| ! | Override internal parameters Latex uses for determining “good” |
+| | float positions. |
++-----------+-------------------------------------------------------------------+
+| H | Places the float at precisely the location in the LaTeX code. |
+| | Requires the float package. ``\usepackage{float}``. |
+| | This is somewhat equivalent to h! |
++-----------+-------------------------------------------------------------------+
+
+Examples::
+
+ \begin{table}[!hbp]
+ \begin{tabular}{...}
+ ... table data ...
+ \end{tabular}
+ \end{table}
+
+ \begin{figure}[b]
+ \includegraphics[scale=0.5]{image1.jpg}
+ \end{figure}
+
+
+Captions
+~~~~~~~~
+
+It is always good practice to add a caption to any figure or table. All you need to do is use the ``\caption{text}`` command within the float environment. LaTeX will automatically keep track of the numbering of figures, so you do not need to include this within the caption text.
+
+The location of the caption is traditionally underneath the float. However, it is up to you to therefore insert the caption command after the actual contents of the float (but still within the environment). If you place it before, then the caption will appear above the float.
+::
+
+ \begin{figure}[b]
+ \caption{This is a caption at the top of the image}
+ \includegraphics[scale=0.5]{image1.jpg}
+ \end{figure}
+
+ \begin{figure}[b]
+ \includegraphics[scale=0.5]{image1.jpg}
+ \caption{This is a caption at the bottom of the image}
+ \end{figure}
+
+
+List of Figures, Tables
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Captions can be listed in a “List of Tables” or a “List of Figures” section by using the ``\listoftables`` or ``\listoffigures`` commands, respectively. The caption used for each table or figure will appear in these lists, along with the table or figure numbers, and page numbers that they appear on.
+
+The ``\caption`` command also has an optional parameter, ``\caption[short]{long}`` which is used for the List of Tables or List of Figures. Typically the short description is for the caption listing, and the long description will be placed beside the figure or table. This is particularly useful if the caption is long, and only a “one-liner” is desired in the figure/table listing.
+
+Typesetting Math
+----------------
+
+If you wish to typset advanced mathematics, it is best to use the AMS-LaTeX bundle, which is a collection of packages and classes for mathematical typsetting. Note that LaTeX does, provide some basic features and environments for mathematical typsetting, but they are limited and in some cases even inconsistent. We shall stick to using the ``amsmath`` package from the AMS-LaTeX bundle, throughout this course.
+
+We load ``amsmath`` by issuing the ``\usepackage{amsmath}`` in the preamble. Through out this section, it is assumed that the ``amsmath`` package has been loaded.
+
+Math Mode
+~~~~~~~~~
+
+There are a few differences between the *math mode* and the *text mode*:
+
+1. Most spaces and line breaks do not have any significance, as all spaces are either derived logically from the mathematical expressions, or have to be specified with special commands such as ``\,``, ``\quad`` or ``\qquad``
+
+2. Empty lines are not allowed.
+
+3. Each letter is considered to be the name of a variable and will be typeset as such. If you want to typeset normal text within a formula, then you have to enter the text using the \text{...} command
+
+Single Equations
+~~~~~~~~~~~~~~~~
+
+There are two ways to typeset mathematical equations in LaTeX - inline within a paragraph (*text style*), or the paragraph can be broken to typeset it separately (*display style*).
+
+A mathematical equation within a paragraph is entered between ``$`` and ``$``.
+
+If you want the larger equations to be set apart from the paragraph, it is better to use the display style. To do this, you enclose the equations within ``\begin{equation}`` and ``\end{equation}``. You can then \label an equation number and refer to it somewhere else in the text by using the ``\eqref`` command. If you want to name the equation something specific, you ``\tag`` it instead. You can’t use ``\eqref`` with ``\tag``. If you donot want LaTeX to number a particular equation, use the starred version of equation using an ``\begin{equation*}`` and ``\end{equation*}``
+
+[need to include images as examples?]
+
+Building Blocks of a Mathematical Formula
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Greek Letters can are entered as ``\alpha, \beta, \gamma, \delta, ...`` for lowercase letters and ``\Alpha, \Beta, \Gamma, ...`` for uppercase ones.
+
+Exponents and Subscripts can be specified using the ^ and the _ character. Most math mode commands act only on the next character, so if you want a command to affect several characters, you have to group them together using curly braces: {...}.
+
+The square root is entered as ``\sqrt``; the nth root is generated with ``\sqrt[n]``. The size of the root sign is determined automatically by LaTeX. If just the sign is needed, use ``\surd``.
+
+To explicitly show a multiplication a dot may be shown. \cdot could be used, which typesets the dot to the centre. \cdots is three centered dots while \ldots sets the dots on the baseline. Besides that, there are \vdots for vertical and \ddots for diagonal dots.
+
+A fraction can be typeset with the command ``\frac{...}{...}``
+
+The integral operator is generated with ``\int``, the sum operator with ``\sum``, and the product operator with ``\prod``. The upper and lower limits are specified with ``^`` and ``_`` like subscripts and superscripts.
+
+If you put ``\left`` in front of an opening delimiter and ``\right`` in front of a closing delimiter, LaTeX will automatically determine the correct size of the delimiter. Note that you must close every ``\left`` with a corresponding ``\right``.
+
+
+
+Vertically Aligned Material
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Multiple Equations
+++++++++++++++++++
+
+For formulae running over several lines or for equation systems, you can use the environments ``align`` and ``align*`` instead of ``equation`` and ``equation*``. With ``align`` each line gets an equation number. The ``align*`` does not number anything.
+
+The ``align`` environments center the single equation around the ``&`` sign. The ``\\`` command breaks the lines. If you only want to enumerate some of equations, use ``\nonumber`` to remove the number. It has to be placed before the ``\\``.
+
+Arrays and Matrices
++++++++++++++++++++
+
+
+Bibliography
+------------
+
+You can produce a bibliography with the ``thebibliography`` environment.
+
+
+--------------------------------------------------------
+
+Acknowledgements, Attributions
+------------------------------
+
+1. *LaTeX Wikibook*
+
+2. *The Not So Short Introduction to LaTeX2e* by Tobias Oetikar et. al.
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/latex/latex.rst Mon Aug 24 23:33:26 2009 +0530
@@ -0,0 +1,83 @@
+Module 3: LaTeX
+===============
+
+Module Objectives
+-----------------
+
+After completing this module, a participant will be successfully able to:
+
+- Produce professional documents in LaTeX. RBT Ap
+- Typeset Mathematical equations. RBT Ap
+- Include figures, tables and code samples. RBT Ap
+- Add References and write BibTeX files. RBT Ap
+
+Suggested Reading
+-----------------
+
+1. *LaTeX Wikibook*
+
+2. *The Not So Short Introduction to LaTeX2e* by Tobias Oetikar et. al.
+
+
+Session Level Split-up
+----------------------
+
++---------+---------------------------------+---------+
+| Session | Topic | Duration|
++=========+=================================+=========+
+| 1 | Introduction, TeX & LaTeX | 10 min |
+| | WYSIWG vs. WYSIWM | |
+| | | |
+| | LaTeX source, Hello World | 10 min |
+| | Compiling | |
++---------+---------------------------------+---------+
+| 2 | General Document Structure | 15 min |
+| | | |
+| | ``\documentclass``, | |
+| | Document environment, | |
+| | Preamble, | |
+| | Packages, | |
+| | Top Matter, | |
+| | Abstract, | |
+| | Sectioning Commands, | |
+| | Appendices, | |
+| | ToC, Bibliography, | |
+| | Including files | |
++---------+---------------------------------+---------+
+| 3 | Line & Page Breaks, | 5 min |
+| | Symbols & Special Characters, | |
+| | Emphasized words | |
+| | | |
+| | Cross References, | 5 min |
+| | Footnotes, | |
+| | | |
+| | Enumerate, Itemize, Description | 5 min |
+| | | |
+| | Flushleft, Flushright, Center | 5 min |
+| | Quote, Quotation and Verse, | |
+| | Abstract, | |
+| | Verbatim | |
++---------+---------------------------------+---------+
+| | Buffer time | 5 min |
++---------+---------------------------------+---------+
+| 4 | ``\tabular`` environment, | 15 min |
+| | Importing Graphics, Floats | |
+| | | |
+| | Captions, List of Figures, | 5 min |
+| | List of Tables | |
++---------+---------------------------------+---------+
+| 5 | ``\usepackage{amsmath}``, | 5 min |
+| | Single Equations | |
+| | | |
+| | Building blocks of an equation, | 15 min |
+| | Multiple Equations, Arrays and | |
+| | Matrices | |
++---------+---------------------------------+---------+
+| 6 | ``\thebibliography`` | 15 min |
+| | environment, BibTeX | |
++---------+---------------------------------+---------+
+| | Buffer time | 5 min |
++---------+---------------------------------+---------+
+
+
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/ult/Using_Linux_Tools.rst Mon Aug 24 23:33:26 2009 +0530
@@ -0,0 +1,196 @@
+1. Introduction to the Course
+=============================
+
+Engineering students use computers for a large number of curricular
+tasks – mostly computation centred. However, they do not see this as coding or programming tasks and usually are not even aware of the tools and
+techniques that will help them to handle these tasks better. This results
+in less than optimal use of their time and resources. This also causes
+difficulties when it comes tocollaboration and building on other people’s
+work. This course is intended to train such students in good software
+practices and tools for producing code and documentation.
+
+After successfully completing the program, the participants will be able to:
+
+- understand how software tools work together and how they can be used in tandem to carry out tasks,
+
+- use unix command line tools to carry out common (mostly text processing tasks,
+
+- to generate professional documents,
+
+- use version control effectively – for both code and documents,
+
+- automate tasks by writing shell scripts and python scripts,
+
+- realise the impact of coding style and readbility on quality,
+
+- write mid-sized programs that carry out typical engineering / numerical computations such as those that involve (basic) manipulation of large arrays in an efficient manner,
+
+- generate 2D and simple 3D plots,
+
+- debug programs using a standardised approach,
+
+- understand the importance of tests and the philosophy of Test Driven Development,
+
+- write unit tests and improve the quality of code.
+
+2. Introducing Linux
+=====================
+
+Linux (commonly pronounced ˈlɪnəks') is a generic term referring to Unix-like computer operating systems based on the Linux kernel. Their development is one of the most prominent examples of free and open source software collaboration; typically all the underlying source code can be used, freely modified, and redistributed by anyone under the terms of the GNU Global Public License (GPL) and other free software licences.
+
+Linux is predominantly known for its use in servers, although it is installed on a wide variety of computer hardware, ranging from embedded devices and mobile phones to supercomputers.
+
+The name "Linux" comes from the Linux kernel, originally written in 1991 by Linus Torvalds. The rest of the system usually comprises components such as the Apache HTTP Server, the X Window System, the GNOME and KDE desktop environments, and utilities and libraries from the GNU Project (announced in 1983 by Richard Stallman). Commonly-used applications with desktop Linux systems include the Mozilla Firefox web-browser and the OpenOffice.org office application suite. The GNU contribution is the basis for the Free Software Foundation's preferred name GNU/Linux
+
+Historical Background
+----------------------
+
+Events leading to the creation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+- The Unix operating system was conceived and implemented in the 1960s and first released in 1970. Its availability and portability caused it to be widely adopted, copied and modified by academic institutions and businesses. Its design became influential to authors of other systems.
+
+- In 1983, Richard Stallman started the GNU project with the goal of creating a free UNIX-like operating system. As part of this work, he wrote the GNU General Public License (GPL). By the early 1990s there was almost enough available software to create a full operating system. However, the GNU kernel, called Hurd, failed to attract enough attention from developers leaving GNU incomplete.
+
+- Another free operating system project in the 1980s was the Berkeley Software Distribution (BSD). This was developed by UC Berkeley from the 6th edition of Unix from AT&T. Since BSD contained Unix code that AT&T owned, AT&T filed a lawsuit (USL v. BSDi) in the early 1990s against the University of California. This strongly limited the development and adoption of BSD.
+
+- MINIX, a Unix-like system intended for academic use, was released by Andrew S. Tanenbaum in 1987. While source code for the system was available, modification and redistribution were restricted. In addition, MINIX's 16-bit design was not well adapted to the 32-bit features of the increasingly cheap and popular Intel 386 architecture for personal computers.
+
+- These factors of a lack of a widely-adopted, free kernel provided the impetus for Torvalds's starting his project. He has stated that if either the GNU or 386BSD kernels were available at the time, he likely would not have written his own.
+
+The Creation of Linux
+~~~~~~~~~~~~~~~~~~~~~~
+In 1991, in Helsinki, Linus Torvalds began a project that later became the Linux kernel. It was initially a terminal emulator, which Torvalds used to access the large UNIX servers of the university. He wrote the program specifically for the hardware he was using and independent of an operating system because he wanted to use the functions of his new PC with an 80386 processor. Development was done on Minix using the GNU C compiler. This application is still the main choice for compiling Linux today (although the code can be built with other compilers, such as the Intel C Compiler).
+
+Torvalds continues to direct the development of the kernel. Stallman heads the Free Software Foundation, which in turn supports the GNU components. Finally, individuals and corporations develop third-party non-GNU components. These third-party components comprise a vast body of work and may include both kernel modules and user applications and libraries. Linux vendors and communities combine and distribute the kernel, GNU components, and non-GNU components, with additional package management software in the form of Linux distributions.
+
+For the 2.6.29 release only, the kernel's mascot, a penguin named Tux, was temporarily replaced by Tuz in order to highlight efforts to save the Tasmanian Devil from extinction.
+
+Design and Implications
+------------------------
+
+A Linux-based system is a modular Unix-like operating system. It derives much of its basic design from principles established in Unix during the 1970s and 1980s. Such a system uses a monolithic kernel, the Linux kernel, which handles process control, networking, and peripheral and file system access. Device drivers are integrated directly with the kernel.
+
+Separate projects that interface with the kernel provide much of the system's higher-level functionality. The GNU userland is an important part of most Linux-based systems, providing the most common implementation of the C library, a popular shell, and many of the common Unix tools which carry out many basic operating system tasks. The graphical user interface (or GUI) used by most Linux systems is based on the X Window System.
+
+User Interface
+~~~~~~~~~~~~~~
+Users can control a Linux-based system through a command line interface (or CLI), a graphical user interface (or GUI), or through controls attached to the associated hardware (this is common for embedded systems). For desktop systems, the default mode is usually graphical user interface (or GUI).
+
+On desktop machines, KDE, GNOME and Xfce are the most popular user interfaces,[36] though a variety of additional user interfaces exist. Most popular user interfaces run on top of the X Window System (or X), which provides network transparency, enabling a graphical application running on one machine to be displayed and controlled from another.
+
+Other GUIs include X window managers such as FVWM, Enlightenment and Window Maker. The window manager provides a means to control the placement and appearance of individual application windows, and interacts with the X window system. This is a more minimalist goal than KDE, GNOME et al., which are termed desktop environments.
+
+A Linux system typically provides a CLI of some sort through a shell, which is the traditional way of interacting with a Unix system. A Linux distribution specialized for servers may use the CLI as its only interface. A “headless system” run without even a monitor can be controlled by the command line via a remote-control protocol such as SSH or telnet.
+
+Most low-level Linux components, including the GNU Userland, use the CLI exclusively. The CLI is particularly suited for automation of repetitive or delayed tasks, and provides very simple inter-process communication. A graphical terminal emulator program is often used to access the CLI from a Linux desktop.
+
+Development
+~~~~~~~~~~~
+The primary difference between Linux and many other popular contemporary operating systems is that the Linux kernel and other components are free and open source software. Linux is not the only such operating system, although it is by far the most widely used. Some free and open source software licenses are based on the principle of copyleft, a kind of reciprocity: any work derived from a copyleft piece of software must also be copyleft itself. The most common free software license, the GNU GPL, is a form of copyleft, and is used for the Linux kernel and many of the components from the GNU project.
+
+Linux based distributions are intended by developers for interoperability with other operating systems and established computing standards. Linux systems adhere to POSIX, SUS, ISO and ANSI standards where possible, although to date only one Linux distribution has been POSIX.1 certified, Linux-FT.
+
+Free software projects, although developed in a collaborative fashion, are often produced independently of each other. The fact that the software licenses explicitly permit redistribution, however, provides a basis for larger scale projects that collect the software produced by stand-alone projects and make it available all at once in the form of a Linux distribution.
+
+A Linux distribution, commonly called a "distro", is a project that manages a remote collection of system software and application software packages available for download and installation through a network connection. This allows the user to adapt the operating system to his/her specific needs. Distributions are maintained by individuals, loose-knit teams, volunteer organizations, and commercial entities. A distribution can be installed using a CD that contains distribution-specific software for initial system installation and configuration. A package manager such as Synaptic or YAST allows later package upgrades and installations. A distribution is responsible for the default configuration of the installed Linux kernel, general system security, and more generally integration of the different software packages into a coherent whole.
+
+Community
+~~~~~~~~~
+A distribution is largely driven by its developer and user communities. Some vendors develop and fund their distributions on a volunteer basis, Debian being a well-known example. Others maintain a community version of their commercial distributions, as Red Hat does with Fedora.
+
+In many cities and regions, local associations known as Linux Users Groups (LUGs) seek to promote their preferred distribution and by extension free software. They hold meetings and provide free demonstrations, training, technical support, and operating system installation to new users. Many Internet communities also provide support to Linux users and developers. Most distributions and free software / open source projects have IRC chatrooms or newsgroups. Online forums are another means for support, with notable examples being LinuxQuestions.org and the Gentoo forums. Linux distributions host mailing lists; commonly there will be a specific topic such as usage or development for a given list.
+
+There are several technology websites with a Linux focus. Print magazines on Linux often include cover disks including software or even complete Linux distributions.
+
+Although Linux distributions are generally available without charge, several large corporations sell, support, and contribute to the development of the components of the system and of free software. These include Dell, IBM, HP, Oracle, Sun Microsystems, Novell, Nokia. A number of corporations, notably Red Hat, have built their entire business around Linux distributions.
+
+The free software licenses, on which the various software packages of a distribution built on the Linux kernel are based, explicitly accommodate and encourage commercialization; the relationship between a Linux distribution as a whole and individual vendors may be seen as symbiotic. One common business model of commercial suppliers is charging for support, especially for business users. A number of companies also offer a specialized business version of their distribution, which adds proprietary support packages and tools to administer higher numbers of installations or to simplify administrative tasks. Another business model is to give away the software in order to sell hardware.
+
+Programming on Linux
+~~~~~~~~~~~~~~~~~~~~
+Most Linux distributions support dozens of programming languages. The most common collection of utilities for building both Linux applications and operating system programs is found within the GNU toolchain, which includes the GNU Compiler Collection (GCC) and the GNU build system. Amongst others, GCC provides compilers for Ada, C, C++, Java, and Fortran. The Linux kernel itself is written to be compiled with GCC. Proprietary compilers for Linux include the Intel C++ Compiler, Sun Studio, and IBM XL C/C++ Compiler.
+
+Most distributions also include support for PHP, Perl, Ruby, Python and other dynamic languages. Examples of languages that are less common, but still supported, are C# via the Mono project, sponsored by Novell, and Scheme. A number of Java Virtual Machines and development kits run on Linux, including the original Sun Microsystems JVM (HotSpot), and IBM's J2SE RE, as well as many open-source projects like Kaffe.
+
+The two main frameworks for developing graphical applications are those of GNOME and KDE. These projects are based on the GTK+ and Qt widget toolkits, respectively, which can also be used independently of the larger framework. Both support a wide variety of languages. There are a number of Integrated development environments available including Anjuta, Code::Blocks, Eclipse, KDevelop, Lazarus, MonoDevelop, NetBeans, and Omnis Studio while the long-established editors Vim and Emacs remain popular.
+
+Reasons for Using Linux
+-----------------------
+- Linux is free:
+
+As in free beer, they say. If you want to spend absolutely nothing, you don't even have to pay the price of a CD. Linux can be downloaded in its entirety from the Internet completely for free. No registration fees, no costs per user, free updates, and freely available source code in case you want to change the behavior of your system.
+Most of all, Linux is free as in free speech:
+The license commonly used is the GNU Public License (GPL). The license says that anybody who may want to do so, has the right to change Linux and eventually to redistribute a changed version, on the one condition that the code is still available after redistribution. In practice, you are free to grab a kernel image, for instance to add support for teletransportation machines or time travel and sell your new code, as long as your customers
+can still have a copy of that code.
+
+- Linux is portable to any hardware platform:
+
+A vendor who wants to sell a new type of computer and who doesn't know what kind of OS his new machine will run (say the CPU in your car or washing machine), can take a Linux kernel and make it work on his hardware, because documentation related to this activity is freely available.
+
+- Linux was made to keep on running:
+
+As with UNIX, a Linux system expects to run without rebooting all the time. That is why a lot of tasks are being executed at night or scheduled automatically for other calm moments, resulting in higher availability during busier periods and a more balanced use of the hardware. This property allows for Linux to be applicable also in environments where people don't have the time or the possibility to control their systems night and day.
+
+- Linux is secure and versatile:
+
+The security model used in Linux is based on the UNIX idea of security, which is known to be robust and of proven quality. But Linux is not only fit for use as a fort against enemy attacks from the Internet: it will adapt equally to other situations, utilizing the same high standards for security. Your development machine or control station will be as secure as you firewall.
+
+- Linux is scalable:
+
+From a Palmtop with 2 MB of memory to a petabyte storage cluster with hundreds of nodes: add or remove the appropriate packages and Linux fits all. You don't need a supercomputer anymore,because you can use Linux to do big things using the building blocks provided with the system. If you want to do little things, such as making an operating system for an embedded processor or just recycling your old 486, Linux will do that as well.
+
+- The Linux OS and Linux applications have very short debug−times:
+
+Because Linux has been developed and tested by thousands of people, both errors and people to fix them are found very quickly. It often happens that there are only a couple of hours between discovery and fixing of a bug.
+
+3. Getting Started
+===================
+Logging in, activating the user interface and logging out
+----------------------------------------------------------
+In order to work on a Linux system directly, you will need to provide a user name and password. You always need to authenticate to the system. Most PC−based Linux systems have two basic modes for a system to run in: either quick and sober in text console mode, which looks like DOS with mouse, multitasking and multi−user features, or in graphical console mode, which
+looks better but eats more system resources.
+
+Graphical Mode
+~~~~~~~~~~~~~~
+This is the default nowadays on most desktop computers. You know you will connect to the system using graphical mode when you are first asked for your user name, and then, in a new window, to type your password.
+
+To log in, make sure the mouse pointer is in the login window, provide your user name and password to the system and click *OK* or press *Enter*.
+It is generally considered a bad idea to connect (graphically) using the root user name, the system adminstrator's account, since the use of graphics includes running a lot of extra programs, in root's case with a lot of extra permissions. To keep all risks as low as possible, use a normal user account to connect graphically. But there are enough risks to keep this in mind as a general advice, for all use of the root account: only log in as root when extra privileges are required.
+
+After entering your user name/password combination, it can take a little while before the graphical environment is started, depending on the CPU speed of your computer, on the software you use and on your personal settings.
+
+To continue, you will need to open a *terminal window* or *xterm* for short (X being the name for the underlying software supporting the graphical environment). This program can be found in the *Applications−>Utilities,
+System Tools* or *Internet menu*, depending on what window manager you are using. There might be icons that you can use as a shortcut to get an xterm window as well, and clicking the right mouse button on the desktop background will usually present you with a menu containing a terminal window application.
+
+While browsing the menus, you will notice that a lot of things can be done without entering commands via the keyboard. For most users, the good old point−'n'−click method of dealing with the computer will do. But this
+guide is for future network and system administrators, who will need to meddle with the heart of the system.
+
+They need a stronger tool than a mouse to handle all the tasks they will face. This tool is the shell, and when in graphical mode, we activate our shell by opening a terminal window.
+
+The terminal window is your control panel for the system. Almost everything that follows is done using this simple but powerful text tool. A terminal window should always show a command prompt when you open one. This terminal shows a standard prompt, which displays the user's login name, and the current working directory, represented by the twiddle (~)
+
+Another common form for a prompt is this one:
+[user@host dir]
+
+In the above example, *user* will be your login name, *hosts* the name of the machine you are working on, and *dir* an indication of your current location in the file system.Prompts can display all kinds of information, but that they are not part of the commands you are giving to your system. To disconnect from the system in graphical mode, you need to close all terminal windows and other applications. After that, hit the logout icon or find Log Out in the menu. Closing everything is not really
+necessary, and the system can do this for you, but session management might put all currently open applications back on your screen when you connect again, which takes longer and is not always the desired effect. However, this behavior is configurable.
+
+When you see the login screen again, asking to enter user name and password, logout was successful.
+
+Text Mode
+~~~~~~~~~
+You know you're in text mode when the whole screen is black, showing (in most cases white) characters. A text mode login screen typically shows some information about the machine you are working on, the name of the machine and a prompt waiting for you to log in.
+
+The login is different from a graphical login, in that you have to hit the *Enter* key after providing your user name, because there are no buttons on the screen that you can click with the mouse. Then you should type
+your password, followed by another *Enter*. You won't see any indication that you are entering something, not even an asterisk, and you won't see the cursor move. But this is normal on Linux and is done for security
+reasons.
+
+When the system has accepted you as a valid user, you may get some more information, called the *message of the day*, which can be anything. Additionally, it is popular on UNIX systems to display a fortune cookie,
+which contains some general wise or unwise (this is up to you) thoughts. After that, you will be given a shell, indicated with the same prompt that you would get in graphical mode.
+
+Also in text mode: log in as root only to do setup and configuration that absolutely requires administrator privileges, such as adding users, installing software packages, and performing network and other system configuration. Once you are finished, immediately leave the special account and resume your work as a non−privileged user.
+
+Logging out is done by entering the logout command, followed by Enter. You are successfully disconnected from the system when you see the login screen again.Don't power−off the computer after logging out. It is not meant to be shut off without application of the proper procedures for halting the system. Powering it off without going through the halting process might cause severe damage!
+
+
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/ult/ult_module_plan.rst Mon Aug 24 23:33:26 2009 +0530
@@ -0,0 +1,98 @@
+Module 1: Using Linux Tools
+============================
+
+Module Objectives
+----------------------
+
+After successfully completing this module a participant will be able to:
+
+* Understand the design philosophy of \*nix {U}
+* Use Linux as their day-to-day operating system {Ap}
+* Use the text processing tools such as 'grep', 'tr' {Ap}
+* Write and execute (bash) shell scripts {Ap}
+* Use a text editor comfortably {Ap}
+
+Suggested Reading
+-----------------------
+
+(1) "In the beginning..." by Neal Stephenson
+(2) "The Unix Programming Environment" by Kerninghan and Pike
+
+**Initial Session Plan**
+
++---------+---------------------------------+---------+
+| Session | Topic | Duration|
++=========+=================================+=========+
+| 1 | Introduction to the Course | 5 mt |
+| | | |
+| | Historical background and | 10 mts |
+| | implications. Why Unix? | |
+| | | |
+| | Getting started–logging in; *ls,| 10 mts |
+| | date, who, cd, mkdir* | |
+| | | |
+| | Getting help: *apropos, man, | 10 mts |
+| | info* | |
+| | | |
+| | Basic file handling: *cp, mv, | 10 mts |
+| | rm* | |
+| | | |
+| | First session buffer | 5 mts |
++---------+---------------------------------+---------+
+| 2 | Command line arguments | 5 mts |
+| | | |
+| | Basic text processing: *head, | 15 mts |
+| | tail, cut, paste* | |
+| | | |
+| | Shell meta characters | 10 mts |
+| | | |
+| | Looking at files: *cat, less* | 5 mts |
+| | | |
+| | Directory structure: *man hier, | 5 mts |
+| | ls -l* | |
+| | | |
+| | Permissions and ownership, | 10 mts |
+| | *chmod, chown* | |
++---------+---------------------------------+---------+
+| 3 | Redirection and Piping | 10 mts |
+| | | |
+| | More text processing:*grep, tr* | 10 mts |
+| | | |
+| | Elementary regex: . ? * ^ $ [ ] | 15 mts |
+| | | |
+| | One liners: show lines n to m, | 15 mts |
+| | show directories | |
++---------+---------------------------------+---------+
+| 4 | More text processing: *join, | 10 mts |
+| | sprt, uniq* | |
+| | | |
+| | Generating a word frequency list| 10 mts |
+| | | |
+| | Basic editing and editors : vim,| 10 mts |
+| | scite | |
+| | | |
+| | Personalising your environment: | 10 mts |
+| | *.bashrc, .vimrc* | |
+| | | |
+| | Subshells and *source~* | 10 mts |
++---------+---------------------------------+---------+
+| 5 | More tools: *tar, zip, diff, | 25 mts |
+| | cmp, comm* | |
+| | | |
+| | Environment variables, *set* | 10 mts |
+| | | |
+| | Writing simple shell scripts | 15 mts |
++---------+---------------------------------+---------+
+| 6 | Control structures and | 20 mts |
+| | operators in bash | |
+| | | |
+| | Writing shell scripts | 30 mts |
++---------+---------------------------------+---------+
+| 7 | Functions in bash scripts | 20 mts |
+| | | |
+| | Assessment Test | 30 mts |
++---------+---------------------------------+---------+
+
+*total session time = 350 mts*
+
+*buffer time = 10 mts*
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/versionControl/handOut.rst Mon Aug 24 23:33:26 2009 +0530
@@ -0,0 +1,518 @@
+
+=================
+ Version Control
+=================
+
+Introduction
+============
+
+The following words are from a blogpost "http://karlagius.com/2009/01/09/version-control-for-the-masses/"
+
+"Version control is one of those weird, geeky things that never really gained much ground in non-geek fields, despite the fact that it’s blindingly useful.
+
+Version control (or source control) is nothing more arcane than keeping copies of ones work as one make changes to it. On the surface, it’s all straight-forward; make a copy of every file before making any changes to it. That way, if something seriously messes up, one can always fall back to something that worked before, or at least compare the broken copy with one that used to work so one can figure out where it went off kilter. Accidentally deleted half of thesis and closed the word processor? No problem – out comes the backup."
+
+Now, in the real world, it’s not so easy. One probably cooks up their own version control system without realizing it had such a geeky name. For instances files with names oldxxxxxx.odt and latestxxxxxx.odt. Every time to make some change in a file, one save it with different name then the original one. Luckily there are like, loads of version control systems out there to do this heavy lifting.
+
+Why Use Version Control
+=======================
+
+"Its the start which most people fail to attempt".
+One of idea behind Version Control Tools was to save that "one" step, to build onto it, rather then simply loose it. So here are some reasons why is automated version control needed:
+
+ - It will track the history and evolution of a project, so one don't have to do it manually. It allows to track what changes where made, when were they made, by whom and why.
+ - For a team of people working on same project, revision control software makes it easier to collaborate. For example, when people more or less simultaneously make potentially incompatible changes, the software will help them to identify and resolve those conflicts.
+ - It can help to recover from mistakes. If a change made at some moment of time, turns out to be in error in future, one can revert to an earlier version of one or more files. In fact, a really good revision control tool will even help in efficiently figure out exactly when a problem was introduced.
+
+Most of these reasons are equally valid for the project having one man show, or hundred people. Besides projects, even it can be used to maintain assignments related to one particular subject/course, it will help manage things in way much better way. These tools can be used for better *resources management*. All codes, documents, presentation, assignments related to one course maintained in such a inventory can help avoiding accidental lose of data(deletion) and Internet hosting for version control will make the work immune to local hard-disk crash, unless hosting crashes itself.
+
+Some of Version Control Tools available and used widely are:
+
+ - cvs (Concurrent Version System)
+ - svn (Subversion)
+ - hg (Mercurial)
+ - bzr (Bazaar)
+ - git
+
+Each of above mentioned tools have sets of feature which it offers in unique way. For this session we are going to concentrate on hg (mercurial). After covering the basics of hg, one can easily try other tools, and use what-ever he/she is most comfortable with.
+
+Learning the Lingo
+==================
+
+Each Version Control uses its own nomenclature for more or less the same features. Here are some of terms which are going to used through out the rest of session:
+
+Basic Setup
+-----------
+
+ Repository(repo):
+ The database/folder storing the files.
+ Server:
+ The computer storing the repo.
+ Client:
+ The computer connecting to the repo.
+ Working Set/Working Copy:
+ Your local directory of files, where you make changes. This is what is present on client side.
+ Trunk/Main:
+ The “primary” location for code in the repo. Think of code as a family tree — the “trunk” is the main line. This is generally what is present on server.
+
+Basic Actions
+-------------
+
+ Add:
+ Put a file into the repo for the first time, i.e. begin tracking it with Version Control.
+ Revision:
+ What version a file is on.
+ Head/Tip:
+ The latest revision of the repo.
+ Check out:
+ Initial download of repo onto machine.
+ Commit:
+ Upload a file to repository(if it has changed). The file gets a new revision number, and people can “check out” the latest one.
+ Checking Message:
+ A short message describing what was changed.
+ Change log/History:
+ A list of changes made to a file since it was created.
+ Update/Sync:
+ Synchronize local files with the latest from the repository on server. This get the latest revisions of all files.
+ Revert:
+ Throw away the local changes and reload the latest version from the repository.
+
+Advanced Actions:
+-----------------
+
+ Branch:
+ Create a separate copy of a file/folder for private use (bug fixing, testing, etc).
+ Diff/Change:
+ Finding the differences between two files. Useful for seeing what changed between revisions.
+ Merge (or patch):
+ Apply the changes from one file to another, to bring it up-to-date.
+ Conflict:
+ When pending changes to a file contradict each other (both changes cannot be applied).
+ Resolve:
+ Fixing the changes that contradict each other and checking in the correct version.
+
+Types of Version Control:
+-------------------------
+
+Based on how source/code management is carried out in a tool there are two categories of Version Control Systems(VCS):
+
+ - Centralized VCS:
+ In this kind of system all the revision control functions are performed on a shared server. If two developers try to change the same file at the same time, without some method of managing access the developers may end up overwriting each other's work. Centralized revision control systems solve this problem in one of two different "source management models": file locking and version merging. Both svn and cvs follows this kind of management.
+
+ - Distributed VCS:
+ In a distributed model, every developer has their own repo. Diffs, commits, and reverts are all done locally, one needs Internet only to share the changes with others. It makes work faster, handles branching and merging in better way, with less management. hg, bzr and git uses this work flow.
+
+Get Going with Hg:
+==================
+
+Why hg?
+-------
+
+ - It is easy to learn and use.
+ - It is lightweight.
+ - It scales excellently.
+ - It is based on Python.
+
+Getting Started:
+----------------
+
+Following command tells the version of hg installed on machine: ::
+
+ $hg version
+
+ Mercurial Distributed SCM (version 1.1.2)
+ Copyright (C) 2005-2008 Matt Mackall <mpm@selenic.com> and others
+ This is free software; see the source for copying conditions. There is NO
+ warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+
+Built-in help, Mercurial provides a built-in help system. Following command will print a brief list of commands, along with a description of what each does. ::
+
+ $hg help
+
+ Mercurial Distributed SCM
+ list of commands:
+ add add the specified files on the next commit
+ addremove -----------------------
+
+For specific command, just follow the command name after the help. ::
+
+ $hg help diff
+ hg diff [OPTION]... [-r REV1 [-r REV2]] [FILE]...
+
+ diff repository (or selected files)
+ Show differences between revisions for the specified files.
+ Differences between files are shown using the unified diff format.
+ NOTE:____________
+
+Let there be Repository:
+------------------------
+
+In Mercurial, everything happens inside a repository. The repository for a project contains all of the files that “belong to” that project, along with a historical record of the project's files. A repository is simply a directory tree in filesystem that Mercurial treats as special.
+
+There can be two ways to create a repo, either getting local copy for existing repo available on Internet or machine, or creating a new repo. For getting already existing repo hg uses command *"clone"* ::
+
+ $hg clone http://hg.serpentine.com/tutorial/hello localCopyhello
+
+ requesting all changes
+ adding changesets
+ adding manifests
+ adding file changes
+ added 5 changesets with 5 changes to 2 files
+ updating working directory
+ 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
+
+If clone succeeded, there would be a local directory called localCopyhello, with some files: ::
+
+ $ls localCopyhello/
+ hello.c Makefile
+
+Every Mercurial repository is complete, self-contained, and independent. It contains its own private copy of a project's files and history.
+
+To start a new repository use *hg init*: ::
+
+ $ mkdir Fevicol
+ $ cd Fevicol/
+ $ echo "print 'Yeh Fevicol ka Majboot jod hai'" > feviStick.py
+ $ ls -a
+ . .. feviStick.py
+ $ hg init
+ $ ls -a
+ . .. feviStick.py .hg
+
+*.hg* directory indicates that this new dir is now a repo.This is where Mercurial keeps all of its metadata for the repository.The contents of the .hg directory and its subdirectories are private to Mercurial. Rest all files are for the user to use them as they pleases.
+
+Creating a branch of existing local repo is very easy via hg using clone command: ::
+
+ $ hg clone localCopyhello newCopy
+ updating working directory
+ 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
+
+newCopy is exact copy of already existing repo. And this command can be used to create branch of locally created repo also: ::
+
+ $ hg clone Fevicol Fevicol-pull
+ updating working directory
+ 0 files updated, 0 files merged, 0 files removed, 0 files unresolved
+
+These local branches can prove really handy at times. It allows keep multiple copies of local branch for different purposes, say for debugging, testing, working version.
+
+History or Logs:
+----------------
+
+For the new repo created, first thing which can be tried is to check the logs/history. What changes were made and when and why, answers to all those questions are stored in logs safely. So for the the cloned repo the history can be viewed using command *"log"* (following commands are wrt localCopyhello repo). ::
+
+ $hg log
+ changeset: 4:2278160e78d4
+ tag: tip
+ user: Bryan O'Sullivan <bos@serpentine.com>
+ date: Sat Aug 16 22:16:53 2008 +0200
+ summary: Trim comments.
+
+ changeset: 3:0272e0d5a517
+ user: Bryan O'Sullivan <bos@serpentine.com>
+ date: Sat Aug 16 22:08:02 2008 +0200
+ summary: Get make to generate the final binary from a .o file.
+
+ changeset: 2:fef857204a0c
+ user: Bryan O'Sullivan <bos@serpentine.com>
+ date: Sat Aug 16 22:05:04 2008 +0200
+ summary: Introduce a typo into hello.c.
+
+ changeset: 1:82e55d328c8c
+ user: mpm@selenic.com
+ date: Fri Aug 26 01:21:28 2005 -0700
+ summary: Create a makefile
+
+ changeset: 0:0a04b987be5a
+ user: mpm@selenic.com
+ date: Fri Aug 26 01:20:50 2005 -0700
+ summary: Create a standard "hello, world" program
+
+By default, this command prints a brief paragraph of output for each change to the project that was recorded.The fields in a record of output from hg log are as follows:
+
+ - changeset: This field has the format of a number, followed by a colon, followed by a hexadecimal (or hex) string. These are identifiers for the changeset. The hex string is a unique identifier: the same hex string will always refer to the same changeset in every copy of this repository.
+ - user: The identity of the person who created the changeset.
+ - date: The date and time on which the changeset was created, and the timezone in which it was created.
+ - summary: The first line of the text message that the creator of the changeset entered to describe the changeset.
+ - tag: A tag is another way to identify a changeset, by giving it an easy-to-remember name.
+
+To narrow the output of hg log down to a single revision, use the -r (or --rev) option. ::
+
+ $hg log -r 3
+ changeset: 3:0272e0d5a517
+ user: Bryan O'Sullivan <bos@serpentine.com>
+ date: Sat Aug 16 22:08:02 2008 +0200
+ summary: Get make to generate the final binary from a .o file.
+
+*range notation* can be used to get history of several revisions without having to list each one. ::
+
+ $ hg log -r 2:4
+ changeset: 2:fef857204a0c
+ user: Bryan O'Sullivan <bos@serpentine.com>
+ date: Sat Aug 16 22:05:04 2008 +0200
+ summary: Introduce a typo into hello.c.
+
+ changeset: 3:0272e0d5a517
+ user: Bryan O'Sullivan <bos@serpentine.com>
+ date: Sat Aug 16 22:08:02 2008 +0200
+ summary: Get make to generate the final binary from a .o file.
+
+ changeset: 4:2278160e78d4
+ tag: tip
+ user: Bryan O'Sullivan <bos@serpentine.com>
+ date: Sat Aug 16 22:16:53 2008 +0200
+ summary: Trim comments.
+
+The hg log command's -v (or --verbose) option gives you this extra detail. ::
+
+ $ hg log -v -r 3
+ changeset: 3:0272e0d5a517
+ user: Bryan O'Sullivan <bos@serpentine.com>
+ date: Sat Aug 16 22:08:02 2008 +0200
+ files: Makefile
+ description:
+ Get make to generate the final binary from a .o file.
+
+Making Changes:
+---------------
+
+There is feviStick.py file in repo created above with name feviCol. ::
+
+ $ cd Fevicol
+ $ hg log
+ $ hg status
+ ? feviStick.py
+
+*status(st)* command prints the revision history of the specified files or the entire project. "?" sign in front of file indicates that this file is not yet part of track record. *add* command is used to add new files to repo. ::
+
+ $ hg add feviStick.py
+ $ hg st
+ A feviStick.py
+
+So file is now part of repository(A symbol). Use *commit (alias ci)* command to make changes effective(this command would be explained in more details in later parts). ::
+
+ $ hg ci -u "Shantanu <shantanu@fossee.in>" -m "First commit."
+ $ hg log
+ changeset: 0:84f5e91f4de1
+ tag: tip
+ user: Shantanu <shantanu@fossee.in>
+ date: Fri Aug 21 23:37:13 2009 +0530
+ summary: First commit.
+
+Similar to add there are other commands available for file management in repo. ::
+
+ $ hg cp feviStick.py pidiLite.py
+ $ hg st
+ A pidiLite.py
+
+*copy (alias cp)* command is used to mark files as copied for the next commit. ::
+
+ $ hg rename pidiLite.py feviCol.py
+ $ hg st
+ A feviCol.py
+ $ hg ci -u "Shantanu <shantanu@fossee.in>" -m "Renamed pidiLite.py."
+ $ hg tip
+ changeset: 1:d948fb4137c5
+ tag: tip
+ user: Shantanu <shantanu@fossee.in>
+ date: Sat Aug 22 00:11:25 2009 +0530
+ summary: Renamed pidiLite.py.
+
+*rename(alias mv)* rename files; equivalent of copy + remove. *tip* command shows newest revision in the repository.. ::
+
+ $ hg remove feviCol.py
+ $ hg st
+ R feviCol.py
+
+R status of files denotes, file is marked as to be removed by the previous command *remove*. To add the file again to repo, one can use *revert* command, which restore individual files or dirs to an earlier state. ::
+
+ $ ls
+ feviStick.py
+ $ hg revert feviCol.py
+ $ ls
+ feviCol.py feviStick.py
+
+Sharing Changes:
+----------------
+
+Pulling from repo:
+~~~~~~~~~~~~~~~~~~
+
+As mentioned earlier that repositories in Mercurial are self-contained. This means that the changeset just created exists only in Fevicol repository and not in previously cloned fevicol-pull. There are a few ways that can be used to propagate this change into other repositories. ::
+
+ $ hg clone Fevicol Fevicol-clone
+ updating working directory
+ 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
+
+Or traverse into the any dir which is a working hg repo(using hg init) and pull command will download all changeset from main repo. ::
+
+ $ mkdir Fevicol-pull
+ $ cd Fevicol-pull
+ $ hg init
+ $ hg pull ../Fevicol
+ pulling from ../Fevicol
+ requesting all changes
+ adding changesets
+ adding manifests
+ adding file changes
+ added 2 changesets with 2 changes to 2 files
+ (run 'hg update' to get a working copy)
+
+*changeset* means a list of changes made to a file. In words of *hg help*, pull command is: ::
+
+ pull changes from the specified source
+
+ Pull changes from a remote repository to a local one.
+
+ This finds all changes from the repository at the specified path
+ or URL and adds them to the local repository. By default, this
+ does not update the copy of the project in the working directory.
+
+Some times, even before pulling changesets, one may need to see what changes would be pulled, Mercurial provides *hg incoming* to tell what changes *hg pull* would pull into repo, without actually pulling the changes. This command is really handy in case of avoiding unwanted changesets into the repo.
+
+With Mercurial, *hg pull* does not(by default) touch the working directory. Instead there is *hg up (alias update, co, checkout)* command to do this. ::
+
+ $ cd Fevicol-pull
+ $ ls -a
+ . .. .hg
+ $ hg up
+ 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
+ $ ls -a
+ . .. feviCol.py feviStick.py .hg
+
+To update to specific version, give a version number to the *hg update* command. ::
+
+ $ hg update 0
+ 0 files updated, 0 files merged, 1 files removed, 0 files unresolved
+ $ hg parent
+ changeset: 0:84f5e91f4de1
+ user: Shantanu <shantanu@fossee.in>
+ date: Fri Aug 21 23:37:13 2009 +0530
+ summary: First commit.
+
+If no version number is specified *hg up* will update to the tip version. Version number of hg starts from 0. Compare *hg parent* output to the one before doing update to see the difference.
+
+Making Changes:
+~~~~~~~~~~~~~~~
+
+After getting the desired version of local repo, one can make changes as he/she needs and then make them available(share) for others. For these operations we will be working in Fevicol-clone repo which we created earlier. It's often good practice to keep a “pristine” copy of a remote repository around, which you can then make temporary clones of to create sandboxes for each task you want to work on. ::
+
+ $ cd Fevicol-clone/
+ $ cat cat feviStick.py
+ print 'Yeh Fevicol ka Majboot jod hai'
+
+This tagline is correct for feviCol.py but for feviStick.py it should be different. ::
+
+ $ echo "print 'Ab no more Chip Chip'" > feviStick.py
+ $ cat cat feviStick.py
+ print 'Ab no more Chip Chip'
+ $ hg st
+ M feviStick.py
+
+Mercurial's hg status command will tell us what Mercurial knows about the files in the repository. 'M' sign infront of feviStick.py indicates that Mercurial has noticed change.
+
+It's somewhat helpful to know that feviStick.py was modified, but one might prefer to know exactly what changes were made to it. To do this, use the *hg diff* command. ::
+
+ $ hg diff
+ diff -r a7912d45f47c feviStick.py
+ --- a/feviStick.py Sun Aug 23 22:34:35 2009 +0530
+ +++ b/feviStick.py Sun Aug 23 22:47:49 2009 +0530
+ @@ -1,1 +1,1 @@
+ -print 'Yeh Fevicol ka Majboot jod hai'
+ +print 'Ab no more Chip Chip'
+
+We can modify files, build and test our changes, and use hg status and hg diff to review our changes, until we're satisfied with what we've done and arrive at a natural stopping point where we want to record our work in a new changeset. All the diffs prior to committing the changes would be done wrt earlier marked record.The hg commit command lets us create a new changeset.
+
+Mercurial records your name and address with each change that you commit, so that you and others will later be able to tell who made each change. Mercurial tries to automatically figure out a sensible username to commit the change with. When we try to use *hg commit* there are various ways by which one can specify User name, some of those are:
+
+ - Specify a -u option to the hg commit command on the command line, followed by a username.
+ - set HGUSER environment variable.
+ - Edit hgrc file present in .hg folder to set this property, add following lines to that file and Mercurial will read those parameters from that location.
+
+ [ui]
+ username = Firstname Lastname <email.address@example.net>
+
+For me the hgrc file looks like this: ::
+
+ [paths]
+ default = /home/baali/Fevicol
+ [ui]
+ username = Shantanu Choudhary <shantanu@fossee.in>
+
+Once this parameter is set, *hg commit* command drops us into a text editor, to enter a message that will describe the modifications we've made in this changeset. This is called the commit message. It will be a record for readers of what we did and why, and it will be printed by hg log after we've finished committing. ::
+
+ Changed tagline for feviStick.py.
+ HG: Enter commit message. Lines beginning with 'HG:' are removed.
+ HG: --
+ HG: user: Shantanu Choudhary <shantanu@fossee.in>
+ HG: branch 'default'
+ HG: changed feviStick.py
+
+This would be vi sort of editor, where you can enter the log message in first line, once you are done with log message quit the editor using *[ESC] key ":wq"*.Once we've finished the commit, we can use the hg tip command to display the changeset we just created. ::
+
+ $ hg tip
+ changeset: 3:e1ab2aff4ddd
+ tag: tip
+ user: Shantanu Choudhary <shantanu@fossee.in>
+ date: Sun Aug 23 23:32:01 2009 +0530
+ summary: Changed tagline for feviStick.py.
+
+One can do above mentioned procedure using following one line command: ::
+
+ $ hg ci -u "Shantanu <shantanu@fossee.in>" -m "Changed tagline for feviStick.py."
+
+Sharing Changes:
+~~~~~~~~~~~~~~~~
+
+The *hg outgoing* command tells us what changes would be pushed into another repository. ::
+
+ $ hg outgoing ../Fevicol
+ comparing with ../Fevicol
+ searching for changes
+ changeset: 3:e1ab2aff4ddd
+ tag: tip
+ user: Shantanu Choudhary <shantanu@fossee.in>
+ date: Sun Aug 23 23:32:01 2009 +0530
+ summary: Changed tagline for feviStick.py.
+
+And the hg push command does the actual push. ::
+
+ $ hg push ../Fevicol
+ pushing to ../Fevicol
+ searching for changes
+ adding changesets
+ adding manifests
+ adding file changes
+ added 1 changesets with 1 changes to 1 files
+
+As with hg pull, the hg push command does not update the working directory in the repository that it's pushing changes into. One has to use hg update to populate the changes in desired repo. ::
+
+ $ cd ../Fevicol
+ $ hg tip
+ changeset: 3:e1ab2aff4ddd
+ tag: tip
+ user: Shantanu Choudhary <shantanu@fossee.in>
+ date: Sun Aug 23 23:32:01 2009 +0530
+ summary: Changed tagline for feviStick.py.
+ $ cat feviStick.py
+ print 'Yeh Fevicol ka Majboot jod hai'
+
+changesets are imported, but update is yet to be done. ::
+
+ $ hg up tip
+ 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+ $ $ cat feviStick.py
+ print 'Ab no more Chip Chip'
+
+Dos and Don'ts with Mercurial:
+==============================
+
+
+
+Suggested Reading:
+==================
+
+ * http://karlagius.com/2009/01/09/version-control-for-the-masses/
+ * http://betterexplained.com/articles/a-visual-guide-to-version-control/
+ * http://en.wikipedia.org/wiki/Revision_control
+ * http://hgbook.red-bean.com/
+ * http://betterexplained.com/articles/intro-to-distributed-version-control-illustrated/
--- a/versionControl/versionControl.rst Sun Aug 23 02:01:53 2009 +0530
+++ b/versionControl/versionControl.rst Mon Aug 24 23:33:26 2009 +0530
@@ -22,37 +22,39 @@
+=========+=================================+=========+
| 1 | Introduction to Course | 5 mts |
+---------+---------------------------------+---------+
-| 2 | Why Revision Control? | 10 mts |
+| 2 | Why Revision Control? | 5 mts |
| | - Use case: for team | |
| | - Use case: for single dev | |
+---------+---------------------------------+---------+
-| 3 | Let there be Repository... | 15 mts |
+| 3 | Learning the Lingo | 5 mts |
++---------+---------------------------------+---------+
+| 4 | Let there be Repository... | 15 mts |
| | - Creating Repositpry. | |
| | - Cloning existing Repo. | |
| | - Branches concept | |
+---------+---------------------------------+---------+
-| 4 | Navigating through history logs | 5 mts |
+| 5 | Navigating through history logs | 5 mts |
+---------+---------------------------------+---------+
-| 5 | Making changes in local branch | 15 mts |
+| 6 | Making changes in local branch | 15 mts |
| | - add | |
| | - cp | |
| | - rename | |
| | - rm | |
+---------+---------------------------------+---------+
-| 6 | Sharing the changes | 10 mts |
+| 7 | Sharing the changes | 10 mts |
| | - status | |
| | - pull | |
| | - update | |
+---------+---------------------------------+---------+
-| 7 | Merging the changes | 20 mts |
+| 8 | Merging the changes | 20 mts |
| | - commit | |
| | - glog | |
| | - push | |
| | - merge | |
+---------+---------------------------------+---------+
-| 8 | Handling conflicts during merge | 20 mts |
+| 9 | Handling conflicts during merge | 20 mts |
+---------+---------------------------------+---------+
-| 9 | Exporting the changes: getting | |
+| 10 | Exporting the changes: getting | |
| | patch, diff | 10 mts |
+---------+---------------------------------+---------+
@@ -60,3 +62,4 @@
*buffer time = 10 mts*
+*For this course, working LAN is needed if Internet is not available.*