[cordova-mobile-spec] 01/04: start work on making READMEs readable

[ja...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

janpio pushed a commit to branch janpio-cleanup_readmes
in repository https://gitbox.apache.org/repos/asf/cordova-mobile-spec.git

commit d68d48de54d2504d826e8f9b55205033e85effb4
Author: Jan Piotrowski <pi...@gmail.com>
AuthorDate: Fri Nov 23 22:58:22 2018 +0100

    start work on making READMEs readable
---
 createmobilespec/README.md | 65 ++++++++++++++++++++++++----------------------
 1 file changed, 34 insertions(+), 31 deletions(-)

diff --git a/createmobilespec/README.md b/createmobilespec/README.md
index 5d41e2e..84b0c34 100644
--- a/createmobilespec/README.md
+++ b/createmobilespec/README.md
@@ -23,15 +23,11 @@
 
 `createmobilespec.js` is a script for creating a test app that has:
 
-* the **mobile-spec** code from the local `cordova-mobile-spec` git repo
-* a `cordova.js` file that is freshly built from the local `cordova-js`
-  git repo
-* the platform (e.g., **Android**) from the local platform git repo (e.g.,
-  `cordova-android`)
-* all the plugins from the local plugin repos (e.g., cordova-plugin-device)
-* it was built using the local `cordova-cli` and `cordova-plugman` git repos
-
-(Many places in this document that say *git repo* may also mean *npm repository*.)
+* local `cordova-mobile-spec`
+* a `cordova.js` file that is freshly built from the local `cordova-js` folder
+* the platform (e.g. Android) from the local platform folder (e.g. `cordova-android`)
+* all the plugins from the local plugin folders (e.g. `cordova-plugin-device`)
+* it was built using the local `cordova-cli` and `cordova-plugman` folders
 
 In other words, it is a great way to test your local development efforts.
 
@@ -40,45 +36,52 @@ globally-installed npm module, a way to use the platform's `cordova.js` file
 instead of building it from the local `cordova-js` git repo,
 and a way to use the platform-centered workflow instead of the CLI.
 
-### Requirements
-
-See the [README.md](../README.md) in the parent directory
-[cordova-mobile-spec](..).
+## Requirements and Preparation
 
-Each git repo should be checked out to the state or edited with the content
-that you want to test. Be **aware** that it **will not download** missing 
-plugin content from the [plugin registry](http://plugins.cordova.io) nor does 
-it fetch platforms from the npm repository.
+Repositories required:
 
-(Except, I think it does...)
+- All repositories must be checked out as peers to each other.
+- `cordova-cli` 
+  (Install pre-requisites by running `npm install` inside of cordova-cli).
+- `cordova-js`  
+- All plugins.
+- Platforms to test  
+  (e.g., `cordova-android`, `cordova-ios` or `cordova-windows`).
+- `cordova-mobile-spec`
+  (Install pre-requisites by running `npm install` inside of
+  [createmobilespec](createmobilespec)).
 
 Before running `createmobilespec.js` for the first time, run `npm install`
 from within the [createmobilespec](.) directory to install the requisite
 third-party **Node** modules. This should be a one-time activity,
 unless there is a change in the pre-reqs.
 
-### Running
+Each git repo should be checked out to the state or edited with the content
+that you want to test.
 
-The `createmobilespec.js` script needs to be invoked from a specific
-current working directory:
-the one where you have all the git repos cloned.
-So if you were to do an `ls` in that directory,
-you should see all the git repos including `cordova-mobile-spec`.
-Thus an invocation should look like:
+(Be **aware** that it **will not download** missing 
+plugin content from the [plugin registry](http://plugins.cordova.io) nor does 
+it fetch platforms from the npm repository. (Except, I think it does...))
+
+## Usage
+
+The `createmobilespec.js` script needs to be invoked from a specific current working directory: the one where you have all the git repos cloned.
+
+So if you were to do an `ls` in that directory, you should see all the git repos including `cordova-mobile-spec`. Thus an invocation should look like:
 
     cordova-mobile-spec/createmobilespec/createmobilespec.js
 
-To see the options available in the script,
-run it with the `-h` option to print the online help.
+To see the options available in the script, run it with the `-h` option to print the online help.
 
-After you have run the script to create the app,
-then you can run the app on a device or simulator,
-using the standard method for that platform(s).
-For example on **Android**:
+    cordova-mobile-spec/createmobilespec/createmobilespec.js -h
+
+After you have run the script to create the app, you can run the app on a device or simulator, using the standard method for that platform(s). For example on **Android**:
 
     cd mobilespec
     ./cordova run android
 
+### Quirks and Issues
+
 Some known quirks and issues:
 
 * `npm install` inside `cordova-js` is needed to resolve a local grunt issue


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org