Split introduction into shorter chapters and fix webpage bug

URL escaping stuff

Author: bryal

Book/build.py

@@ -7,6 +7,7 @@
 
 import os
 import shutil
+from urllib.parse import quote
 from subprocess import Popen, PIPE
 
 def read_file(filepath):
@@ -54,7 +55,7 @@ def build_sections(sources):
         next_chap_name = "Table of contents"
         if (i + 1) < len(chapters):
             next_section, next_chap_name, _ = chapters[i + 1]
-            next_chap_href = "../{}/{}.html".format(next_section, next_chap_name)
+            next_chap_href = "../{}/{}.html".format(quote(next_section, safe=''), quote(next_chap_name, safe=''))
         if not os.path.exists(section):
             os.makedirs(section)
         chapter_path = "../../" + chapter_source
@@ -75,10 +76,11 @@ def build_sections(sources):
                 "lhs-source-href": lhs_source_href,
                 "lhs-source-name": lhs_source_name,
             })
-        out_path = "{}/{}.html".format(section, chapter_name)
+        out_path   = "{}/{}.html".format(section, chapter_name)
+        out_path_u = "{}/{}.html".format(quote(section, safe=''), quote(chapter_name, safe=''))
         write_string_to_file(chapter, out_path)
         copy_images(os.path.dirname(chapter_path), section)
-        prev_chap_href = "../" + out_path
+        prev_chap_href = "../" + out_path_u
         prev_chap_name = chapter_name
 
 def build_index(sources):
@@ -88,7 +90,7 @@ def build_index(sources):
         toc += "<div>" + section_name + "</div>\n"
         toc += "<ul>\n"
         for (chapter_name, _) in chapter_sources:
-            chapter_path = "{}/{}.html".format(section_name, chapter_name)
+            chapter_path = "{}/{}.html".format(quote(section_name, safe=''), quote(chapter_name, safe=''))
             toc += "<li><a href=\"{}\">{}</a></li>\n".format(chapter_path, chapter_name)
         toc += "</ul>\n</li>\n"
     index_template = open_template("index")
@@ -97,7 +99,9 @@ def build_index(sources):
 
 sources = [
     ("Introduction", [
-        (">> Start here <<", "Physics/src/Introduction/Introduction.lhs"),
+        ("About this book", "Physics/src/Introduction/About.lhs"),
+        ("So what's a DSL?", "Physics/src/Introduction/WhatIsADsl.lhs"),
+        ("Getting started", "Physics/src/Introduction/GettingStarted.lhs"),
     ]),
     ("Calculus", [
         ("Introduction", "Physics/src/Calculus/Intro.lhs"),
@@ -124,7 +128,6 @@ def build_index(sources):
     #     ("Gungbräda", "Physics/src/Examples/Gungbraeda.lhs"),
     #     ("krafter på lådor", "Physics/src/Examples/krafter_pa_lador.lhs"),
     # ])
-
 ]
 
 if not os.path.exists("build"):

Physics/src/Introduction/About.lhs

@@ -0,0 +1,39 @@
+About this book
+======================================================================
+
+You've arrived at **Learn You a Physics for Great Good**,
+the #1 stop for all your beginner-to-intermediate needs of learning
+**Physics** through the use of **Domain Specific Languages**
+(DSLs).
+
+This book was written as a [BSc thesis
+project](https://github.com/DSLsofMath/BScProj2018) at Chalmers
+University of Technology as an offshoot of a bachelor's level elective
+course [*Domain Specific Languages of
+Mathematics*](https://github.com/DSLsofMath/DSLsofMath). The goal of
+the the project and the reason for the existence of this book, is to
+help (primarily CS) students learn physics better. We think that the use
+of domain specific languages to teach the subject will help set these
+students in the right mindset to learn physics efficiently and
+properly. An observed problem has been that students base their mental
+models completely or partially on intuition and incorrect assumptions,
+instead of on definitions and proved theorems where validity is
+ensured. This may be a bad habit stemming from the way math and
+physics is taught in earlier stages of the education, and we think
+that DSLs will inherently force students into the right mindset for
+learning this subject well! Further, many textbooks on physics are
+incredibly thick and boring, so we've decided to emulate the great and
+good [Learn You a Haskell for Great
+Good](http://learnyouahaskell.com/) in order to provide som comic
+relief in between all the dramatic definitions.
+
+In this book, we will study physics through the lens of DSLs. We will
+need to pay close attention to definitions, throughly ponder any
+non-trivial syntax, and verify (via tests or proofs) that the things
+we do are actually correct. The areas covered include such things as:
+dimensional analysis, vectors, calculus, and more!
+
+The book is aimed at you who have some knowledge of
+[Haskell](https://www.haskell.org/). If you know what a `class` and an
+`instance` is, you're probably good to go! Even if you don't we're
+sure you could pick it up as we go. We believe in you!

Physics/src/Introduction/GettingStarted.lhs

@@ -0,0 +1,41 @@
+
+
+
+
+What you need to dive in
+======================================================================
+
+To just follow along and implement the same stuff we do, a single
+document loaded into GHCi will do. For this, you just need to install the
+[Haskell Platform](https://www.haskell.org/platform/).
+
+If you want to automatically install any required dependencies, like
+[*Hatlab*](https://github.com/DSLsofMath/Hatlab) which will be used
+later on, install [Stack](https://haskellstack.org). Stack is a build
+system that will automatically get dependencies and build the project
+for you. If you want to build the code the same way we do, this is
+what you'll need. With Stack installed and [our repository
+cloned](https://github.com/DSLsofMath/BScProj2018), enter the
+`Physics` directory and type `stack build`. Stack should now download
+and compile all necessary dependencies, such that they are avaiable
+when you load a module in GHCi.
+
+
+
+If you need to sharpen up your skills
+======================================================================
+
+If you need to freshen up on your Haskell, [Learn You a Haskell for
+Great Good](http://learnyouahaskell.com/) is a great book that covers
+all the important stuff in a humorous manner that really holds your
+attention.
+
+If you still don't really get what DSLs are all about, try reading the
+["notes" (almost a full book really) for the course on DSLs of math at
+Chalmers](https://github.com/DSLsofMath/DSLsofMath/tree/master/L/snapshots). If
+you're studying at Chalmers, it is even better to actually take the course!
+
+If there's some part of the material that you still think is unclear
+(or maybe even wrong? Blasphemy!), please [open an issue on the github
+repo!](https://github.com/DSLsofMath/BScProj2018/issues). We'll look
+into it!

Physics/src/Introduction/Introduction.lhs

@@ -0,0 +1,81 @@
+So what's a DSL?
+======================================================================
+
+In general, a domain specific language is simply a computer language
+for a specific domain. It's NOT a synonym for
+[jargon](http://www.catb.org/jargon/html/online-preface.html)! DSLs
+can be specialized for markup, like
+[*HTML*](https://en.wikipedia.org/wiki/HTML); for modelling, like
+[*EBNF*](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form);
+for shell scripting, like
+[*Bash*](https://en.wikipedia.org/wiki/Bash_%28Unix_shell%29); and
+more.
+
+The languages we will construct will mostly concern modelling of
+physics and mathematics. We will create data structures in Haskell to
+represent the same physics calculations that we write on paper, in
+such a way that we can write functions to, for example, analyze the
+expressions for validity.
+
+Look, we'll demonstrate. Let's say we want to model a language that is
+a subset to the common algebra we're all familiar with. Our language
+will consist expressions of a single variable and addition. For
+example, the following three expressions are all valid in such a language:
+
+$$x + x$$
+
+$$x$$
+
+$$(x + x) + (x + x)$$
+
+When implementing a DSL, we typically start with modelling the
+syntax. Let's first declare a data type for the language
+
+> data Expr
+
+Then we interpret the textual description of the language. "Our
+language will consist of expressions of a single variable and
+addition". Ok, so an expression can be one of two things then: a
+single variable
+
+>   = X
+
+or two expressions added together.
+
+>   | Add Expr Expr
+
+And that's it, kind of! However, a DSL without any associated
+functions for validation, symbolic manipulation, evaluation, or
+somesuch, is really no DSL at all! We must DO something with it, or
+there is no point!
+
+One thing we can do with expressions such as these, is compare whether
+two of them are equal. Even without using any numbers, we can test
+this by simply counting the $x$s! If both expressions contain the same
+number of $x$s, they will be equal!
+
+> eq :: Expr -> Expr -> Bool
+> eq e1 e2 = count e1 == count e2
+>   where count X           = 1
+>         count (Add e1 e2) = count e1 + count e2
+
+We can now test whether our expressions are equal.
+
+< ghci> eq (Add (Add X X) X) (Add X (Add X X))
+< True
+
+And NOW that's it (if we want to stop here)! This is a completely
+valid (but boring) DSL. We've modelled the syntax, and added a function
+that operates symbolically on our language. This is a very small and
+simple DSL, and you've likely done something similar before without
+even realizing you were constructing a DSL. It can really be that
+simple
+
+In other DSLs we may also look at evaluation and the semantics of a
+language, i.e. what is the actual type of the result when we
+*evaluate* or "compute" our expressions.
+
+Throughout this book we'll construct and use DSLs in many different
+ways. Different parts of the physics we look at will require different
+DSL treatments, basically. There is no *one* model to use for all
+DSLs.