Simplify and re-org the intro section

docs/index.rst

@@ -5,7 +5,7 @@
 
 tractor
 =======
-An async-native "`actor model`_" built on trio_ and multiprocessing_.
+A `structured concurrent`_, async-native "`actor model`_" built on trio_ and multiprocessing_.
 
 .. toctree::
    :maxdepth: 2
@@ -22,10 +22,12 @@ An async-native "`actor model`_" built on trio_ and multiprocessing_.
 .. _cancellation: https://trio.readthedocs.io/en/latest/reference-core.html#cancellation-and-timeouts
 .. _channels: https://en.wikipedia.org/wiki/Channel_(programming)
 .. _chaos engineering: http://principlesofchaos.org/
+.. _structured concurrent: https://trio.discourse.group/t/concise-definition-of-structured-concurrency/228
 
 
 ``tractor`` is an attempt to bring trionic_ `structured concurrency`_ to
-distributed multi-core Python.
+distributed multi-core Python; it aims to be the Python multi-processing
+framework *you always wanted*.
 
 ``tractor`` lets you spawn ``trio`` *"actors"*: processes which each run
 a ``trio`` scheduled task tree (also known as an `async sandwich`_).
@@ -34,6 +36,53 @@ sharing any state. This model allows for highly distributed software
 architecture which works just as well on multiple cores as it does over
 many hosts.
 
+The first step to grok ``tractor`` is to get the basics of ``trio`` down.
+A great place to start is the `trio docs`_ and this `blog post`_.
+
+.. _messages: https://en.wikipedia.org/wiki/Message_passing
+.. _trio docs: https://trio.readthedocs.io/en/latest/
+.. _blog post: https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/
+.. _structured concurrency: https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/
+.. _3 axioms: https://en.wikipedia.org/wiki/Actor_model#Fundamental_concepts
+.. _unrequirements: https://en.wikipedia.org/wiki/Actor_model#Direct_communication_and_asynchrony
+.. _async generators: https://www.python.org/dev/peps/pep-0525/
+
+
+Install
+-------
+No PyPi release yet!
+
+::
+
+    pip install git+git://github.com/goodboy/tractor.git
+
+
+Feel like saying hi?
+--------------------
+This project is very much coupled to the ongoing development of
+``trio`` (i.e. ``tractor`` gets all its ideas from that brilliant
+community). If you want to help, have suggestions or just want to
+say hi, please feel free to ping me on the `trio gitter channel`_!
+
+.. _trio gitter channel: https://gitter.im/python-trio/general
+
+
+.. contents::
+
+
+Philosophy
+----------
+Our tenets non-comprehensively include:
+
+- strict adherence to the `concept-in-progress`_ of *structured concurrency*
+- no spawning of processes *willy-nilly*; causality_ is paramount!
+- (remote) errors `always propagate`_ back to the parent supervisor
+- verbatim support for ``trio``'s cancellation_ system
+- `shared nothing architecture`_
+- no use of *proxy* objects or shared references between processes
+- an immersive debugging experience
+- anti-fragility through `chaos engineering`_
+
 ``tractor`` is an actor-model-*like* system in the sense that it adheres
 to the `3 axioms`_ but does not (yet) fulfil all "unrequirements_" in
 practise. It is an experiment in applying `structured concurrency`_
@@ -50,37 +99,6 @@ definitely not required). There is first class support for inter-actor
 streaming using `async generators`_ and ongoing work toward a functional
 reactive style for IPC.
 
-The first step to grok ``tractor`` is to get the basics of ``trio`` down.
-A great place to start is the `trio docs`_ and this `blog post`_.
-
-.. _messages: https://en.wikipedia.org/wiki/Message_passing
-.. _trio docs: https://trio.readthedocs.io/en/latest/
-.. _blog post: https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/
-.. _structured concurrency: https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/
-.. _3 axioms: https://en.wikipedia.org/wiki/Actor_model#Fundamental_concepts
-.. _unrequirements: https://en.wikipedia.org/wiki/Actor_model#Direct_communication_and_asynchrony
-.. _async generators: https://www.python.org/dev/peps/pep-0525/
-
-
-.. contents::
-
-
-Philosophy
-----------
-``tractor`` aims to be the Python multi-processing framework *you always wanted*.
-
-Its tenets non-comprehensively include:
-
-- strict adherence to the `concept-in-progress`_ of *structured concurrency*
-- no spawning of processes *willy-nilly*; causality_ is paramount!
-- (remote) errors `always propagate`_ back to the parent supervisor
-- verbatim support for ``trio``'s cancellation_ system
-- `shared nothing architecture`_
-- no use of *proxy* objects or shared references between processes
-- an immersive debugging experience
-- anti-fragility through `chaos engineering`_
-
-
 .. warning:: ``tractor`` is in alpha-alpha and is expected to change rapidly!
     Expect nothing to be set in stone. Your ideas about where it should go
     are greatly appreciated!
@@ -88,15 +106,6 @@ Its tenets non-comprehensively include:
 .. _concept-in-progress: https://trio.discourse.group/t/structured-concurrency-kickoff/55
 
 
-Install
--------
-No PyPi release yet!
-
-::
-
-    pip install git+git://github.com/goodboy/tractor.git
-
-
 Examples
 --------
 Note, if you are on Windows please be sure to see the gotchas section
@@ -619,13 +628,3 @@ Stuff I'd like to see ``tractor`` do real soon:
 .. _asyncitertools: https://github.com/vodik/asyncitertools
 .. _pdb++: https://github.com/antocuni/pdb
 .. _capability-based security: https://en.wikipedia.org/wiki/Capability-based_security
-
-
-Feel like saying hi?
---------------------
-This project is very much coupled to the ongoing development of
-``trio`` (i.e. ``tractor`` gets all its ideas from that brilliant
-community). If you want to help, have suggestions or just want to
-say hi, please feel free to ping me on the `trio gitter channel`_!
-
-.. _trio gitter channel: https://gitter.im/python-trio/general