Initial ptx conversion and Ch1 cleanup

.gitignore

@@ -2,3 +2,10 @@ pavement.py
 build
 published
 __pycache__
+output
+.error_schema.log
+logs
+
+# at least temporarily, ignore stuff the CLI makes for github codespaces
+.devcontainer.json
+.github

pretext/Chapter1/debugging.ptx

@@ -0,0 +1,164 @@
+<?xml version="1.0"?>
+<section xml:id="chapter1_what-is-debugging">
+  <title>What is Debugging?</title>
+  <p>Programming is a complex process, and since it is done by human
+    beings, it often leads to errors. For whimsical reasons, programming errors are called <term>
+    bugs</term> and the process of tracking them down and correcting them is called <term>debugging</term>
+    .</p>
+  <p>There are a few different kinds of errors that can occur in a program,
+    and it is useful to distinguish between them in order to track them down
+    more quickly.</p>
+  <subsection xml:id="chapter1_compile-time-errors">
+    <title>Compile-time errors</title>
+    <p>The compiler can only translate a program if the program is
+      syntactically correct; otherwise, the compilation fails and you will not
+      be able to run your program.</p>
+    <note>
+      <p><term>Syntax</term> refers to the structure of your program and the rules about that
+        structure.</p>
+    </note>
+    <p>For example, in English, a sentence must begin with a capital letter and
+      end with a period. this sentence contains a syntax error. So does this
+      one</p>
+    <p>For most readers, a few syntax errors are not a significant problem,
+      which is why we can read the poetry of e e cummings without spewing
+      error messages.</p>
+    <p>Compilers are not so forgiving. If there is a single syntax error
+      anywhere in your program, the compiler will print an error message and
+      quit, and you will not be able to run your program.</p>
+    <p>To make matters worse, there are more syntax rules in C++ than there are
+      in English, and the error messages you get from the compiler are often
+      not very helpful. During the first few weeks of your programming career,
+      you will probably spend a lot of time tracking down syntax errors. As
+      you gain experience, though, you will make fewer errors and find them
+      faster.</p>
+  </subsection>
+  <subsection xml:id="chapter1_run-time-errors-run-time">
+    <title>Run-time errors</title>
+    <p>The second type of error is a <term>run-time error</term>,
+      so-called because the error does not appear until you run the program.</p>
+    <p>For the simple sorts of programs we will be writing for the next few
+      weeks, run-time errors are rare, so it might be a little while before
+      you encounter one.</p>
+  </subsection>
+  <subsection xml:id="chapter1_logic-errors-and-semantics">
+    <title>Logic errors and semantics</title>
+    <p>The third type of error is the <term>logical</term> or <term>
+      semantic</term> error.</p>
+    <note>
+      <p><term>Semantics</term> refer to the meaning of the program.</p>
+    </note>
+    <p>If there is a semantic error in your program, it will compile and run successfully, in the
+      sense that the computer will not generate any error messages, but it will not do the right
+      thing. It will do something else. <term>Specifically, it will do what you told it to do.</term></p>
+    <p>The problem is that the program you wrote is not the program you wanted
+      to write. The meaning of the program is wrong. Identifying semantic errors
+      can be tricky, since it requires you to work backwards by looking at the
+      output of the program and trying to figure out what it is doing.</p>
+  </subsection>
+  <subsection xml:id="chapter1_experimental-debugging">
+    <title>Experimental debugging</title>
+    <p>One of the most important skills you should acquire from working with
+      this book is debugging. Although it can be frustrating, debugging is one
+      of the most intellectually rich, challenging, and interesting parts of
+      programming.</p>
+    <p>In some ways debugging is like detective work. You are confronted with
+      clues and you have to infer the processes and events that lead to the
+      results you see.</p>
+    <p>Debugging is also like an experimental science. Once you have an idea what is going wrong,
+      you modify your program and try again. If your hypothesis was correct, then you can predict
+      the result of the modification, and you take a step closer to a working program. If your
+      hypothesis was wrong, you have to come up with a new one. As Sherlock Holmes pointed out, <q>When
+      you have eliminated the impossible, whatever
+        remains, however improbable, must be the truth.</q> (from A. Conan Doyle's <em>The Sign of
+      Four</em>).</p>
+    <p>For some people, programming and debugging are the same thing. That is, programming is the
+      process of gradually debugging a program until it does what you want. The idea is that you
+      should always start with a working program that does <em>something</em>, and make small
+      modifications, debugging them as you go, so that you always have a working program.</p>
+    <p>For example, Linux is an operating system that contains thousands of lines of code, but it
+      started out as a simple program Linus Torvalds used to explore the Intel 80386 chip. According
+      to Larry Greenfield, <q>One of Linus's earlier projects was a program that would switch
+      between
+        printing AAAA and BBBB. This later evolved to Linux</q> (from <em>The Linux
+        Users' Guide</em> Beta Version 1).</p>
+    <p>In later chapters I will make more suggestions about debugging and other
+      programming practices.</p>
+    <exercise label="debugging_1">
+      <statement>
+        <p>Another word for an error is a(n) <var/>. The process of
+          finding and fixing errors is called <var/>.
+        </p>
+      </statement>
+      <setup>
+        <var case="insensitive">
+          <condition string="^\s*bug\s*$">
+            <feedback>
+              <p>Correct!</p>
+            </feedback>
+          </condition>
+          <condition string="^\s*.*\s*$">
+            <feedback>
+              <p>Try again!</p>
+            </feedback>
+          </condition>
+        </var>
+        <var case="insensitive">
+          <condition string="^\s*debugging\s*$">
+            <feedback>
+              <p>Correct!</p>
+            </feedback>
+          </condition>
+          <condition string="^\s*.*\s*$">
+            <feedback>
+              <p>Try again!</p>
+            </feedback>
+          </condition>
+        </var>
+      </setup>
+    </exercise>
+    <exercise label="debugging_2">
+      <statement>
+        <p>Match each term to its definition!</p>
+      </statement>
+      <feedback>
+        <p>Try again!</p>
+      </feedback>
+      <matches>
+        <match order="1">
+          <premise>syntax (compile-time) error</premise>
+          <response>an error that surfaces when something is wrong with the structure of your
+            program</response>
+        </match>
+        <match order="2">
+          <premise>run-time error</premise>
+          <response>an error that comes up when your program is executed</response>
+        </match>
+        <match order="3">
+          <premise>semantic error</premise>
+          <response>your program does what you told it to do, not what you intended for it to do</response>
+        </match>
+      </matches>
+    </exercise>
+    <exercise label="debugging_4">
+      <statement>
+        <p>The structure of your program and the rules it must follow are called the <var/>.
+        </p>
+      </statement>
+      <setup>
+        <var case="insensitive">
+          <condition string="^\s*syntax\s*$">
+            <feedback>
+              <p>Correct!</p>
+            </feedback>
+          </condition>
+          <condition string="^\s*.*\s*$">
+            <feedback>
+              <p>Try again!</p>
+            </feedback>
+          </condition>
+        </var>
+      </setup>
+    </exercise>
+  </subsection>
+</section>