updated forward

CONTRIBUTING.md

@@ -7,17 +7,41 @@ mailing list before putting in a lot of effort. The first step is to
 
 Also, while GitHub is a great place to archive and track revisions over time,
 it is often the case that a shared Google Document is a better tool for
-collaboration. This is true not only for from-scratch efforts, but also as a way to
-get comments and feedback on a fairly complete draft. If you're game, we
-have a shared [Google Drive Folder](https://drive.google.com/drive/u/2/folders/1diDcXKTyMFyuR7g1M6gTRuCnHXAUYj7C?ths=true).
+collaboration. This is true not only for from-scratch efforts, but
+also as a way to get comments and feedback on a fairly complete
+draft. If you're game, we have a shared
+[Google Drive Folder](https://drive.google.com/drive/u/2/folders/1diDcXKTyMFyuR7g1M6gTRuCnHXAUYj7C?ths=true).
+
+If you have new material that doesn't fit into the current book
+organization in an obvious way, check it into the `advanced-topics`
+repo. We'll figure out the best way to organize material (both old and
+new) over time. We've also created a `tools` repo in anticipation of
+contributions describing network diagnostic, monitoring, and analysis
+tools students can run to "see" the Internet in action.
 
 As for stylistic guidelines, there are only a few things to keep in mind.
 
-First, try to keep each major topic (what corresponded to a chapter in the original textbook) self-contained, with minimal forward- or backward-references to other material. The idea is that each chapter should be able to stand alone.
+First, try to keep each major topic (what corresponded to a chapter in
+the original textbook) self-contained, with minimal forward- or
+backward-references to other material. The idea is that each chapter
+should be able to stand alone. (Think self-contained software module
+with no hard-coded dependencies.)
+
+Second, adhere to best practices using MarkDown. Run `make lint` on any
+new text you write. See
+https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md
+for the rules being applied. This may seem pedantic, but it's
+important that the raw MarkDown be easily read, edited, and compared.
 
-Second, adhere to best practices using MarkDown. Run make lint on any new text you write. See https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md for the rules being applied.
+> **Note:** We're relaxed the "No Inline HTML" rule (MD033) to allow
+> for the current treatment of Figures and Tables. This will
+> eventually be corrected, and we suggest otherwise abiding by the
+> rule.
 
-Third, when creating figures, start with the PowerPoint template available here (TODO).
+Third, when creating figures, reuse as many of the existing graphical
+elements as possible and stick to the current color scheme. Check in
+both editable source (currently `.eps`) and a PNG file (300 dpi) for each
+figure.
 
 Finally, keep the *Systems Approach* in mind as you write. To quote the
 Preface in the original book:

Makefile

@@ -17,6 +17,9 @@ LINT_STYLE ?= mdl_relaxed.rb
 serve: setup
 	gitbook serve
 
+pdf:	setup
+	gitbook pdf ./ ./book.pdf
+
 build: setup
 	gitbook build
 

README.md

@@ -1,7 +1,3 @@
-<!--- Copyright 2018, Larry Peterson & Bruce Davie    --->
-<!--- Licsenced under the CC BY License, Version 4.0 --->
-<!--- https://creativecommons.org/licenses/by/4.0  --->
-
 # Preface 
 
 This site contains source text for *Computer Networks: A Systems
@@ -11,21 +7,29 @@ license. The community is invited to contribute corrections,
 improvements, updates, and new material under the same terms.
 
 Like many open source software projects, this one has been seeded
-with once proprietary content: the 5th edition of *Peterson and Davie*,
+with once restricted content: the 5th edition of *Peterson and Davie*,
 copyrighted by Elsevier. Our hope is that open sourcing this material
-will not only make it widely available, but also serve as an attractor
-for new content: updating what's already there, expanding it to
-include additional topics, and augmenting the text with additional
-teaching collateral.
+will both make it widely available and serve as an attractor for new
+content: updating what's already there, expanding it to cover new
+topics, and augmenting the text with additional teaching collateral.
+
+We will initially play an editorial role (curating and wordsmithing)
+for contributions that come back, but our plan is to share ownership
+of the project with others committed to its success.
+
+And if you make use of this work, the attribution should include
+the following information:
 
-We will initially play an editorial role—vetting and wordsmithing
-contributions—but our plan is share ownership of the project with
-others committed to its success.
+> *Title: Computer Networks: A Systems Approach  
+> Authors: Larry Peterson and Bruce Davie  
+> Copyright: Elsevier, 2012  
+> Source: https://github.com/SystemsApproach  
+> License: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0)*
 
 ## Getting Started
 
-The material is organize as a git repository per chapter, each
-of which focuses on a major networking topic (e.g., *Internetworking*,
+The material is organize as a git repository per chapter, each of
+which focuses on a major networking topic (e.g., *Internetworking*,
 *Congestion Control*). A "root" repo (this one) contains the gitbook
 files that can be used to create a full book. To build a web-viewable
 version, you first need to install a couple packages:
@@ -44,14 +48,15 @@ git submodule init
 git submodule update
 ```
 
-To build the gitbook, simply type:
+To build a web version of the book, simply type:
 
 ```shell
 make
 ```
 
 If all goes well, you will be able to view the book in your browser at
-`localhost:4000`.
+`localhost:4000`. (If all doesn't go well, you might try typing `make`
+a second tme.)
 
 ## How to Contribute
 
@@ -66,16 +71,16 @@ improvements back into GitHub.
 If you do want to contribute either patches or new material, you will
 need to sign a [Contributor Licensing Agreement
 (CLA)](https://github.com/SystemsApproach/book/blob/master/CLA.md).
-There's nothing you need to do this minute; you'll be prompted to
-sign the CLA the first time you make a pull request.
+You'll be prompted to sign the CLA the first time you make a pull request.
 
 The CLA is pretty straightforward: it establishes that (a) you have
 the right to contribute what you're contributing, and (b) what you
 contribute is available to everyone else under the same
 [CC BY](https://creativecommons.org/licenses/by/4.0) terms as
 the existing content. The CLA is a little unusual in that it explicitly
-calls out Elsevier's rights, but suffice it to say, the publishing
-industry is still getting comfortable with open source.
+calls out Elsevier's rights (which are the same as everyone's), but
+this does signal their intent to continue publishing textbooks based
+on the material.
 
 You should also familiarize yourself with the [guidelines for
 contributing](https://github.com/SystemsApproach/book/blob/master/CONTRIBUTING.md).
@@ -88,21 +93,29 @@ cd ~/systemsapproach
 make lint
 ```
 
-Finally, if you'd like to contribute and are looking for something
-that needs attention, see the current list of
-[Issues](https://github.com/SystemsApproach/book/issues/)
-or the [Project Board](https://github.com/orgs/SystemsApproach/projects/).
+If you'd like to contribute and are looking for something that needs
+attention, see the current
+[Project Board](https://github.com/orgs/SystemsApproach/projects/).
 We'd also like to expand the set of topics/chapters beyond the initial
 set inherited from the 5th edition, so if you have ideas, we'd love to
 hear from you. Send email to `discuss@systemsapproach.org`, or better
 yet, [join the
 forum](https://groups.google.com/a/systemsapproach.org/forum/#!forum/discuss).
 
+Finally, in as much as this an on-going effort, we will try to record
+and track our
+[progress](https://github.com/SystemsApproach/book/blob/master/status.md).
+For now, think of this as a poor-man's release notes.
+
 ## Join Us
 
 We hope you've gotten value out of *Computer Networks: A Systems
 Approach* over the years, and we're eager to have you join us in this
 new venture.
 
 Larry Peterson & Bruce Davie  
-August 8, 2018
+August 2018
+
+{% creativecommons type="by" %}
+{% endcreativecommons %}
+

mdl_relaxed.rb

@@ -28,19 +28,22 @@
 # Exclude rule: Trailing spaces
 exclude_rule 'MD009'
 
+# Allow hard tabs (Limited to Figures)
+exclude_rule 'MD010'
+
 # Don't enforce line length limitations within code blocks and tables
 rule 'MD013', :code_blocks => false, :tables => false
 
 # Allow  ! and ? as trailing punctuation in headers
 rule 'MD026', :punctuation => '.,;:'
 
-# Exclude rule: Multiple spaces after blockquote symbol
-exclude_rule 'MD027'
-
 # Numbered lists should have the correct order
 rule 'MD029', :style => "ordered"
 
-# Allow Bare URLs
+# Allow Inline HTML (Limited to Figures)
+exclude_rule 'MD033'
+
+# Allow Bare URLs (e.g., as examples)
 exclude_rule 'MD034'
 
 # Allow copyright notice as an HTML comment before top level header