Fill in the changelog for 1.3.

3 files changed, 93 insertions, 20 deletions

diff --git a/docs/back-matter.rst b/docs/back-matter.rst
index a7833ce..5245d41 100644
--- a/docs/back-matter.rst
+++ b/docs/back-matter.rst
@@ -27,10 +27,10 @@ from the root of a source checkout.
 
 Most of the tests are pairs of input/output files in ``scss/tests/files``; the
 test suite scans for these, compiles all the ``.scss`` files, and compares the
-output with the ``.css`` file of the same name.  You can limit which file tests
-run::
+output with the ``.css`` file of the same name.  To run only particular tests,
+you can pass them directly as filenames::
 
-    py.test --test-file-filter=REGEX,REGEX,REGEX...
+    py.test scss/tests/files/general/000-smoketest.scss
 
 There are also several tests borrowed from the Ruby and C implementations.
 Many of these don't work (due to missing features, different error messages,
@@ -39,8 +39,7 @@ by a test run, you must explicitly opt into them with ``--include-ruby``, even
 when using a file filter.  These files are in the ``from-ruby/`` and
 ``from-sassc/`` subdirectories.
 
-Additionally, test files in the ``xfail/`` subdirectory are assumed to fail.
-Other than these cases, the directory names are arbitrary.
+Other than the borrowed tests, the directory names are arbitrary.
 
 
 License and copyright
@@ -71,6 +70,76 @@ Changelog
 1.3.0 (unreleased)
 ^^^^^^^^^^^^^^^^^^
 
+This is a somewhat transitional release along the road to 2.0, which will
+remove a lot of deprecated features.
+
+Sass/CSS compatibility
+""""""""""""""""""""""
+
+* Importing files from a parent directory with ``../`` now works (as long as the imported file is still on the search path).
+* Multiple CSS imports on the same line are now left unchanged.  (Previously, the line would be repeated once for each import.)
+* CSS 3 character set detection is supported.
+* CSS escapes within strings are supported (though, unlike Sass, are usually printed literally rather than escaped).
+* Map keys may now be arbitrary expressions.
+* Slurpy named arguments are now supported.
+* ``!global`` on variable assignments is now supported (and does nothing, as in Sass).
+* `rebeccapurple`_ is understood as a color name.
+
+.. _rebeccapurple: http://meyerweb.com/eric/thoughts/2014/06/19/rebeccapurple/
+
+Additionally, a great many more constructs should now parse correctly.  By default, when pyScss encounters a parse error, it replaces any interpolations and variables, and treats the result as a single opaque string.
+
+This was the only way syntax like ``url(http://foo/bar)`` was recognized, since a colon is usually not allowed in the middle of a bareword.  As a result, code like ``background: url(...) scale-color(...);`` didn't work, because the url would fail to parse and so pyScss would never even know that ``scale-color`` is supposed to be a function call.
+
+Now, the parser understands most of the unusual quirks of CSS syntax:
+
+* ``()`` is recognized as an empty list.
+* ``url()`` is fully supported.
+* ``expression()``, ``alpha(opacity=...)``, and ``calc()`` are supported (and left alone, except for interpolation).
+* Interpolation is part of the parser, rather than being applied before parsing, so there should be far fewer bugs with it.
+* CSS escapes within barewords are recognized (and ignored).
+* ``!important`` may have whitespace after the ``!``.
+
+Glossing over a bad parse now spits out a deprecation warning, and will be
+removed entirely in 2.0.
+
+Bug fixes
+"""""""""
+
+* Old-style pseudo-element selectors (``:before`` and friends, written with only one colon) always stay at the end of the selector.
+* The CSS3 ``grayscale(90%)`` function is now left alone, rather than being treated as a Sass function.  (Previously, only unitless numbers would trigger this behavior.)
+* Placeholder selectors (``%foo``) no longer end up in the output.
+* Iterating over a list of lists with a single variable works (again).
+* File path handling is much more polite with Windows directory separators.
+* At-rules broken across several lines are now recognized correctly.
+* ``@for ... to`` now excludes the upper bound.
+* ``@extend`` no longer shuffles rules around, and should now produce rules in the same order as Ruby Sass.  It also produces rules in the correct order when extending from the same rule more than once.  Hopefully it's now correct, once and for all.
+* Fixed a couple more Compass gradient bugs.  Probably.
+
+
+New features
+""""""""""""
+
+* Compatibility with Python 3.2, allegedly.
+* Support for building SVG font sheets from within stylesheets.
+* Error messages have been improved once again: parse errors should be somewhat less cryptic, the source of mixins is included in a traceback, and missing closing braces are reported.
+
+Backwards-incompatible changes
+""""""""""""""""""""""""""""""
+
+* Missing imports are now fatal.
+* Much sloppy behavior or reliance on old xCSS features will now produce deprecation warnings.  All such behaviors will be removed in pyScss 2.0.
+
+Internals
+"""""""""
+
+* The C speedups module is now Unicode-aware, and works under CPython 3.
+* There's no longer a runtime warning if the speedups module is not found.
+* pyScss is now (a lot more) Unicode-clean; everything internally is treated as text, not bytes.
+* Compiling the grammar is now much less painful, and doesn't require copy-pasting anything.
+* Several large modules have been broken up further.  ``__init__`` is, at last, virtually empty.
+* All the built-in functions have been moved into built-in extensions.
+
 1.2.0 (Oct 8, 2013)
 ^^^^^^^^^^^^^^^^^^^
 
diff --git a/docs/index.rst b/docs/index.rst
index 50e90c7..5da3cd5 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -6,23 +6,27 @@
 pyScss, a Sass compiler for Python
 ==================================
 
-pyScss compiles Scss (Sass), a superset of CSS that is more powerful, elegant
-and easier to maintain than plain-vanilla CSS. The library acts as a CSS source
-code preprocesor which allows you to use variables, nested rules, mixins, and
-have inheritance of rules, all with a CSS-compatible syntax which the
-preprocessor then compiles to standard CSS.
-
-Scss, as an extension of CSS, helps keep large stylesheets well-organized. It
-borrows concepts and functionality from projects such as OOCSS and other similar
-frameworks like as Sass. It's build on top of the original PHP xCSS codebase
-structure but it's been completely rewritten, many bugs have been fixed and it
-has been extensively extended to support almost the full range of Sass' Scss
-syntax and functionality.
+pyScss is a Python implementation of `Sass`_, a CSS preprocessing language that
+adds variables, expressions, nested rules, mixins, inheritance, and other
+features that help ease the maintenance of large stylesheets.
+
+.. _Sass: http://sass-lang.com/
+
+pyScss also includes support for Compass, and has an extension mechanism for
+adding your own custom behavior.
+
+pyScss is not yet fully compatible with the canonical Ruby implementation, but
+we're getting there and constantly improving.  Please feel free to `file a
+GitHub issue`_ for anything pyScss gets wrong.
+
+.. _file a GitHub issue: https://github.com/Kronuz/pyScss/issues
 
 .. image:: http://pledgie.com/campaigns/16513.png?skin_name=chrome
    :alt: Click here to lend your support to pyScss and make a donation at pledgie.com!
    :target: http://pledgie.com/campaigns/16513
 
+.. TODO this first page should have some basic usage; there's currently nothing
+   particularly helpful on it.  also installation, deps, etc.
 
 Contents:
 
@@ -35,7 +39,6 @@ Contents:
     back-matter
 
 
-
 Indices and tables
 ==================
 
diff --git a/docs/syntax.rst b/docs/syntax.rst
index 930ec2d..0aed584 100644
--- a/docs/syntax.rst
+++ b/docs/syntax.rst
@@ -424,7 +424,8 @@ syntax to work in the future.
 Operations on lists
 -------------------
 
-Binary operations with a list on the left-hand side are performed element-wise:
+Binary operations with a list on the left-hand side are performed
+element-wise::
 
     p {
         margin: (1em 0 3em) * 0.5;  // => 0.5em 0 1.5em
@@ -437,7 +438,7 @@ built-in list operations, the future of this feature is unclear.
 Mixin "injection"
 -----------------
 
-A mixin defined like this:
+A mixin defined like this::
 
     @mixin foo(...) {
         // ...