The RST-script for this Learning-path

The script below was used to generate the learning-path page above.

======================================
How to Write a Learning Path Script
======================================

All learning paths should start with a title like the one above. It's important to place it right at the top.

This is how to create it in reStructuredText:

::

  ======================================
  How to Write a Learning Path Script
  ======================================


You can then add a table of contents as easily as this

::

    .. contents::

cool huh? Here's what it looks like for this scipt

.. contents::


Note that the members of the list of contents are hyperlinked to their respective sections in the document. Likewise, clicking on a document section/heading will take you to the table-of-contents. 

.. smd-note:: Viewing learning-path scripts

    At the bottom of each learning-path you will find the script used to produce it. This is a good way to pick up some reST know-how.


A good starting point for using restructured text (reST) is Jeff Rush's rather excellent intro:

.. video:: 300

there is an accompanying page in the `Showmedo wiki <http://wiki.showmedo.com/index.php/JeffRush_ReStructuredTextDemo>`_

I created that last sentence using this markup - note the syntax for the hyperlink: 

::

    there is an accompanying page in the `Showmedo wiki <http://wiki.showmedo.com/index.php/JeffRush_ReStructuredTextDemo>`_

That box above is a literal-block. It preserves the text inside without interpreting it. Good for code-samples among other things. To create it I used a double semi-colon followed by indented text:

::

    ::

      there is an accompanying page in the `Showmedo wiki <http://wiki.showmedo.com/index.php/JeffRush_ReStructuredTextDemo>`_

following the title you should add a start and goal section to your learning-path. These should tell the users succinctly what they need to know before starting on the path and where the path is intended to take them: 

::

  start
  =====
  You don't know how to create a Showmedo Learning path.

  goals
  =====
  You should know enough restructured text (reST) to be able to write a learning-path script.

the above reST creates this:

start
=====
You don't know how to create a Showmedo Learning path.

goals
=====
You should know enough restructured text (reST) to be able to write a learning-path script.

Introduction
============

Now the preliminaries are over, you are free to structure the learning path as you like using sections

::

  First Steps
  ===========

First Steps
===========

and subsections to organize the learning-path.

::

  Smaller Steps
  -------------

Smaller Steps
-------------

We are in a subsection.

A Little Guide to Restructured Text (reST)
==========================================

reST allows you to use plain-text markup to create material in various formats, for example HTML, Latex, PDF etc.. The HTML you are looking at here was generated by running a plain-text script through an RST2HTML generator. You can use most of the HTML formatting expressions. For example to *emphasize* or **strongly emphasize** a word or phrase. 


::

  ... to *emphasize* or **strongly emphasize** to a word or phrase. 

let's add an familiar image, just to show you how:

.. figure:: http://www.showmedo.com/static/images/showmedoLogo.gif
    :figclass: float-center

::

  .. figure:: http://www.showmedo.com/static/images/showmedoLogo.gif
        :figclass: float-center

How about a bullet pointed list:

Some useful RST links
----------------------
.. _`rst resources`:

- The `reST home-page <http://docutils.sourceforge.net/rst.html>`_
- A `quickstart primer <http://docutils.sourceforge.net/docs/user/rst/quickstart.html>`_
- A `quick-reference guide <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_

::

  - The `reST home-page <http://docutils.sourceforge.net/rst.html>`_
  - A `quickstart primer <http://docutils.sourceforge.net/docs/user/rst/quickstart.html>`_
  - A `quick-reference guide <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_

We could have used '-', '+' or '*' markers to create the bullets. To create an enumerated list just use numbers '1.', '2.', ...  

You can even create tables, should the need arise:

======  =========  =======
Animal  Vegetable  Mineral
======  =========  =======
python  potato     ruby
rhino   carrot     diamond
camel   cucumber   garnet
lynx    leek       saphire
======  =========  =======

::

  ======  =========  =======
  Animal  Vegetable  Mineral
  ======  =========  =======
  python  potato     ruby
  rhino   carrot     diamond
  camel   cucumber   garnet
  lynx    leek       saphire
  ======  =========  =======

Just make sure the top and bottom borders are aligned - if they're not you should, as with most reST errors, receive a helpful error-message.


We've skimmed the surface of what reST can do. For greater depth, check out the list of `rst resources`_ above. 

To create that internal hyperlink I added a target just above the resource list:


::

  .. _`rst resources`:


and created a hyperlink to it like so


::

  For greater depth, check out the list of `rst resources`_ above. 
  

Special Showmedo Directives
===========================

Learning-paths use special directives to link to elements of Showmedo, for example video tutorials, tutorial series, authors etc.. To do this they use ID numbers, usually found in prepended square brackets. e.g. "[1209] Python 3.0 changes - Part I - (1/1)", where the ID of the video in question is 1209.    

One of the key aims of learning-paths is to enable richer, more seamless integration of video screencasts and supporting textual material. At the top of this path I referenced Jeff Rush's excellent screencast by using this directive:

::

  .. video:: 300


That creates a 'video-box' for the Showmedo video with ID 300. 

.. video:: 300

If you are referencing your own videos you will find all the IDs on your personal ('My') page. All videos have IDs (for video and containing series) on their respective pages, just beneath the descriptions. Using these IDs you can incorporate and reuse videos by yourself and others.  Notice the play button to the left of the video-title. Clicking this should bring up a video play-box. Give it a try.


.. _default-video-72:

Including Multiple Videos
-------------------------

You can include more than one video in the directive, using spaces or commas to separate them. Here's a couple of cool videos you might want to include at the beginning of a Python learning-path:


.. video:: 72 73

::

  .. video:: 72 73

Including Video-series
----------------------

Those last two videos are two halves of a series so we could have included that instead:

.. series:: 27

::
  
  .. series:: 27

Clicking from a series box will open a new tab with the series-page. 

By default the video and series boxes include the first 250 characters of their respective descriptions to give the user the gist of their content. You can add '-short' and '-long' postscripts to the video and series directives. '-short' suppresses the description entirely while '-long' prints the whole description. In this way you can incorporate the descriptions in your learning-path or remove redundant information.

As an example let's try both short and long versions of video 72. Compare with the  `default-video-72`_.

.. video-short:: 72

::
  
  .. video-short:: 72


.. video-long:: 72

::
  
  .. video-long:: 72

Connecting to Other Learning-paths
----------------------------------

Learning paths can of course connect to other learning-paths. In fact it is hoped this connectivity will realize their full potential and is strongly encouraged. In this way longer learning-paths can be constructed by incorporating shorter path-elements allowing authors to reuse their own and others paths, thus minimizing redundancy and increasing the richness of the learning experience.

Here's a recent path announcing the release of Showmedo's Learning-paths. It has a bit of detail I don't need to repeat here (now):

.. path:: 1

Referencing paths is as easy as this:

::

    .. path:: 1


where 48 is the ID of the path in question. You'll find these IDs at the front of the Learning-paths' titles.

As well as referring to whole paths one can reference one of a path's constituent steps:

.. step:: 2 special-showmedo-directives

::

    .. step:: 2 special-showmedo-directives

The number in the directive (2 in this case) refers to the ID of the path and the string afterwards ('special-showmedo-directives') to the step's title. Note the conversion to lower-case and the replacement of white-space with dashes '-'. 


Including User-uploaded images
------------------------------

Authors can upload their own images to Showmedo using the `upload form </creators/uploadImage>`_. Each image has an ID number which can be used with the smd-image directive to conveniently include it in a learning-path:

.. smd-image:: 21
    :imageclass: float-center

::

  .. smd-image:: 21
        :imageclass: float-center

The authors' 'My-Page' contains a tabbed list of uploaded images and their IDs.


Multiple Authors
----------------

It is easy for multiple authors to collaborate on a learning-path and this collaboration is very much encouraged. To allow co-authors, an author can use the authors' directive:

::

    ..authors:: [author ID 1] [author ID 2] [...]


The author ID numbers can be found next to the author's name in the identity-box at the top of their videos, video-series or learning-paths. 

Notes
-----

.. smd-note:: A Note About Collaboration!

    Although we keep a copy of learning-path scripts as they are edited, currently we do not have a source-control system in place or any means of *rolling back* through the editing history of the script, as most conventional wiki's allow. We are looking into this, but at the moment advise that you keep a copy of any script submitted when co-authoring a script. 

I just made use of the special note directive to create the note above:

::

    .. smd-note:: A Note About Collaboration!

        Although we keep a copy of learning-path scripts as they are edited, currently we do not have a source-control system in place or any means of *rolling back* through the editing history of the script, as most conventional wiki's allow. We are looking into this, but at the moment advise that you keep a copy of any script submitted when co-authoring a script. 
   
This note is publicly viewable, but you can make it private by including the ':class: private' qualifier under the note title:

::

    .. smd-note:: A Private Note
        :class: private

**Note** this is a weak privacy, using CSS to hide the note from non-authors; the text is still available in the source html. 

Authors can keep track of all public and private notes from their 'My Page'. In this way notes, particularly private ones, can be used as reminders in the editing process.


Requests and Responses
----------------------

Another way in which authors can collaborate and spur the production of new learning-paths is by using the new Request-Response system. If, for example, while writing a learning-path I would like to refer the user to another path, to clarify a point or fill in a gap in the presentation, but there is nothing suitable, I can make a request like the following: 
  
.. request:: I'd like to see a learning-path about responding to requests

    A little more detail on how requests and responses work please


::
    
    .. request:: I'd like to see a learning-path about responding to requests

        A little more detail on how requests and responses work please
    
    
The above request will find its way to the Showmedo `notice-board <http://www.showmedo.com/learningpaths/notices>`_ where hopefully someone will see it and, noting its ID, script a response:

.. response:: 1

    A little information about responding to a learning-path request.

::

    .. response:: 1
        
        A little information about responding to a learning-path request.

You can place the response directive anywhere in a learning-path script to indicate the relevant material. For example, if one were writing a whole path in response one would place the directive at the top of the script. 

If a request generates a satisfactory response, the author can remove it and replace it with a link to the responding path. This removes it from prominence on the notice-board. The system will doubtless be refined over time but should allow proper communication between authors. 


Code Blocks
-----------

Learning-paths make it much easier to integrate your videos' code-samples and reST has a special directive to allow attractive syntax highlighting. Here's a little python code to demonstrate:

.. code-block:: python

  #  
  # 910100_csvReader.py  
  #  
  import csv  
  import easygui  
   
  def getFileAndPath():  
     "Get fully-qualified path to the csv file"  
     fileAndPath = easygui.fileopenbox(title="Select .CSV file")  
     print "Using:",fileAndPath   
     return fileAndPath  
   
  def getLinesInCSVFile(fileAndPath):  
     "read lines in CSV file, return a list of these lines"  
     linesInCSV = []  
     reader = csv.reader(open(fileAndPath, "rb"))  
     for row in reader:  
         linesInCSV.append(row)  
     return linesInCSV  


To produce a syntax-highlighted code-block we use the code-block directive with the required language as an argument:

::

  code-block:: python

    # and the code start...
    import a_required_module

    print 'hello world'

To produce the highlighting we use the excellent Python `Pygments <http://pygments.org>`_ module. This can highlight a large range of languages. You will find a list `here <http://pygments.org/languages/>`_.

Here's a bit of java code as a final example:


.. code-block:: java

  /** 
 * The HelloWorldApp class implements an application that
 * simply prints "Hello World!" to standard output.
   \*/
  class HelloWorldApp {
      public static void main(String[] args) {
          System.out.println("Hello World!"); // Display the string.
      }
  }

::

  .. code-block:: java

    /** 
   * The HelloWorldApp class implements an application that
   * simply prints "Hello World!" to standard output.
     */
    class HelloWorldApp {
        public static void main(String[] args) {
            System.out.println("Hello World!"); // Display the string.
        }
    }

Troubleshooting
---------------

If you use a non-existent series or video Id, you should get a fairly helpful error-message:

.. series:: 9999

Note: the yellow message-bar at the top of the page indicates any errors in your script.

Tagging
-------

Your learning-path will inherit tags from all videos and series referenced but it's a good idea to include a few key ones anyway, just to be on the safe side. This will help other users find their way here. The tag directive allows you to add tags to the learning path:

::

  .. tags:: introduction, learning-path, beginners, rst

You can place a single tag-directive at the start or end of your learning path. This will create the following tag-cloud subsection: 

.. tags:: introduction, learning-path, beginners, rst

These tags give users access to relevant Showmedo collections.