added more detailed checkstyle running instructions (unfinished)

fixed broken link on style guide
added more blurb to style guide

Author: Matt Hughes

checkstyle.md

@@ -0,0 +1,45 @@
+---
+layout: default
+title: CS 1331 - Running Checkstyle
+---
+
+# How To Run Checkstyle on Java Source Files
+
+One runs checkstyle on Java source code using the `java` command:
+
+```bash
+java -jar checkstyle-6.2.1.jar MyJavaFile.java
+```
+This command is not altogether different from the command that we use to run
+compiled Java classes we have written. The command creates an instance of the
+Java Virtual Machine, and runs a `main(String[])` method defined in some class.
+But rather than invoking the `main(String[])` method of a class we have
+written, it instead runs that of a class packaged inside of the provided Java
+archive (or `.jar`) file.
+
+It is important to note that checkstyle will only give reliable output on
+*compiling* Java source code. Source code which contains syntax errors may not
+yield meaningful output when run through checkstyle.
+
+One can pass more than one Java source file to Checkstyle. It is recommended
+that you always use the command
+
+```bash
+java -jar checkstyle-6.2.1.jar *.java
+```
+to invoke checkstyle on each file in the current working directory with a name
+ending in `.java`. This helps to ensure that you do not accidentally submit
+`.java` files containing style violations.
+
+## Point Deductions
+
+For assignments submitted in this class, style counts in a very real sense.
+Grades on assignments will be reduced by up to one point per error reported. It
+is very important to correct style errors as you encounter them. As such, it is
+recommended that you run checkstyle on your code several times as you are
+writing it.
+
+## Advanced Options
+
+Checkstyle can also be used to check formatting of Javadoc comments written
+alongside your source code. 

cs1331-style-guide.html

@@ -5,18 +5,33 @@
 
 <h1>CS 1331 Java Style Guide</h1>
 
-<p>This document summarizes and in some cases clarifies Sun/Oracle's
-<a href="http://www.oracle.com/technetwork/java/javase/documentation/codeconvtoc-136057.html">Java Code Conventions</a>
-(and in some places copies it directly) and the Checkstyle checks specified in
-<a href="resources/cs1331-checkstyle.xml">cs1331-checkstyle.xml</a>.
-The Checkstyle web site also documents each of its standard checks here: <a href="http://checkstyle.sourceforge.net/availablechecks.html">http://checkstyle.sourceforge.net/availablechecks.html</a></p>
+<p>Style is very important when writing code. Often code is not judged simply
+base on how effectively it performs a specific function, but also how easily it
+can be understood by a human reader. While rules of style vary, it is important
+to be able to learn to write code which conforms to a given standard.</p>
+
+<p>In this class, the style rules that you are asked to follow are crystallized
+into an automated tool, called
+<a href="http://checkstyle.sourceforge.net">Checkstyle</a>. This tool is
+configurable to check for a large number of different stylistic errors.
+Additional details about how to run checkstyle on your code can be found <a href="checkstyle.html">here.</a></p>
+
 <p>The file you need to run Checkstyle:</p>
 <ul class="simple">
 <li><a href="resources/checkstyle-6.2.1.jar">checkstyle-6.2.1.jar</a></li>
 <!--<li>New Version: <a href="resources/checkstyle1331v2.jar">checkstyle1331v2.jar</a></li>-->
 </ul>
-Run checkstyle on your Java files like so:
+<p>In the simplest case, run checkstyle on your Java files like so:
 <pre>java -jar checkstyle-6.2.1.jar MyJavaFile.java</pre>
+For more advanced options (which will be necessary in later portions of the
+semester), check out the <a href="checkstyle.html">options available</a> for
+running checkstyle.</p>
+
+<p>The rest of this document summarizes and in some cases clarifies Sun/Oracle's
+<a href="http://www.oracle.com/technetwork/java/javase/documentation/codeconvtoc-136057.html">Java Code Conventions</a>
+(and in some places copies it directly) and the Checkstyle checks specified in
+<a href="resources/cs1331-checkstyle.xml">cs1331-checkstyle.xml</a>.
+The Checkstyle web site also documents each of its standard checks here: <a href="http://checkstyle.sourceforge.net/checks.html">http://checkstyle.sourceforge.net/checks.html</a></p>
 <div class="section" id="names">
 <h1>Names</h1>
 <ul>