Language mechanics (#29)

* julia -> Julia, where appropriate * Lesson grammar check; remove HTML tags from MD * wrap markdown at 79 lines; fix VSCode template Very long lines render poorly on GitHub and in editors, and (perhaps more significantly) require larger blobs for git to track changes. This commit wraps lines at 79 chars, for the most part, to improve rendering, readability, and repository size. `.editorconfig` has been updated to reflect the change. In addition, the VSCode template for Challenge-and-Solution blocks was modified to insert blank lines after each title. * tidy up the README
carpentries-incubator · Dec 3, 2021 · 15bce55 · 15bce55
1 parent 4b45f12
commit 15bce55
Show file tree

Hide file tree

Showing 14 changed files with 556 additions and 292 deletions.
diff --git a/.editorconfig b/.editorconfig
@@ -8,10 +8,10 @@ trim_trailing_whitespace = true
 [*.md]
 indent_size = 2
 indent_style = space
-max_line_length = 100  # Please keep this in sync with bin/lesson_check.py!
+max_line_length = 79  # Please keep this in sync with bin/lesson_check.py!
 
 [*.r]
-max_line_length = 80
+max_line_length = 79
 
 [*.py]
 indent_size = 4

diff --git a/.vscode/carpentries.snippet.code-snippets b/.vscode/carpentries.snippet.code-snippets
@@ -1,11 +1,17 @@
 {
-	// Place your julia-novice workspace snippets here. Each snippet is defined under a snippet name and has a scope, prefix, body and
-	// description. Add comma separated ids of the languages where the snippet is applicable in the scope field. If scope
-	// is left empty or omitted, the snippet gets applied to all languages. The prefix is what is
-	// used to trigger the snippet and the body will be expanded and inserted. Possible variables are:
-	// $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders.
-	// Placeholders with the same ids are connected.
-	// Example:
+	// Place your julia-novice workspace snippets here. Each snippet is defined
+	// under a snippet name and has a scope, prefix, body and description. Add
+	// comma-separated ids of the languages where the snippet is applicable in
+	// the scope field. If scope is left empty or omitted, the snippet gets
+	// applied to all languages. The prefix is what is used to trigger the
+	// snippet and the body will be expanded and inserted.
+	//
+	// Possible variables are:
+	// $1, $2 for tab stops, $0 for the final cursor position, and ${1:label},
+	// ${2:another} for placeholders.
+	//
+	// Placeholders with the same ids are connected. Example:
+	//
 	// "Print to console": {
 	// 	"scope": "javascript,typescript",
 	// 	"prefix": "log",
@@ -15,6 +21,7 @@
 	// 	],
 	// 	"description": "Log output to console"
 	// }
+
 	"julia-codefence": {
 		"prefix": "~~~jl",
 		"body": ["~~~",
@@ -31,16 +38,16 @@
 			"{: .output}"
 		]
 	},
-	"challange and solution": {
+	"challenge and solution": {
 		"prefix": "challS",
 		"body": [
 			"> ## $1",
+			">",
 			"> > ## ${2:Solution}",
-			">{: .solution}",
+			"> >",
+			"> {: .solution}",
 			"{: .challenge}",
 			"$0"
 		]
 	}
-
-
 }
diff --git a/README.md b/README.md
@@ -1,53 +1,49 @@
-# julia-novice-trebuchet
+# Programming with Julia
 
-[![Create a Slack Account with us](https://img.shields.io/badge/Create_Slack_Account-The_Carpentries-071159.svg)](https://swc-slack-invite.herokuapp.com/)
+[![Create a Slack Account with us][slack]](https://swc-slack-invite.herokuapp.com/)
 
-[![Our channel](https://img.shields.io/badge/juliaswc-slack_channel-orange)](https://swcarpentry.slack.com/archives/CBJ8C7NE6)
+[![Our channel][channel](https://swcarpentry.slack.com/archives/CBJ8C7NE6)
 
-This lesson targets people who already have some experience with (scientific) programming, but are new to julia.
-
-
-**Thanks for contributing to The Carpentries Incubator!**
-This repository provides a blank starting point for lessons to be developed here.
-
-A member of the [Carpentries Curriculum Team](https://carpentries.org/team/)
-will work with you to get your lesson listed on the
-[Community Developed Lessons page][community-lessons]
-and make sure you have everything you need to begin developing your new lesson.
-
-##
+This lesson targets people who already have some experience with (scientific)
+programming, but are new to Julia.
 
 ## Contributing
 
-We welcome all contributions to improve the lesson! Maintainers will do their best to help you if you have any
-questions, concerns, or experience any difficulties along the way.
-
-We'd like to ask you to familiarize yourself with our [Contribution Guide](CONTRIBUTING.md) and have a look at
-the [more detailed guidelines][lesson-example] on proper formatting, ways to render the lesson locally, and even
-how to write new episodes.
+We welcome all contributions to improve the lesson! Maintainers will do their
+best to help you if you have any questions, concerns, or experience any
+difficulties along the way.
 
-Please see the current list of [issues](https://github.com/carpentries-incubator/julia-novice/issues) for ideas for contributing to this
-repository. For making your contribution, we use the GitHub flow, which is
-nicely explained in the chapter [Contributing to a Project](http://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project) in Pro Git
-by Scott Chacon.
-Look for the tag ![good_first_issue](https://img.shields.io/badge/-good%20first%20issue-gold.svg). This indicates that the maintainers will welcome a pull request fixing this issue.
+We'd like to ask you to familiarize yourself with our [Contribution
+Guide](CONTRIBUTING.md) and have a look at the [more detailed
+guidelines][lesson-example] on proper formatting, ways to render the lesson
+locally, and even how to write new episodes.
 
+Please see the current list of [issues][issues] for ideas for contributing to
+this repository. For making your contribution, we use the GitHub flow, which is
+nicely explained in the chapter [Contributing to a Project][start] in *Pro Git*
+by Scott Chacon. Look for the tag ![good_first_issue][first]. This indicates
+that the maintainers will welcome a pull request fixing this issue.
 
 ## Maintainer(s)
 
 Current maintainers of this lesson are
 
-* [Simon](https://carpentries.org/instructors/#beastyblacksmith): [@BeastyBlacksmith](https://github.com/BeastyBlacksmith)
-
+* [Simon](https://carpentries.org/instructors/#beastyblacksmith):
+  [@BeastyBlacksmith](https://github.com/BeastyBlacksmith)
 
 ## Authors
 
 A list of contributors to the lesson can be found in [AUTHORS](AUTHORS)
 
 ## Citation
 
-To cite this lesson, please consult with [CITATION](CITATION)
+To cite this lesson, please consult [CITATION](CITATION)
 
 [cdh]: https://cdh.carpentries.org
 [community-lessons]: https://carpentries.org/community-lessons
 [lesson-example]: https://carpentries.github.io/lesson-example
+[slack]: https://img.shields.io/badge/Create_Slack_Account-The_Carpentries-071159.svg
+[channel]: https://img.shields.io/badge/juliaswc-slack_channel-orange
+[issues]: https://github.com/carpentries-incubator/julia-novice/issues
+[start]: http://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project
+[first]: https://img.shields.io/badge/-good%20first%20issue-gold.svg
diff --git a/_episodes/01-introduction.md b/_episodes/01-introduction.md
@@ -3,55 +3,90 @@ title: "Introduction"
 teaching: 5
 exercises: 0
 questions:
-- "Who is teaching?"
-- "What is the schedule?"
+- "What is Julia?"
+- "Why use Julia?"
 objectives:
-- "Explain the overall content and in more detail the content of todays lesson."
+- "Explain the difference between interpreted and compiled programming languages"
+- "Compare how composing works in Julia and some common programming languages"
 keypoints:
-- "Julia is a just in time compiled language"
-- "Julia code composes well"
+- "Julia is a just-in-time compiled language"
+- "Julia packages compose well"
 ---
 
 ## What is a programming language?
 
-A programming language mediates between the natural language of humans and the machine instructions of a computer.
-The human specifies what the computer should compute on a high level using the programming language.
-This specification will be translated to machine instructions, the so called assembly code, which will be executed by the processor (CPU, GPU, ...).
+A programming language mediates between the natural language of humans and the
+machine instructions of a computer.
+The human specifies what the computer should compute on a high level using the
+programming language.
+This specification will be translated to machine instructions, the so called
+assembly code, which will be executed by the processor (CPU, GPU, ...).
 
 ## Interpreting and compiling
 
-This translation happens differently depending of the programming language you use.
+This translation happens differently depending on the programming language you
+use.
 There are mainly two different techniques: _compiling_ and _interpreting_.
-Interpreted languages such as python and R translate instructions one at a time, while compiled languages like C and Fortran take whole documents analyze the structure of the code and perform optimizations before translating it to machine code.
+Interpreted languages such as Python and R translate instructions one at a
+time, while compiled languages like C and Fortran take whole documents, analyze
+the structure of the code, and perform optimizations before translating it to
+machine code.
 
-This leads to more efficient machine instructions of the compiled code at the cost of less flexibility and more verbose code.
-Most prominently the need for type declarations in compiled languages.
+This leads to more efficient machine instructions of the compiled code at the
+cost of less flexibility and more verbose code.
+Most prominently, compiled languages need an explicit type declaration for each
+variable.
 
-## Why julia?
+## Why Julia?
 
-Julia is a programming language that superficially looks like an interpreted language and mostly behaves like one.
-But before each function is executed it will compile it _just in time_.
+Julia is a programming language that superficially looks like an interpreted
+language and mostly behaves like one.
+But before each function is executed it will be compiled _just in time_.
 
-Thus you get the flexibility of an interpreted language and the execution speed of the compiled language at the cost of waiting a bit longer for the first execution of any function.
+Thus you get the flexibility of an interpreted language and the execution speed
+of a compiled language at the cost of waiting a bit longer for the first
+execution of any function.
 
-There is another aspect of julia that makes it interesting and that is the way packages compose.
-This is captured the best by an analogy from [Sam Urmy](https://github.com/ElOceanografo):
+There is another aspect of Julia that makes it interesting and that is the way
+packages compose.
+This is captured the best by an analogy from [Sam Urmy](
+https://github.com/ElOceanografo):
 
 > Say you want a toy truck.
 >
-> The Python/R solution is to look for the appropriate package–like buying a Playmobil truck. It comes pre-manufactured, well-engineered and tested, and does 95% of what you would ever want a toy truck to do.
+> The Python/R solution is to look for the appropriate package–like buying a
+> Playmobil truck. It comes pre-manufactured, well-engineered and tested, and
+> does 95% of what you would ever want a toy truck to do.
 >
-> The Fortran/C solution is to build the truck from scratch. This allows total customization and you can optimize the features and performance however you want. The downside is that it takes more time, you need woodworking skills, and might hurt yourself with the power tools.
+> The Fortran/C solution is to build the truck from scratch. This allows total
+> customization and you can optimize the features and performance however you
+> want. The downside is that it takes more time, you need woodworking skills,
+> and might hurt yourself with the power tools.
 >
-> The Julia solution is like Legos. You can get the truck kit if you want–which will require a bit more assembly than the Playmobil, but way less than building it from scratch. Or, you can get the component pieces and assemble the truck to your own specs. There’s no limit to what you can put together, and because the pieces all have the same system of bumps, everything snaps together quickly and easily.
+> The Julia solution is like Legos. You can get the truck kit if you want–which
+> will require a bit more assembly than the Playmobil, but way less than
+> building it from scratch. Or, you can get the component pieces and assemble
+> the truck to your own specs. There’s no limit to what you can put together,
+> and because the pieces all have the same system of bumps, everything snaps
+> together quickly and easily.
 >
-> ![Trucks](https://aws1.discourse-cdn.com/business5/uploads/julialang/original/3X/5/2/52e63856ad9e23876cda4297a04171879fa625b4.jpeg){: height="400px"}
-> Ok, sure. Toy trucks are like linear algebra, though, a common request, and every “toy system” will have an implementation that works basically fine. But what if you want a time-traveling sailing/space ship with lasers AND dragon wings? And it should be as easy to build and use as a basic dump truck?
+> ![Trucks][vessel]{: height="400px"}
 >
-> ![Vessel](https://aws1.discourse-cdn.com/business5/uploads/julialang/original/3X/2/8/2865d34fb35c181dc3c5c0f0b71915f31310269c.jpeg){: height="400px"}
-> There’s a reason that only Lego ever made anything like Dr Cyber’s Flying Time Vessel
+> OK, sure. Toy trucks are like linear algebra, though, a common request, and
+> every “toy system” will have an implementation that works basically fine. But
+> what if you want a time-traveling sailing/space ship with lasers AND dragon
+> wings? And it should be as easy to build and use as a basic dump truck?
+>
+> ![Vessel][vessel]{: height="400px"}
+>
+> There’s a reason that only Lego ever made anything like Dr. Cyber’s Flying
+> Time Vessel!
 {: .quotation}
 
-Originally posted on [Discourse](https://discourse.julialang.org/t/what-is-the-advantage-of-julia-over-fortran/65964/101).
+Originally posted on [Discourse][discourse].
+
+[discourse]: https://discourse.julialang.org/t/what-is-the-advantage-of-julia-over-fortran/65964/101
+[truck]: https://aws1.discourse-cdn.com/business5/uploads/julialang/original/3X/5/2/52e63856ad9e23876cda4297a04171879fa625b4.jpeg
+[vessel]: https://aws1.discourse-cdn.com/business5/uploads/julialang/original/3X/2/8/2865d34fb35c181dc3c5c0f0b71915f31310269c.jpeg
 
 {% include links.md %}
diff --git a/_episodes/02-REPL.md b/_episodes/02-REPL.md
@@ -10,19 +10,23 @@ objectives:
 - "Learn about REPL modes."
 keypoints:
 - "The REPL reads the given input, evaluates the given expression and prints the resulting output to the user."
-- "Pressing <kbd>?</kbd> enters help mode."
-- "Pressing <kbd>;</kbd> enters shell mode."
-- "Pressing <kbd>]</kbd> enters pkg mode."
+- "Pressing `?` enters help mode."
+- "Pressing `;` enters shell mode."
+- "Pressing `]` enters pkg mode."
 
 ---
 
 # Entering the REPL
 
 ## Variables
 
+After downloading and executing a Julia binary from
+[julialang.org](https://julialang.org), Melissa and her classmates face the so
+called REPL, which stands for **r**ead-**e**valuate-**p**rint-**l**oop. The
+interactive command-line REPL allows quick and easy execution of Julia
+statements.
+The first thing they try is to perform basic arithmetic operations:
 
-After downloading and executing a julia binary from https://julialang.org Melissa and her classmates face the so called REPL, which stands for <u>r</u>ead-<u>e</u>valuate-<u>p</u>rint-<u>l</u>oop. The interactive command-line REPL allows quick and easy execution of Julia statements.
-The first thing they try is to perform basic arithmetic operations
 ~~~
 1 + 4 * 7.3
 ~~~
@@ -33,7 +37,8 @@ The first thing they try is to perform basic arithmetic operations
 {: .output}
 
 That works as expected.
-It is also possible to create a variable by binding a name to a value via the assignment operator `=`, which makes it easier to refer to them later on.
+It is also possible to bind a name to a value via the assignment operator `=`,
+which makes it easier to refer to the value later on.
 These names are called _variables_.
 
 ~~~
@@ -47,8 +52,9 @@ distance_x_2 = 2 * distance
 {: .output}
 
 Melissa notices that assignment also returns the value.
+She can also check which variables are defined in the current session by
+running
 
-She can also check which variables are defined in the current session by running
 ~~~
 julia> varinfo()
   name                    size summary
@@ -65,12 +71,15 @@ julia> varinfo()
 
 ## Unicode
 
-In julia unicode characters are also allowed as variables like `α = 2`.
-Unicode characters can be entered by a backslash followed by their LaTeX-name and then pressing <kbd>tab</kbd> (in this case `\alpha`<kbd>tab</kbd>).
+In Julia, Unicode characters are also allowed as variables like `α = 2`.
+Unicode characters can be entered by a backslash followed by their LaTeX-name
+and then pressing `tab` (in this case `\alpha``tab`).
 
 ## REPL-modes
 
-Unfortunately Melissa can't remember the LaTeX name of ∂ so she copies the character, presses <kbd>?</kbd> to enter the help mode, pastes the character and gets
+Unfortunately Melissa can't remember the LaTeX name of ∂ so she copies the
+character, presses `?` to enter the help mode, pastes the character and gets
+
 ~~~
 help?> ∂
 "∂" can be typed by \partial<tab>
@@ -80,15 +89,18 @@ help?> ∂
 Great! This way she can easily look up the names she needs.
 She gets back to normal mode by pressing backspace.
 
-Another useful mode is the shell mode that can be entered by pressing <kbd>;</kbd>.
+Another useful mode is the shell mode that can be entered by pressing `;`.
 The prompt has now changed to shell.
-It can be used to issue commands of the underlying shell, but don't confuse it with an actual shell: Special shell syntax like piping won't work.
+It can be used to issue commands of the underlying shell, but don't confuse it
+with an actual shell: Special shell syntax like piping won't work.
 
 > ## Hello shell mode
+>
 > Use the shell mode to start nano and save your first `.jl` file
 {: .challenge}
 
-Finally there is the package mode that is entered with <kbd>]</kbd> which is used for package management, which will be covered later on.
-To exit the shell or pkg mode use <kbd>backspace</kbd>.
+Finally there is the package mode that is entered with `]` which is used for
+package management, which will be covered later on.
+To exit the shell or pkg mode use `backspace`.
 
 {% include links.md %}