 ;; ## Puppet catalog parsing
 ;;
-;; Puppet catalogs aren't really pre-configured for easy persistence
-;; and manipulation; while they contain complete records of all
-;; resources and edges, and most things are properly encoded as lists
-;; or maps, there are still a number of places where structure is
-;; absent or lacking:
+;; Functions that handle conversion of catalogs from wire format to
+;; internal Grayskull format.
+;;
+;; The wire format is described in detail in [the
+;; spec](../spec/catalog-wire-format.md).
+;;
+;; There are a number of transformations we apply to wire format
+;; catalogs during conversion to our internal format; while wire
+;; format catalogs contain complete records of all resources and
+;; edges, and most things are properly encoded as lists or maps, there
+;; are still a number of places where structure is absent or lacking:
 ;;
 ;; 1. Resource specifiers are represented as opaque strings, like
 ;;    `Class[Foobar]`, as opposed to something like

;; * `:type` and `:title` are used to produce a `resource-spec` for
;;   this resource
;;
;; ### Dependency Specification
;;
;; A representation of an "edge" in the catalog. All edges have the
;; following form:
;;
;;     {:source       <resource spec>
;;      :target       <resource spec>

;;    operations that need to correlate against specific resources
;;    unneccesarily difficult
;;
;; 4. Keys to all maps are strings (to conform with JSON), instead of
;;    more convenient Clojure keywords
;;
;; ### Terminology
;;
;; Unless otherwise indicated, all terminology for catalog components
;; matches terms listed in [the spec](../spec/catalog-wire-format.md).
;;
;; ### Transformed constructs
;;
;; ### Resource Specifier (resource-spec)
;;
