Tiny CLI docs improvements (#402)
Co-authored-by: Tim Brust <github@timbrust.de>
Co-authored-by: Erisu <ellis.bryan@gmail.com>
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 21a93d7..b092f51 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -25,13 +25,13 @@
There are multiple ways to contribute: report bugs, improve the docs, and
contribute code.
-
+
For instructions on this, start with the
[contribution overview](http://cordova.apache.org/contribute/).
The details are explained there, but the important items are:
- - Check for Github issues that corresponds to your contribution and link or create them if necessary.
- - Run the tests so your patch doesn't break existing functionality.
+
+- Check for Github issues that corresponds to your contribution and link or create them if necessary.
+- Run the tests so your patch doesn't break existing functionality.
We look forward to your contributions!
-
diff --git a/README.md b/README.md
index 4efcf04..bcc031d 100644
--- a/README.md
+++ b/README.md
@@ -26,23 +26,27 @@
[](https://github.com/apache/cordova-cli/actions?query=branch%3Amaster)
[](https://codecov.io/github/apache/cordova-cli?branch=master)
-> The command line tool to build, deploy and manage [Cordova](http://cordova.apache.org)-based applications.
+> The command line tool to build, deploy and manage [Cordova](https://cordova.apache.org)-based applications.
-[Apache Cordova](http://cordova.apache.org) allows for building native mobile applications using HTML, CSS and JavaScript.
+[Apache Cordova](https://cordova.apache.org) allows for building native mobile applications using HTML, CSS and JavaScript.
This tool helps with management of multi-platform Cordova applications as well as Cordova plugin integration.
-# Installation
-In your command-line on Windows:
-```bash
+## Installation
+
+In your command-line on Windows:
+
+```bash
c:\> npm install -g cordova
-```
-
+```
+
In your terminal on Mac OS X/Linux:
-```bash
+
+```bash
$sudo npm install -g cordova
```
-# Creating a new Cordova project
+## Creating a new Cordova project
+
This simple example demonstrates how Cordova CLI can be used to create a `myApp` project with the `camera` plugin and run it for `android` platform:
```bash
@@ -50,23 +54,25 @@
cd myApp
cordova plugin add cordova-plugin-camera --save
cordova platform add android --save
- cordova requirements android
+ cordova requirements android
cordova build android --verbose
cordova run android
```
-# Docs
+## Docs
+
- [Overview of Cordova]
- [Create your first Cordova app] guide
-- [Full reference docs for Cordova CLI][Reference docs] has details of commands to add platforms, add plugins, build, package, and sign your HTML, JS apps.
+- [Full reference docs for Cordova CLI][Reference docs] has details of commands to add platforms, add plugins, build, package, and sign your HTML, JS apps.
- Cordova allows you to build apps for a number of platforms. Learn more about our [Supported platforms].
- [Project directory structure] documents the details of the directory structure created by Cordova CLI.
-# Contributing
-Cordova is an open source Apache project and contributors are needed to keep this project moving forward. Learn more on
-[how to contribute on our website][contribute].
+## Contributing
-# Reporting Issues
+Cordova is an open source Apache project and contributors are needed to keep this project moving forward. Learn more on
+[how to contribute on our website][contribute].
+
+## Reporting Issues
If you find issues with the Cordova CLI, please follow our guidelines for [reporting issues]. Please bear in mind that most of `cordova-cli`'s functionality is implemented in [cordova-lib], so that could be the place to report your issue.
Platform-specific issues should be reported in the relevant repositories, such as [cordova-android] and [cordova-ios].
diff --git a/doc/readme.md b/doc/readme.md
index a64093e..34a52dc 100644
--- a/doc/readme.md
+++ b/doc/readme.md
@@ -38,10 +38,10 @@
| Command | Description
|----------|--------------
-| create | Create a project
-| help `<command>` | Get help for a command
-| telemetry | Turn telemetry collection on or off
-| config | Set, get, delete, edit, and list global cordova options
+| `create` | Create a project
+| `help <command>` | Get help for a command
+| `telemetry` | Turn telemetry collection on or off
+| `config` | Set, get, delete, edit, and list global cordova options
## Project Command List
@@ -49,15 +49,16 @@
| Command | Description
|--------------|--------------
-| info | Generate project information
-| requirements | Checks and print out all the installation requirements for platforms specified
-| platform | Manage project platforms
-| plugin | Manage project plugins
-| prepare | Copy files into platform(s) for building
-| compile | Build platform(s)
-| clean | Cleanup project from build artifacts
-| run | Run project (including prepare && compile)
-| serve | Run project with a local webserver (including prepare)
+| `info` | Generate project information
+| `requirements` | Checks and print out all the installation requirements for platforms specified
+| `platform` | Manage project platforms
+| `plugin` | Manage project plugins
+| `prepare` | Copy files into platform(s) for building
+| `compile` | Compile project for platform(s)
+| `build` | Build project for platform(s) (`prepare` + `compile`)
+| `clean` | Cleanup project from build artifacts
+| `run` | Run project (including prepare && compile)
+| `serve` | Run project with a local webserver (including prepare)
## Common options
@@ -351,7 +352,7 @@
cordova plugin ls
### Conflicting plugins
-Conflicting plugins may occur when adding plugins that use `edit-config` tags in their plugin.xml file. `edit-config` allows plugins to add or replace attributes of XML elements.
+Conflicting plugins may occur when adding plugins that use `edit-config` tags in their plugin.xml file. `edit-config` allows plugins to add or replace attributes of XML elements.
This feature can cause issues with the application if more than one plugin tries to modify the same XML element. Conflict detection has been implemented to prevent plugins from being added so one plugin doesn't try to overwrite another plugin's `edit-config` changes. An error will be thrown when a conflict in `edit-config` has been found and the plugin won't be added. The error message will mention that all conflicts must be resolved before the plugin can be added. One option to resolving the `edit-config` conflict is to make changes to the affected plugins' plugin.xml so that they do not modify the same XML element. The other option is to use the `--force` flag to force add the plugin. This option should be used with caution as it ignores the conflict detection and will overwrite all conflicts it has with other plugins, thus may leave the other plugins in a bad state.
@@ -374,7 +375,7 @@
| Option | Description
|------------|------------------
-| `<platform> [..]` | Platform name(s) to prepare. If not specified, all platforms are built.
+| `<platform> [..]` | Platform name(s) to prepare. If not specified, all platforms are prepared.
## cordova compile command
@@ -386,9 +387,9 @@
### Syntax
```bash
-cordova build [<platform> [...]]
- [--debug|--release]
- [--device|--emulator|--target=<targetName>]
+cordova compile [<platform> [...]]
+ [--debug | --release]
+ [--device | --emulator | --target=<targetName>]
[--buildConfig=<configfile>]
[-- <platformOpts>]
```
@@ -404,8 +405,8 @@
```bash
cordova build [<platform> [...]]
- [--debug|--release]
- [--device|--emulator]
+ [--debug | --release]
+ [--device | --emulator]
[--buildConfig=<configfile>]
[-- <platformOpts>]
```
@@ -416,7 +417,7 @@
| --debug | Perform a debug build. This typically translates to debug mode for the underlying platform being built.
| --release | Perform a release build. This typically translates to release mode for the underlying platform being built.
| --device | Build it for a device
-| --emulator | Build it for an emulator. In particular, the platform architecture might be different for a device Vs emulator.
+| --emulator | Build it for an emulator. In particular, the platform architecture might be different for a device vs. emulator.
| --buildConfig=`<configFile>` | Default: build.json in cordova root directory. <br/> Use the specified build configuration file. `build.json` file is used to specify paramaters to customize the app build process especially related to signing the package.
| `<platformOpts>` | To provide platform specific options, you must include them after `--` separator. Review platform guide docs for more details.
@@ -445,8 +446,9 @@
```bash
cordova run [<platform> [...]]
[--list | --debug | --release]
- [--noprepare] [--nobuild]
- [--device|--emulator|--target=<targetName>]
+ [--noprepare]
+ [--nobuild]
+ [--device | --emulator | --target=<targetName>]
[--buildConfig=<configfile>]
[-- <platformOpts>]
```
