Creating a lesson on syndicating web data

CONTRIBUTING.md

@@ -22,8 +22,9 @@ and then open an issue of your own to get feedback on your ideas and coordinate
 
 *   [Topic Maintainers](#topic-maintainers)
 *   [Working With GitHub](#working-with-github)  
+*   [Locations](#locations)
+*   [Formats](#formats)
 *   [Previewing](#previewing)
-*   [Locations and Formats](#locations-and-formats)
 *   [Sample Files](#sample-files)
 *   [Labels](#labels)
 *   [FAQ](#faq)
@@ -55,6 +56,15 @@ the topic name links to that repository.
 Working With GitHub
 -------------------
 
+In general, we are using Git and GitHub for almost everything.
+But if it is easier for you to send your contributions to us some other way,
+please mail us at
+[admin@software-carpentry.org](mailto:admin@software-carpentry.org).
+Given a choice between you creating content or wrestling with Git,
+we'd rather have you doing the former.
+
+The GitHub workflow looks like this:
+
 1.  Fork the `swcarpentry/bc` repository on GitHub.
 
 2.  Clone that repository to your own machine.
@@ -74,6 +84,45 @@ please mail us at
 Given a choice between you creating content or wrestling with Git,
 we'd rather have you doing the former.
 
+Locations
+---------
+
+Every subject has a sub-directory of its own,
+while individual topics are files in that directory.
+For example,
+the `novice/git` directory holding our introduction to Git for newcomers
+contains the files
+`00-intro.md`,
+`01-backup.md`,
+and so on.
+(We use two digits followed by a one-word topic key
+to ensure files appear in the right order when listed.)
+
+Formats
+-------
+
+We are using [Jekyll](https://en.wikipedia.org/wiki/Jekyll_%28software%29)
+to convert lessons in [Markdown](https://en.wikipedia.org/wiki/Markdown)
+to [HTML](https://en.wikipedia.org/wiki/HTML).
+Therefore, we require every lesson to be available in Markdown.
+But this does not mean that you have to write it in Markdown as well.
+
+The following list contains more detailed instructions for different formats:
+
+*   Markdown: Nothing to do.
+*   IPython Notebook: Generate and provide a Markdown version in addition
+    to the IPython Notebook.
+    Look at our existing files to get an idea how the IPython Notebook
+    should look like.
+*   Other formats: Generate and provide a Markdown version in addition
+    to the file in the original format.
+    In order to be able to recreate the Markdown from source,
+    include the conversion from this other format to Markdown
+    in the `Makefile` as well. This ensures that people who *aren't* familiar
+    with some format don't have to install the tools needed to work with it
+    (e.g., R programmers don't have to install the IPython Notebook).
+    **Please check with us if you plan to do this.**
+
 Previewing
 ----------
 
@@ -82,7 +131,6 @@ run the command `make site`.
 This runs Jekyll with the same flags that GitHub uses when things are committed to the `gh-pages` branch
 and puts the results in a directory called `_site`.
 
-
 You should also run `make check` before pushing changes to your `index.html` home page
 to your repository.
 If you don't have Make installed,
@@ -109,40 +157,6 @@ and ensure that the main Makefile only does what Jekyll on GitHub will do.
 To re-do conversion of notebooks to Markdown files,
 use `make ipynb`.
 
-Locations and Formats
----------------------
-
-Every subject has a sub-directory of its own,
-while individual topics are files in that directory.
-For example,
-the `novice/git` directory holding our introduction to Git for newcomers
-contains the files
-`00-intro.md`,
-`01-backup.md`,
-and so on.
-(We use two digits followed by a one-word topic key
-to ensure files appear in the right order when listed.)
-
-Lessons may be written in Markdown,
-as IPython Notebooks,
-or in other formats.
-However,
-as explained in [the README file](README.md),
-Jekyll (the tool GitHub uses to create websites)
-only knows how to handle Markdown and HTML.
-if some other format is used,
-the author of the lesson must
-add the generated Markdown to the repository.
-This ensures that people who *aren't* familiar with some format
-don't have to install the tools needed to work with it
-(e.g.,
-R programmers don't have to install the IPython Notebook).
-
-> If a lesson is in a format we don't already handle,
-> the author must also add something to the Makefile
-> to re-create the Markdown from the source.
-> Please check with us if you plan to do this.
-
 Sample Files
 ------------
 
@@ -188,11 +202,15 @@ FAQ
 ---
 
 *   *Where can I get help?*
-    <br/>
     Mail us at [admin@software-carpentry.org](mailto:admin@software-carpentry.org),
     come chat with us on [our IRC channel](irc://moznet/sciencelab),
     or join our [discussion list](http://software-carpentry.org/pages/discuss.html)
     and ask for help there.
 
+*   *Is there a list of open issues to tackle?*
+    The [open issues for the bc repository](https://github.com/swcarpentry/bc/issues)
+    and also the [related projects](http://www.software-carpentry.org/pages/create.html#related)
+    listed on the create page are a good starting point.
+
 [windows-installer]: https://github.com/swcarpentry/windows-installer
 [installation-test]: http://git.tremily.us/?p=swc-setup-installation-test.git

Makefile

@@ -72,6 +72,7 @@ ALL_SRC = \
         $(wildcard intermediate/regex/*.md) \
 	$(wildcard intermediate/python/*.md) \
 	$(wildcard intermediate/doit/*.md) \
+	$(wildcard intermediate/webdata/*.md) \
 	$(wildcard slides/*.html) \
 	$(MOST_SRC)
 

README.md

@@ -47,14 +47,14 @@ and so on.
 
 **Table of Contents**
 
-*   [Background](#background)  
-*   [Getting Started](#getting-started)  
-*   [Previewing the Site](#previewing-the-site)  
-*   [Variables](#variables)  
-*   [Website Content](#website-content)  
-*   [Lesson Material](#lesson-material)  
-*   [Building Things](#building-things)  
-*   [Site Map](#site-map)  
+*   [Background](#background)
+*   [Getting Started](#getting-started)
+*   [Previewing the Site](#previewing-the-site)
+*   [Variables](#variables)
+*   [Website Content](#website-content)
+*   [Lesson Material](#lesson-material)
+*   [Building Things](#building-things)
+*   [Site Map](#site-map)
 *   [FAQ](#faq)
 
 Background
@@ -108,15 +108,15 @@ rather than Git itself.
 
     then GitHub doesn't just copy the file over verbatim.
     Instead,
-    it runs the file through a translator called Jekyll
+    it runs the file through a translator called [Jekyll](https://en.wikipedia.org/wiki/Jekyll_%28software%29)
     that looks for specially-formatted commands embedded in the file.
 
 6.  Commands can be embedded in the body of a page.
     One is {% raw %}{% include something.html %}{% endraw %},
     which tells Jekyll to copy the contents of `something.html` into the file being translated;
     this is used to create standard headers and footers for pages.
     Another is `{{variable}}`:
-    when Jekyll see this,
+    when Jekyll sees this,
     it replaces it with the value of `variable`.
     This is used to insert things like a contact email address and the URL for our Twitter account.
 
@@ -403,7 +403,7 @@ Lesson Material
     in directories under `intermediate`.
 3.  Our old lesson material
     is in the `lessons` directory.
-    We plan to retire it in Spring 2014,
+    We plan to retire it in Spring 2014.
 
 As explained [below](#building-things),
 you can use `make` to compile this material in the way that GitHub does
@@ -455,7 +455,7 @@ The most important files and directories are **highlighted**.
 *   _layouts/ - Jekyll page layouts.
 *   **_site/** - output directory (created when building the site locally).
 *   _templates/ - template files for conversion of IPython Notebooks to Markdown.
-    Templates for other conversion systems (e.g., Pandoc) should go here too.
+    Templates for other conversion systems (e.g., Pandoc) should go here, too.
 *   bib.md - bibliography.
 *   bin/ - miscellaneous tools used in building the site.
 *   book.md - generated when compiling the website locally.
@@ -535,7 +535,7 @@ FAQ
     Uninstall pygments.rb 0.5.1 or 0.5.2, install 0.5.0.  For example, here's how you would
     uninstall pygments 0.5.2 and restore version 0.5.0:
 
-    ~~~    
+    ~~~
     $ gem uninstall pygments.rb --version "=0.5.2"
     $ gem install pygments.rb --version "=0.5.0"
     ~~~
@@ -544,7 +544,7 @@ FAQ
     <br/>
     The output of `make check` looks like this:
 
-    ~~~    
+    ~~~
     WARNING: Unrecognized alias: 'output', it will probably have no effect.[TerminalIPythonApp] File not found: u'nbconvert'
     cp tmp/python/novice/01-numpy.html _site/python/novice/01-numpy.html
     cp: cannot stat ‘tmp/python/novice/01-numpy.html’: No such file or directory