documentation

README.md

@@ -1,42 +1,27 @@
-This is a toy configuration language.  If you want to know why, see the [WHY](WHY.md) doc.
+# Moon
+
+Moon is a human-readable data exchange format designed to be used as a
+configuration language in software projects. This projects contains a
+description of Moon's grammar and a reference implementation of a moon
+interpreter written in Go. For some history as to why this project was seen as
+worthwhile, please see the [WHY](WHY.md) doc. For a description of Moon's
+design goals (and non-goals), please see the [GOALS](GOALS.md) doc.
 
 # Instability
 
-This isn't even remotely stable.  Don't use this in an actual project, I
-promise you I will break this.
-
-# What it is
-
-Moon is a configuration language intended to replace JSON as a configuration
-format in Go projects.  The syntax is fairly similar, with a few changes:
-
-- instead of having some hand-wavy "number" thing without ever specifying the
-  valid ranges or anything like that, there are two number types: int and
-  float64.  Int means int32 on 32bit systems and int64 on 64bit systems.  Maybe
-  I'll go back on that because it sounds really dumb when I type it out.
-- support for complex numbers.  The only reason I included this is that it's
-  included in the text/template package in the standard library and I stole the
-  number-parsing code from that library.
-- bare strings.  Support here is somewhat up in the air.  Inside of bare
-  strings, the characters [, ], ;, :, {, and } must be escaped, because each of
-  those can terminate a bare string.
-- comments.  There are no comments in JSON and that's incredibly annoying.
-  Moon has them.
-- variables.  In moon, you can make a reference to a value that was already
-  defined.
-- hidden variables.  This sounds really dumb but it quickly became apparent
-  that if you're using variables to compose something, those variables end up
-  polluting the namespace of the moon document.
-- a command-line tool.  I'm sure these exist for json but there's no official
-  "this is the tool, that one isn't" decree.
-- something kinda like xpath that lets you select elements in a document.
-
-# How it works
-
-json and similar formats parse text and render some kind of parse tree.  We do
-the same thing in moon, but then we walk the tree and evaluate it, which is why
-variables are a thing.  It's effectively just enough of a dynamic language
-interpreter for variables to work.
+This project is not yet stable. Things may change. It's not recommended that
+you use this in any type of production system, since I can't guarantee future
+compatibility at this time.
+
+# Design
+
+A Moon file is a human-readable description of an unordered collection of
+key-value pairs. Parsing a Moon document always yields either a Moon Document
+or an error.
+
+The top level of a Moon document contains a series of key-value pairs separated with a colon:
+
+![Assignment Diagram](grammar/diagram/Assign.png)
 
 # Types
 

WHY.md

@@ -43,10 +43,10 @@ writing the config files themselves.
 
 Historically, I have always used json as the configuration format for Go
 projects.  I've found this to be the best option.  It's in the standard
-library, so it doesn't add any dependencies to your project.  Everyone can
-understand it, and those that don't pick it up very quickly.  It's a nearly
-ideal format, inasmuch as it doesn't litter itself with spurious information,
-it's relatively compact, and it's a familiar set of non-word characters that
+library, so it doesn't add any dependencies to your project.  For small
+configurations, json is very easy for a human to write.  It's a nearly ideal
+format, inasmuch as it doesn't litter itself with spurious information, it's
+relatively compact, and it's a familiar set of non-word characters that
 everyone can grok.  The parsing API is also quite nice, and the json package in
 the standard library is extremely easy to use.  As far as programming the host
 application, json works very well.
@@ -72,15 +72,8 @@ It also seems to drive my colleagues in ops into an absolute rage.
 
 #### Why not YAML?
 
-Every time I use YAML I accidentally break it.  It's incredibly brittle.  I
-actually do buy the argument that semantic whitespace is great for humans.  I
-programmed a significant amount of Python and loved every minute of it.
-
-But where it really breaks down is that semantic whitespace is an absolute
-showstopper when it comes to generating a configuration file from a template
-system, which is a common technique in
-[Chef](http://en.wikipedia.org/wiki/Chef_%28software%29), the configuration
-management tool we use [where I work](https://www.etsy.com/).  Beyond being
-impossible to template out, it's much, much too complicated.  The YAML spec is
-nearly as large as the specification for Go itself!
+Semantic whitespace makes it difficult to generate YAML from within a template
+language, such as ERB.  Generating configuration files from templates or from a
+parent application is a common strategy when using configuration management
+systems, such as [Chef](https://www.chef.io/chef/).