Polish READMEs and starting screen

README.md

@@ -1,7 +1,7 @@
-Vis-à-vis web-viewer for scientific plots in chemistry and physics
+Web-viewer for plots in materials science, chemistry, and physics
 ==========
 
-Standalone and self-contained HTML5 widget, based on the D3 and Plotly libs, written in [$mol](https://github.com/hyoo-ru) hyper-reactive micromodular UI framework.
+**Vis-à-vis** is a standalone and self-contained HTML5 widget, written in the [$mol](https://github.com/hyoo-ru) framework and based on the D3 and Plotly libs.
 
 Supports the following plot types (see `examples` folder):
 
@@ -29,7 +29,7 @@ All the plot types being visualized must conform the spec:
 }
 ```
 
-As a part of the [MPDS desktop GUI](https://github.com/mpds-io/ermac), being used in an **iframe**, tries to access the `window.parent` and `window.parent.wmgui`, as well as the methods therein.
+**Vis-à-vis** exists in two realizations: standalone application called `app` and embeddable web component called `plot`.
 
 
 ### Requirements
@@ -40,41 +40,49 @@ As a part of the [MPDS desktop GUI](https://github.com/mpds-io/ermac), being use
 
 ## Installation and development
 
-Make empty directory for MAM dev environment:
+Note, that, unlike many other frontend frameworks, `$mol` provides the same single environment for all its projects. That is, all your `$mol`-based code lives inside some directory `$MOL_HOME`. So if you don't have `$MOL_HOME`, create it and navigate there:
 
 ```bash
-mkdir mam && cd mam
+mkdir $MOL_HOME && cd $MOL_HOME
 ```
 
-Start dev server:
+Run `$mol` MAM server (MAM stands for the `$mol` abstract modules) inside your `$MOL_HOME`:
 
 ```bash
 npm exec mam@latest
 ```
 
-Use this link to build app on the fly and run it with hot reload support: [http://localhost:9080/mpds/visavis/app/-/test.html](http://localhost:9080/mpds/visavis/app/-/test.html)
+Use a link to run the standalone **Vis-à-vis** application `app` with the hot reload support: http://localhost:9080/mpds/visavis/app/-/test.html
+
 
 ## Building
 
-Build standalone application at `mpds/visavis/app/-`:
+Build the standalone application `app` at `mpds/visavis/app/-` using:
 
 ```bash
 npm exec mam@latest mpds/visavis/app
 ```
-[Build mpds-visavis-plot Web Component](https://github.com/mpds-io/visavis/blob/master/plot/readme.md)
+
+Build the embeddable web component `plot` at `mpds/visavis/plot/-/web.js` using:
+
+```bash
+npm exec mam@latest mpds/visavis/plot
+```
+
+See also the [mpds-visavis-plot web component description](https://github.com/mpds-io/visavis/blob/master/plot/README.md).
 
 
 ## Sources file layout
 
 `app` - the main `$mol` app
 
-`elements` - elemental properties and constants
+`elements` - **Vis-à-vis** elemental properties and constants
 
-`examples` - supported data samples, see also **plots** on [MPDS platform](https://mpds.io/#plot/matrix/inquiry/formulae=TiO2)
+`examples` - **Vis-à-vis** supported data samples, see also **plots** on [MPDS platform](https://mpds.io/#plot/matrix/inquiry/formulae=TiO2)
 
-`lib` - external libraries
+`lib` - external libraries bundled
 
-`plot` - plot types implementations
+`plot` - plot types + embeddable web component implementation
 
 `plotly` - Plotly library embedding description
 

app/app.view.tree

@@ -46,10 +46,10 @@ $mpds_visavis_app $mol_book2
 								accept \application/json
 								files? <=> files_read? null
 					<= Examples_open $mol_link
-						title \Or browse examples
+						title \or browse examples
 						arg * section \examples
 		<= Menu $mol_page
-			title \Vis-a-vis
+			title \Vis-à-vis
 			tools /
 				<= History_link $mol_link
 					title @ \Uploads
@@ -71,7 +71,7 @@ $mpds_visavis_app $mol_book2
 							Sub <= History_upload $mol_button_minor
 								sub /
 									<= History_upload_label $mol_paragraph
-										title \Add new (choose a plot file in JSON format)
+										title \Choose a plot JSON file
 									<= History_upload_icon $mol_icon_upload
 									<= History_upload_native $mol_button_open_native
 										accept \application/json

plot/readme.md → plot/README.md

@@ -1,38 +1,45 @@
-# $mpds_visavis_plot
+# `$mpds_visavis_plot`
+
+This is the plot displaying component, which can be used as a [web component](https://developer.mozilla.org/en-US/docs/Web/Web_Components).
 
-Plot displaying component.
-Can be used as [Web Component](https://developer.mozilla.org/en-US/docs/Web/Web_Components).
 
 ## Building
 
 ```bash
 npm exec mam@latest mpds/visavis/plot
 ```
-The module bundle will be at `mpds/visavis/plot/-/web.js`
 
-## Web Component usage example
+The module bundle will be in `mpds/visavis/plot/-/web.js`
+
+
+## Web component usage example
+
 When you import the module, the web component is automatically registered, so you can use the html tag:
+
 ```html
 <mpds-visavis-plot></mpds-visavis-plot>
 ```
-Use `view` property of the DOM element to control `$mpds_visavis_plot` $mol component instance:
+
+Use `view` property of the DOM element to control the `$mpds_visavis_plot` component instance:
+
 ```js
 const visavis_plot = document.getElementsByTagName( 'mpds-visavis-plot' )[ 0 ].view
 
-visavis_plot.json_request( 'https://jsonplaceholder.typicode.com/todos/1' )
+visavis_plot.json_request( 'https://raw.githubusercontent.com/mpds-io/visavis/master/examples/bar_sci_literature.json' )
 
-visavis_plot.notify = ( msg )=> alert( msg )
+visavis_plot.notify = ( msg ) => alert( msg )
 ```
 
-## Properties
+
+## API
 
 **`json_request( next?: string ) : string`**
 
-Request url to get json (plot data)
+Request url to get JSON (plot data)
 
 **`notify( msg: string ) : void`**
 
-Called inside component for display notification
+Called inside the component for display notification
 
 **`matrix_click( { cmt: string } ) : void`**