Check individual Markdown lessons for errors

[wcaleb]

In the wake of our bulk conversion to Jekyll, we need to do a close editorial check of each of the Markdown lessons listed below, which are kept in the lessons directory and can be seen live at http://programminghistorian.github.io/jekyll/lessons.

The best way to spot check is probably to look at the live GitHub Pages version of a page alongside its older, ProgrammingHistorian.org version. Be aware that you may see some differences in spacing and color (for example, in the code blocks, which also lack line numbers in the new site); these can be adjusted later with CSS, so they don't require changes to the Markdown files at this stage.

Each lesson check needs to include, at a minimum:

• Clicking on every link to make sure it works
• Fixing any incorrect Markdown syntax, using Markdown Style Guide as a reference
• Identifying any broken images and finding copies of the original images (please add a comment here listing the urls of the images that need to be added, unless you already know how to "push" the images directly to the images folder)
• Turning any images that were clickable and had captions on the old site into "figures," using the instructions on the Markdown Style Guide
• General proofreading of any typos
• If there is nothing showing up in the "About the authors" box at the bottom of your lesson, then you need to add a bio for each author in the _config.yml file, as explained in Adding New Lessons.
• Restore any missing italics (using the *emphasis* Markdown syntax) or missing monospace font changes (using the "back ticks" inline code Markdown syntax); particularly in some of the early lessons, there were "span" tags for these things that were lost in the conversion. If you notice lots of missing italics / code styling in your lesson, you can also look on the spans branch for deprecated versions of the lessons that do have most of this inline span styling preserved.

Our wiki has instructions on Editing Lessons on GitHub.

If you see a systemic problem, or an issue in a lesson that you're not sure how to fix, see the instructions on Reporting Issues so that others can help out.

To "claim" a lesson for proofreading, please leave a comment on this issue listing the ones that you will look at, so we don't duplicate efforts. I'll try to update this list to reflect the lessons claimed in the comments.

Lesson List

When you've finished checking a lesson, the only thing left to "check" is the box!

• [x] applied-archival-downloading-with-wget.md (Caleb)
• [x] automated-downloading-with-wget.md (Caleb)
• [x] cleaning-data-with-openrefine.md (Adam) - missing datafile phm-collection.tsv
• [x] cleaning-ocrd-text-with-regular-expressions.md (Caleb)
• [x] code-reuse-and-modularity.md (Bill)
• [x] counting-frequencies-from-zotero-items.md (Bill; zip file fixed)
• [x] counting-frequencies.md (Bill; zip file fixed)
• [x] creating-an-omeka-exhibit.md
• [x] creating-and-viewing-html-files-with-python.md (Bill)
• [x] creating-new-items-in-zotero.md
• [x] data-mining-the-internet-archive.md (Caleb)
• [x] downloading-multiple-records-using-query-strings.md (Adam)
• [x] from-html-to-list-of-words-1.md (Allison; zip file fixed)
• [x] from-html-to-list-of-words-2.md (Allison; zip file fixed)
• [x] georeferencing-qgis.md (Caleb)
• [x] googlemaps-googleearth.md (Caleb)
• [ ] lessons/index.md (fred)
• [x] installing-python-modules-pip.md (fred)
• [ ] intro-to-beautiful-soup.md (fred)
• [x] intro-to-the-zotero-api.md (Bill)
• [x] introduction-and-installation.md (Adam; now in table of contents)
• [x] keywords-in-context-using-n-grams.md (Bill)
• [x] linux-installation.md (fred)
• [x] mac-installation.md (fred)
• [x] manipulating-strings-in-python.md (Bill; zip file fixed)
• [x] normalizing-data.md
• [x] output-data-as-html-file.md (Bill)
• [x] output-keywords-in-context-in-html-file.md (Bill)
• [x] preserving-your-research-data.md
• [x] qgis-layers.md (Caleb)
• [x] sustainable-authorship-in-plain-text-using-pandoc-and-markdown.md (Caleb)
• [x] topic-modeling-and-mallet.md (Caleb)
• [x] transliterating.md (Allison)
• [x] understanding-regular-expressions.md (Miriam)
• [x] up-and-running-with-omeka.md (Miriam)
• [x] vector-layers-qgis.md (Caleb)
• [x] viewing-html-files.md (Bill)
• [x] windows-installation.md (fred)
• [x] working-with-text-files.md (Bill)
• [x] working-with-web-pages.md (Bill)

[acrymble]

Some of those look like deprecated lessons. I think Fred was going to weed those out?

[wcaleb]

Probably are some deprecated lessons or dummy pages. For the time being, we could take care of keeping those of the site by adding this line to the metadata:

published: false

And then check the box above to indicate it's taken care of.

[fredgibbs]

indeed. i'm in the process of doing that now. i'm moving unneeded files to a depricated directory that i've created in the lessons folder so that they are less distracting and confusing--since they have names very similar to existing lessons we want to keep.

[wcaleb]

Thanks, @fredgibbs. We may want to add published: false to those files anyway, because even in their own subdirectory, Jekyll will compile and publish them on the site. (Though obviously they'll be hard to find since nothing links to them.)

[fredgibbs]

i've moved all the non-lessons into the site root directory (should be commit 1d0e88e), and removed them from this list; i will change their templates and check the markdown for these pages.

[wcaleb]

Great! It turns out that we can exclude the deprecated lessons just by putting an exclude statement for that directory in the config file. See 7103c9ea9f5af1d0c02fad1891b8caea0a038ccf.

[williamjturkel]

I already edited a few of the lessons and changed your list above to reflect. This post doesn't match the one that was circulated by email, so I am just using this one since it is more recent.

[acrymble]

target="_blank" on the external links doesn't seem to be possible with markdown.

[wcaleb]

@acrymble That's correct, but if we wanted to have external links open in new windows, we could probably achieve this with javascript. But I have a vague, unprofessional sense that opinion is mixed about whether to force links to open in new windows, since many browsers have this functionality for users who want it.

[acrymble]

We had put that in for all external links, since presumably someone working on a tutorial wouldn't want to lose the page when they clicked on a link of a technical term for a definition.

[acrymble]

What is the plan for marking up figure captions? Right now mine look like part of the text.

[wcaleb]

Re: figures, see Markdown Style Guide.

[miriamposner]

Hey, when we have a link to another PH lesson, what should we be linking to? Currently the link is broken.

[wcaleb]

@miriamposner Use a relative URL: ../lessons/name-of-file-without-extension

[wcaleb]

@acrymble I added some javascript in 6f7eef6971f212aa3f42d9f6b5530a207b898869 that will open external links in new windows. (You won't see the "target=_blank" in the actual HTML, and you don't need to do anything in the Markdown; the javascript will essentially add that attribute on the fly.)

[acrymble]

cool

[acrymble]

The Figure tag (and your example of it working) don't see to be working.

Instead, I see the tag itself in the text:

https://github.com/programminghistorian/jekyll/blob/3c3f97d3f05dd26149a398b9daa19793fe9f7820/lessons/working-with-web-pages.md

[acrymble]

Can we also make sure the Google Analytics code gets put in before we go live? I don't want to have a gap in our stats if we can avoid it.

[wcaleb]

Figure won't show up in the Github markdown previewer, but you should see it when you look at the live page.

Sent from my iPhone

On Aug 7, 2014, at 6:21 AM, Adam Crymble notifications@github.com wrote:

The Figure tag (and your example of it working) don't see to be working.

Instead, I see the tag itself in the text:

https://github.com/programminghistorian/jekyll/blob/3c3f97d3f05dd26149a398b9daa19793fe9f7820/lessons/working-with-web-pages.md

— Reply to this email directly or view it on GitHub.

[acrymble]

Gotcha. Bit of a learning curve.

[ahegel]

Some questions I had after going through the "Transliterating non-ASCII characters with Python" lesson:

There was a non-functioning link to a PH lesson called "Installing Pip and Beautiful Soup" that I wasn't able to find anywhere - does this lesson still exist?

Is it ok if the new markdown lesson removed the distinction between "Technical Reviewers" and "Literary Reviewers" and instead grouped them together as "Reviewer(s)", or should we be preserving that distinction somehow?

I added the author, Seth Bernstein, to the config file with just the first sentence of his bio to match the other authors' one-sentence bios, but there was an extra sentence on the old site version. Should I have included the full bio? When I tried to, it had trouble dealing with the colon in his dissertation title (I tried adding a backslash which still didn't work).

[wcaleb]

@ahegel

The distinction between types of reviewers was one of the things lost in the bulk conversion process (see #5), and I think the consensus in our last Skype was that it was okay to leave a single "reviewer(s)" line.

I'm interested in the problem you had with the colon when adding Bernstein's full bio. The pipe character in the config file immediately after "bio" signals that what follows is a "literal block" and should allow you to use characters like that without escaping, so long as you preserve the indenting for the literal block. Could you "commit" what you tried so I can have a look at what's going on?

[ahegel]

Sure, I just committed it. While I was typing the second line of the bio, the line turned from red text to black text, which made me think it wouldn't recognize it as part of the previous bio line, but it seems to work fine now that I've committed it.

[ahegel]

How do you get a targeted link to work on the new site? I want to link to the last section (Code Syncing) in this lesson (http://programminghistorian.github.io/jekyll/lessons/from-html-to-list-of-words-2) but adding #codesync to the end of the link like we did on the old site doesn't work in the new version.

Sorry for all the questions!

[wcaleb]

Hmmm. This identifies something that I should have captured in the bulk conversion, but I think I can fix it. Go ahead and create your link, but use #code-syncing (the text of the header you want to link to). I'll try to use a Pandoc filter to give ID names to all the headers in our lessons.

[wcaleb]

@ahegel Actually, I remember now why I didn't include the HTML anchors in bulk conversion, because it would seriously clutter the Markdown. Fortunately, there's an extension to Redcarpet (the Markdown renderer we're using) called with_toc_data that automatically generates semantic ids for every header. I've implemented this with c42bd6c9a426612a5dc91a8d9708111b8359374c. So you should now be able to create links to particular headers, using the syntax in my last comment.

[ahegel]

It works! Thank you.

The only left-over question I have is whether the "Installing Pip and Beautiful Soup" lesson still exists? There's a non-functioning link to it in "Transliterating non-ASCII characters with Python".

[fredgibbs]

@ahegel the title/link for that lesson/page, which is errantly not on the lessons index page is installing-python-modules-pip.

beyond that one, i think we should ass a section on the lessons page for getting started or setting up your environment, etc, that has this page listed as well as a few of the other set up lessons that don't seem to appear there now.

[ahegel]

The lessons "From HTML to List of Words" (parts 1 and 2) are finished EXCEPT FOR a link to a zip file in the last section of each that is supposed to be in the images directory (http://programminghistorian.github.io/jekyll/images/programming-historian2.zip). I'm not sure how to find the file or "push" it into the correct folder.

[williamjturkel]

@ahegel I added links to the zip files for the two lessons you did