From 663bf88da3b06d5b21624e3aaf1993012b0292e5 Mon Sep 17 00:00:00 2001 From: Pieter van de Bruggen Date: Fri, 25 Feb 2011 21:11:55 -0800 Subject: Updating README with more assertive language. --- README.md | 60 +++++++++++++++++++++++++++++++++++++----------------------- 1 file changed, 37 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 4fd7da3..5934378 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,44 @@ -This repository acts as an attempt at specifying both standard- and edge-case -behavior for libraries parsing Mustache (or a superset thereof). Early -development will focus on describing idealized output, with later work being -done to normalize expectations. *It is not expected that any implementation -support any draft prior to v1.0.0.* +The repository at https://github.com/mustache/spec is the formal standard for +Mustache. It defines both normal usage and edge-case behavior for libraries +parsing the Mustache templating language (or a superset thereof). + +This specification is being [semantically versioned](http://semver.org). +Roughly described, major version changes will always represent backwards +incompatible changes, minor version changes will always represent new language +features and will be backwards compatible, and patch ('tiny') version changes +will always be bug fixes. + +Mustache implementations SHOULD report the most recent version of the spec +they have support for. It is RECOMMENDED that implementations supporting at +least v1.0.0 of this spec refer to themselves as "Mustache-like", or +"Mustache-inspired". + +The specification is developed as a series of YAML files, under the `specs` +directory. + +Alternate Formats +----------------- + +Since YAML is a reasonably complex format that not every language has good +tools for working with, we also provide JSON versions of the specs on a +best-effort basis. + +These should be identical to the YAML specifications, but if you find the need +to regenerate them, they can be trivially rebuilt by invoking `rake build`. + +It is also worth noting that some specifications (notably, the lambda module) +rely on YAML "tags" to denote special types of data (e.g. source code). Since +JSON offers no way to denote this, a special key ("`__tag__`") is injected +with the name of the tag as its value. See `TESTING.md` for more information +about handling tagged data. Optional Modules ---------------- -Specification files beginning with a tilde (~) describe optional modules. At -present, the only module being described as optional is regarding support for -lambdas. As a guideline, a module may be a candidate for optionality when: +Specification files beginning with a tilde (`~`) describe optional modules. +At present, the only module being described as optional is regarding support +for lambdas. As a guideline, a module may be a candidate for optionality +when: * It does not affect the core syntax of the language. * It does not significantly affect the output of rendered templates. @@ -28,18 +57,3 @@ outside this core specification, as adjunct specifications. Implementors are strongly encouraged to support any and all modules they are reasonably capable of supporting. - -Alternate Formats ------------------ - -Since YAML is a reasonably complex format that not every language has good -tools for working with, we are also providing JSON versions of the specs. -These should be kept identical to the YAML specifications, but if you find the -need to regenerate them, they can be trivially rebuilt by invoking `rake -build`. - -It is also worth noting that some specifications (notably, the lambda module) -rely on YAML "tags" to denote special types of data (e.g. source code). Since -JSON offers no way to denote this, a special key ("`__tag__`") is injected with -the name of the tag as its value. See `TESTING.md` for more information about -handling tagged data. -- cgit v1.2.1