Edit file formats docs.

docs/source/user/file_formats.md

@@ -1,43 +1,48 @@
-
 # File and output formats
 
 ## Overview
 
-When working with code and data, you will encounter data and files in a wide
-variety of formats. JupyterLab provides a unified architecture for viewing and editing
-data. This model applies whether the data is in a file or is provided by a
-kernel as rich output in a notebook or code console.
+JupyterLab provides a unified architecture for viewing and editing data in a
+wide variety of formats. This model applies whether the data is in a file or is
+provided by a kernel as rich cell output in a notebook or code console.
 
 For files, the data format is detected by the extension of the file. A single
 file extension may have multiple editors or viewers registered. For example a
 Markdown file (`.md`) can be edited in the file editor or rendered and displayed
-as HTML.
-
-You can open different editors and viewers for a file by right-clicking on
-the filename in the file browser and using the "Open With..." submenu:
+as HTML. You can open different editors and viewers for a file by right-clicking
+on the filename in the file browser and using the "Open With..." submenu:
 
 [screenshot]
 
-To use these different data formats as output in a notebook or code console,
-you can use the relevant display API for the kernel you are using. For example,
-the IPython kernel provides a `display` function that takes a `dict` of keys
-(MIME types) and values (MIME data):
+To use these different data formats as output in a notebook or code console, you
+can use the relevant display API for the kernel you are using. For example, the
+IPython kernel provides a variety of convenience classes for displaying rich output:
 
 ```python
-from IPython.display import display
-display({'text/html': '<h1>Hello World</h1>'}, raw=True)
+from IPython.display import display, HTML
+display(HTML('<h1>Hello World</h1>'))
 ```
 
-Running this code will display the HTML in the output of the notebook or code
-console:
+Running this code will display the HTML in the output of a notebook or code
+console cell:
 
 [screenshot]
 
+The IPython display function can also construct a raw rich output message from a
+dictionary of keys (MIME types) and values (MIME data):
+
+```python
+from IPython.display import display
+display({'text/html': '<h1>Hello World</h1>', 'text/plain': 'Hello World'}, raw=True)
+```
+
 Other Jupyter kernels offer similar APIs.
 
-## Markdown
+## Formats
 
-* File format: `.md`
+### Markdown
+
+* File extension: `.md`
 * MIME type: `text/markdown`
 
 Markdown is a simple and popular markup language used for text cells in the
@@ -45,69 +50,56 @@ Jupyter Notebook.
 
 Markdown documents can be edited as text files or rendered inline:
 
-[animation]
-
-The markdown syntax supported in this mode is the same as that in the Jupyter
-Notebook (LaTeX equations work). As seen in the animation, edits to the Markdown
-source are immediately reflected in the rendered version.
-
-## Images
+[animation showing opening a markdown document editor and renderer side-by-side, and changes in the editor being reflected in the renderer]
 
-* File format: `.png`, `.jpeg`, `.gif`
-* MIME type: `image/png`, `image/jpeg`, `image/gif`
+The Markdown syntax supported in this mode is the same syntax used in the
+Jupyter Notebook (for example, LaTeX equations work). As seen in the animation,
+edits to the Markdown source are immediately reflected in the rendered version.
 
-JupyterLab supports image data as files and output in the above formats. In the image file viewer, you can use keyboard shortcuts such as `+` and `-` to zoom the image and `0` to reset the zoom level.
+### Images
 
-## HTML
+* File extensions: `.bmp`, `.gif`, `.jpeg`, `.jpg`, `.png`, `.svg`
+* MIME types: `image/bmp`, `image/gif`, `image/jpeg`, `image/png`, `image/svg+xml`
 
-* File format: `.html`
-* MIME type: `text/html`
+JupyterLab supports image data in cell output and as files in the above formats. In the image file viewer, you can use keyboard shortcuts such as `+` and `-` to zoom the image and `0` to reset the zoom level. To edit an SVG image as a text file, right-click on the SVG filename in the file browser and select the “Editor” item in the “Open With…” submenu:
 
-JupyterLab supports rendered HTML in output. HTML files can be edited as text
-files in the file editor.
+[animation]
 
-## SVG
+### HTML
 
-* File format: `.svg`
-* MIME type: `image/svg+xml`
+* File extension: `.html`
+* MIME type: `text/html`
 
-JupyterLab will render Scalable Vector Graphics (SVG) in files and output. SVG
-files can slso be edited as text files in the file editor.
+JupyterLab supports rendering HTML in cell output and editing HTML files as text in the file editor.
 
-## LaTeX
+### LaTeX
 
-* File format: `.tex`
+* File extension: `.tex`
 * MIME type: `text/latex`
 
-JupyterLab will render LaTeX questions in output, and LaTeX files (`.tex`) can
-be edited as text files in the file editor.
+JupyterLab supports rendering LaTeX in cell output and editing LaTeX files as text in the file editor.
 
-## JSON
+### JSON
 
-* File format: `.json`
-* MIME type: `application/binary+json`
+* File extension: `.json`
+* MIME type: `application/json`
 
-JavaScript Object Notation (JSON) files are common in data science.
+JavaScript Object Notation (JSON) files are common in data science. JupyterLab supports displaying JSON data in cell output or viewing a JSON file using a searchable tree view:
 
-The default viewer for JSON files is a searchable tree view:
+[animation showing both rendering JSON as cell output and viewing a JSON file]
 
-[animation]
-
-To edit the JSON as a text file, right-click on the file in the file browser and
-select the “Editor” item in the “Open With…” submenu:
+To edit the JSON as a text file, right-click on the filename in the file browser
+and select the “Editor” item in the “Open With…” submenu:
 
 [animation]
 
-## CSV
+### CSV
 
-* File format: `.csv`
+* File extension: `.csv`
 * MIME type: None
 
-Files with rows of Comma-Separated Values (with a `.csv` extension) are a common
-format for tabular data.
-
-The default viewer for CSV files in JupyterLab is a high performance data grid
-viewer:
+Files with rows of comma-separated values (CSV files) are a common
+format for tabular data. The default viewer for CSV files in JupyterLab is a high-performance data grid viewer:
 
 [animation]
 
@@ -116,35 +108,32 @@ and select the “Editor” item in the “Open With…” submenu:
 
 [animation]
 
-## PDF
+### PDF
 
-* File format: `.pdf`
+* File extension: `.pdf`
 * MIME type: `application/pdf`
 
-PDF files are a common standard file format for
-documents. To view a PDF file in JupyterLab, double-click on the file in the
-file browser:
+PDF is a common standard file format for documents. To view a PDF file in
+JupyterLab, double-click on the file in the file browser:
 
 [animation]
 
-
-## Vega/Vega-Lite
+### Vega/Vega-Lite
 
 Vega:
 
-* File format: `.vg`, `.vg.json`
+* File extension: `.vg`, `.vg.json`
 * MIME type: `application/vnd.vega.v2+json`
 
 Vega-Lite:
 
-* File format: `.vl`, `.vl.json`
+* File extension: `.vl`, `.vl.json`
 * MIME type: `application/vnd.vegalite.v1+json`
 
 Vega and Vega-Lite are declarative visualization grammars that allow
 visualizations to be encoded as JSON data. For more information, see the
-documentation of Vega or Vega-Lite. JupyterLab has built-in rendering support
-for Vega 2.x and Vega-Lite 1.x data. This support works for both files and
-output in the Notebook and Code Console.
+documentation of Vega or Vega-Lite. JupyterLab supports rendering
+Vega 2.x and Vega-Lite 1.x data in files and cell output.
 
 Vega-Lite 1.x files, with a `.vl` or `.vl.json` file extension, can be opened by
 double-clicking the file in the File Browser:
@@ -166,7 +155,7 @@ The same workflow also works for Vega 2.x files, with a `.vg` or `.vg.json` file
 extension.
 
 Output support for Vega/Vega-Lite in a notebook or code console is provided
-through third party libraries such as Altair (Python), the vegalite R package,
+through third-party libraries such as Altair (Python), the vegalite R package,
 or Vegas (Scala/Spark).
 
 [screenshot]
@@ -174,9 +163,9 @@ or Vegas (Scala/Spark).
 A JupyterLab extension that supports Vega 3.x and Vega-Lite 2.x can be found
 [here](https://github.com/jupyterlab/jupyter-renderers).
 
-## Virtual DOM
+### Virtual DOM
 
-* File format: `.vdom`, `.json`
+* File extension: `.vdom`, `.json`
 * MIME type: `application/vdom.v1+json`
 
 Virtual DOM libraries such as [react.js](https://reactjs.org/) have greatly
@@ -186,7 +175,7 @@ project, which collaborates closely with Project Jupyter, has created a
 JupyterLab can render this data using react.js. This works for both VDOM files
 with the `.vdom` extension, or within notebook output.
 
-Here is an example of a `.vdom` files being edited and rendered interactively:
+Here is an example of a `.vdom` file being edited and rendered interactively:
 
 [animation]