From 8b7d31159506d1708c18704f4c8bda69dddcfdb8 Mon Sep 17 00:00:00 2001
From: Paul Sokolovsky <pfalcon@users.sourceforge.net>
Date: Sat, 1 Jul 2017 22:09:40 +0300
Subject: [PATCH] reference/index: Rewrite introduction paragraph to avoid
 confusion.

The old intro talked about "differences", but there were hardly any
sections describing differences, mostly MicroPython specific features.
On the other hand, we now have real "differences" chapter, though it's
mostly concerned with stdlib differences.

So, try to avoid confusion by changing wording and linking to the other
chapters and contrasting them with what is described in "MicroPython
language".
---
 docs/differences/index_template.txt |  2 ++
 docs/library/index.rst              |  2 ++
 docs/reference/index.rst            | 19 +++++++++++++------
 3 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/docs/differences/index_template.txt b/docs/differences/index_template.txt
index 772a7104a2..eb8b3ba640 100644
--- a/docs/differences/index_template.txt
+++ b/docs/differences/index_template.txt
@@ -1,3 +1,5 @@
+.. _cpython_diffs:
+
 MicroPython differences from CPython
 ====================================
 
diff --git a/docs/library/index.rst b/docs/library/index.rst
index e0260b7012..8a59628e2d 100644
--- a/docs/library/index.rst
+++ b/docs/library/index.rst
@@ -1,3 +1,5 @@
+.. _micropython_lib:
+
 MicroPython libraries
 =====================
 
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
index 7a85fc5cf3..63d9941b1f 100644
--- a/docs/reference/index.rst
+++ b/docs/reference/index.rst
@@ -1,13 +1,20 @@
 The MicroPython language
 ========================
 
-MicroPython aims to implement the Python 3.4 standard, and most of
-the features of MicroPython are identical to those described by the
-documentation at
-`docs.python.org <https://docs.python.org/3.4/reference/index.html>`_.
+MicroPython aims to implement the Python 3.4 standard (with selected
+features from later versions) with respect to language syntax, and most
+of the features of MicroPython are identical to those described by the
+"Language Reference" documentation at
+`docs.python.org <https://docs.python.org/3/reference/index.html>`_.
 
-Differences to standard Python as well as additional features of
-MicroPython are described in the sections here.
+The MicroPython standard library is described in the
+:ref:`corresponding chapter <micropython_lib>`. The :ref:`cpython_diffs`
+chapter describes differences between MicroPython and CPython (which
+mostly concern standard library and types, but also some language-level
+features).
+
+This chapter describes features and peculiarities of MicroPython
+implementation and the best practices to use them.
 
 .. toctree::
    :maxdepth: 1