Merge pull request #124 from willingc/walkthrough-services

Edit extensions and services doc in tutorial

tutorial/extensions.md

@@ -1,21 +1,28 @@
 # Plugins
 
-JupyterLab can be extended in two ways: via top level application plugins
-or document widget extensions.  Application plugins extend the 
-functionality of JupyterLab itself and are the focus of this tutorial. 
-Document widget extensions extend the functionality of document widgets added 
-to the application and are covered in the Documents tutorial.
+JupyterLab can be extended in two ways via:
 
-A JupyterLab application is comprised of Services and Extensions, as well as a 
-core [Application](https://github.com/phosphorjs/phosphide/blob/master/src/core/application.ts) object.
+- **application plugins (top level):** Application plugins extend the
+  functionality of JupyterLab itself, and **this tutorial focuses on them.**
+- document widget extensions (lower level): Document widget extensions extend
+  the functionality of document widgets added to the application, and we cover
+  them in the "Documents" tutorial.
 
-A full example is contained [here](https://github.com/jupyter/jupyterlab/tree/master/examples/lab).
+A JupyterLab application is comprised of several parts:
+- Service Providers
+- Extensions
+- a core [Application](https://github.com/phosphorjs/phosphide/blob/master/src/core/application.ts) object
 
-## [Services](https://github.com/phosphorjs/phosphide/blob/master/src/core/serviceregistry.ts) 
-A service provider is used by extensions to add functionality to the
-application. 
-- Service providers can require other services.
-- Services are activated when they are needed by other services or extensions.
+A full example of an application is contained [here](https://github.com/jupyter/jupyterlab/tree/master/examples/lab).
+Looking at the `index.js` file, you can see the extensions and service providers
+used in the tutorial example.
+
+## [Services](https://github.com/phosphorjs/phosphide/blob/master/src/core/serviceregistry.ts)
+A service provider adds a core functionality to the application:
+- A service provider does not use the Application object.
+- A Service provider can require other services for operation.
+- Extensions can use providers to offer additional functionality to the user.
+- A Service provider is activated when it is needed by other services or extensions.
 
 The default services providers in the JupyterLab application include:
 - [Services](http://jupyter.org/jupyterlab/modules/_services_plugin_.html#servicesprovider) - An application-specific interface to `jupyter-js-services`.
@@ -23,10 +30,10 @@ The default services providers in the JupyterLab application include:
 - [Document Registry](http://jupyter.org/jupyterlab/modules/_docregistry_plugin_.html#docregistryprovider) - Used to add functionality around widgets backed by files.
 - [Clipboard](http://jupyter.org/jupyterlab/modules/_clipboard_plugin_.html#clipboardprovider) - The application-wide clipboard for arbitrary MIME data.
 
-## [Extensions](https://github.com/phosphorjs/phosphide/blob/master/src/core/extensionregistry.ts#L19) 
-Extensions use the Application object and optionally other services to provide 
-functionality to the application. 
-- Extensions provided to the application on startup are activated immediately. 
+## [Extensions](https://github.com/phosphorjs/phosphide/blob/master/src/core/extensionregistry.ts#L19)
+Extensions use the Application object and optionally other services to provide
+functionality to the application.
+- Extensions provided to the application on startup are activated immediately.
 - Extensions can also be activated explicitly at runtime through the Application [instance](https://github.com/phosphorjs/phosphide/blob/master/src/core/application.ts#L71).
 
 The default extensions in the application include:
@@ -43,21 +50,21 @@ interactive kernel console sessions.
 
 ## Command Palette
 
-The command palette is a part of the application object and is intended to
+The command palette, as a part of the application object, is intended to
 be the primary way to display and execute commands in the application.
-Many of the default extensions add commands to the command palette for actions
-such as executing a cell on a notebook or launching a new terminal instance.
+Many of the default extensions add new commands to the command palette to provide
+actions such as executing a notebook cell or launching a new terminal instance.
 
 
 ## Phosphor
-Phosphor is used as the underlying architecture of JupyterLab and provides 
+The Phosphor library is used as the underlying architecture of JupyterLab and provides 
 many of the low level primitives and widget structure used in the application.
-It provides a rich set of widgets for developing desktop-like applications
+Phosphor provides a rich set of widgets for developing desktop-like applications
 in the browser, as well as patterns and objects for writing clean, 
-well-abstracted code.  The widgets in the application are primarily Phosphor 
-widgets, and Phosphor concepts like message passing and signals are used
-throughout.  Phosphor messages are a many-to-one interaction that allows
-information like resize events to flow through the widget heirarchy in 
-the application.  Phosphor signals are a one-to-many interaction that allow
+well-abstracted code.  The widgets in the application are primarily **Phosphor 
+widgets**, and Phosphor concepts, like message passing and signals, are used
+throughout.  **Phosphor messages** are a *many-to-one* interaction that allows
+information like resize events to flow through the widget hierarchy in 
+the application.  **Phosphor signals** are a *one-to-many* interaction that allow
 listeners to react to changes in an observed object.