cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mwbro...@apache.org
Subject docs commit: [CB-3962] cleaned up plugin spec, conforming to editorial guidelines
Date Thu, 18 Jul 2013 19:12:02 GMT
Updated Branches:
  refs/heads/master fdca73d45 -> 35508a6ac


[CB-3962] cleaned up plugin spec, conforming to editorial guidelines


Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/35508a6a
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/35508a6a
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/35508a6a

Branch: refs/heads/master
Commit: 35508a6ac1fb030cbd260db30367bd2f1a950db4
Parents: fdca73d
Author: Mike Sierra <letmespellitoutforyou@gmail.com>
Authored: Tue Jul 16 23:22:54 2013 -0400
Committer: Michael Brooks <michael@michaelbrooks.ca>
Committed: Thu Jul 18 12:11:44 2013 -0700

----------------------------------------------------------------------
 docs/en/edge/guide/plugins/plugin_spec.md | 422 +++++++++++++++----------
 1 file changed, 254 insertions(+), 168 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/35508a6a/docs/en/edge/guide/plugins/plugin_spec.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/plugins/plugin_spec.md b/docs/en/edge/guide/plugins/plugin_spec.md
index 61a0eba..63b9b0c 100644
--- a/docs/en/edge/guide/plugins/plugin_spec.md
+++ b/docs/en/edge/guide/plugins/plugin_spec.md
@@ -19,40 +19,37 @@ license: Licensed to the Apache Software Foundation (ASF) under one
 
 # Plugin Specification
 
-The `plugin.xml` file is an XML document in the plugins namespace -
-`http://apache.org/cordova/ns/plugins/1.0`. It contains a top-level `plugin`
-element defining the plugin, and children that define the structure of the
-plugin.
+The `plugin.xml` file is an XML document in the `plugins` namespace:
+`http://apache.org/cordova/ns/plugins/1.0`. It contains a top-level
+`plugin` element that defines the plugin, and children that define the
+structure of the plugin.
 
 A sample plugin element:
 
-	<?xml version="1.0" encoding="UTF-8"?>
+    <?xml version="1.0" encoding="UTF-8"?>
     <plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
         xmlns:android="http://schemas.android.com/apk/res/android"
         id="com.alunny.foo"
         version="1.0.2">
 
-
 ## &lt;plugin&gt; element
 
-The `plugin` element is the top-level element of the plugin manifest. It has the
-following attributes:
-
-### xmlns (required)
-
-The plugin namespace - `http://apache.org/cordova/ns/plugins/1.0`. If the document
-contains XML from other namespaces - for example, tags to be added to the
-AndroidManifest.xml file - those namespaces should also be included in the
-top-level element.
+The `plugin` element is the plugin manifest's top-level element. It
+features the following attributes:
 
-### id (required)
+* `xmlns` (required):
+  The plugin namespace, `http://apache.org/cordova/ns/plugins/1.0`. If
+  the document contains XML from other namespaces, such as tags to be
+  added to the `AndroidManifest.xml` file, those namespaces should
+  also be included in the top-level element.
 
-A reverse-domain style identifier for the plugin - for example, `com.alunny.foo`
+* `id` (required):
+  A reverse-domain style identifier for the plugin, such as
+  `com.alunny.foo`
 
-### version (required)
-
-A version number for the plugin, that matches the following major-minor-patch
-style regular expression:
+* `version` (required):
+  A version number for the plugin, that matches the following
+  major-minor-patch style regular expression:
 
     ^\d+[.]\d+[.]\d+$
 
@@ -67,29 +64,32 @@ Apache Cordova-based frameworks that this plugin supports. An example:
         <engine name="worklight" version="1.0.0" />
     </engines>
 
-Similarly to the `version` attribute for the `<plugin>` element,
-the version string specified should match a major-minor-patch string
-conforming to the regular expression:
+Similar to the `<plugin>` element's `version` attribute, the specified
+version string should match a major-minor-patch string conforming to
+the regular expression:
 
     ^\d+[.]\d+[.]\d+$
 
-Engine elements may also have fuzzy matches to avoid repetition, and reduce
-maintenance when the underlying platform is updated. A minimum of `>`, `>=`,
-`<` and `<=` should be supported by tools, such as:
+Engine elements may also specify fuzzy matches to avoid repetition,
+and to reduce maintenance when the underlying platform is updated.
+Tools should support a minimum of `>`, `>=`, `<` and `<=`, for
+example:
 
     <engines>
         <engine name="cordova" version=">=1.7.0" />
         <engine name="cordova" version="<1.8.1" />
     </engines>
 
-plugman will abort plugin installation if the target project does not meet the engine constraints,
and exit with a non-zero code.
+plugman aborts with a non-zero code for any plugin whose target
+project does not meet the engine's constraints.
 
-If no `<engine>` tags are specified, plugman will attempt to install into the specified
cordova project directory blindly.
+If no `<engine>` tags are specified, plugman attempts to install into
+the specified cordova project directory blindly.
 
 ## &lt;name&gt; element
 
-A human-readable name for the plugin. The text content of the element contains
-the name of the plugin. An example:
+A human-readable name for the plugin, whose text content contains the
+name of the plugin. For example:
 
     <name>Foo</name>
 
@@ -97,111 +97,173 @@ This element does not (yet) handle localization.
 
 ## &lt;asset&gt; element
 
-One or more elements listing the files or directories to be copied into a
-Cordova app's `www` directory. A couple of samples:
+One or more elements listing the files or directories to be copied
+into a Cordova app's `www` directory. Examples:
 
     <!-- a single file, to be copied in the root directory -->
     <asset src="www/foo.js" target="foo.js" />
     <!-- a directory, also to be copied in the root directory -->
     <asset src="www/foo" target="foo" />
 
-All assets tags require both a `src` attribute and a `target` attribute. Web-only plugins
would contains mainly `<asset>` elements. `<asset>` elements can also be nested
under `<platform>` elements, to specify platform-specific web assets (see below).
-
-### src (required)
+All `<asset>` tags require both `src` and `target` attributes.
+Web-only plugins contains mostly `<asset>` elements. Any `<asset>`
+elements that are nested within `<platform>` elements specify
+platform-specific web assets, as described below. Attributes include:
 
-Where the file or directory is located in the plugin package, relative to the
-`plugin.xml` document.
+* `src` (required): 
+  Where the file or directory is located in the plugin package,
+  relative to the `plugin.xml` document.  If a file does not exist at
+  the specified `src` location, plugman stops and reverses the
+  installation process, issues a notification about the conflict, and
+  exits with a non-zero code.
 
-If a file does not exist at the specified `src` location, plugman will stop/reverse the installation
process and notify the user, and exit with a non-zero code.
+* `target` (required):
 
-### target (required)
-
-Where the file or directory should be located in the Cordova app, relative to
-the `www` directory.
-
-Assets can be targeted to subdirectories - for instance:
+  Where the file or directory should be located in the Cordova app,
+  relative to the `www` directory.
+  Assets can be targeted to subdirectories, for example:
 
     <asset src="www/new-foo.js" target="js/experimental/foo.js" />
 
-would create the `js/experimental` directory in the `www` directory, if not
-present, and then copy the file `new-foo.js` as `foo.js` into that directory.
-
-If a file exists at the target location, plugman will stop/reverse the installation process
and notify the user of the conflict, and exit with a non-zero code.
+  creates the `js/experimental` directory within the `www` directory,
+  unless already present, then copies the `new-foo.js` file and
+  renames it `foo.js`.  If a file already exists at the target
+  location, plugman stops and reverses the installation process,
+  issues a notification about the conflict, and exits with a non-zero
+  code.
 
 ## &lt;js-module&gt; element
 
-A typical plugin includes one or more JavaScript files. Rather than have the user of your
plugin add `<script>` tags for your JavaScript to their HTML file(s) manually, you should
use `<js-module>` tags for your Javascript files.
-
-`<asset>` tags are a dumb copy: copy a file from the plugin subdirectory to `www`.
-
-In contrast, `<js-module>` tags are much more sophisticated. They look like this:
+Most plugins include one or more JavaScript files.  Each `<js-module>`
+tag corresponds to a JavaScript file, and prevents the plugin's users
+from having to add a `<script>` tag for each file.  While `<asset>`
+tags simply copy a file from the plugin subdirectory into `www`,
+`<js-module>` tags are much more sophisticated. They look like this:
 
     <js-module src="socket.js" name="Socket">
         <clobbers target="chrome.socket" />
     </js-module>
 
-With the above example, after installing a plugin, this tool will copy socket.js to `www/plugins/my.plugin.id/socket.js`.
Further, it will add an entry for this plugin to `www/cordova_plugins.js`. At load time, code
in `cordova.js` will use an XHR to read this file, inject a `<script>` tag for each
Javascript file, and add a mapping to clobber or merge as appropriate (see below).
+When installing a plugin with the example above, `socket.js` is copied
+to `www/plugins/my.plugin.id/socket.js`, and added as an entry to
+`www/cordova_plugins.js`. At load time, code in `cordova.js` uses XHR
+to read each file and inject a `<script>` tag into HTML. It adds a
+mapping to clobber or merge as appropriate, as described below.
 
-DO NOT wrap the file with `cordova.define`; this will be added automatically. Your module
will be wrapped in a closure, and will have `module`, `exports` and `require` in scope, as
normal for AMD modules.
+_Do not_ wrap the file with `cordova.define`, as it is added
+automatically. The module is wrapped in a closure, with `module`,
+`exports`, and `require` in scope, as is normal for AMD modules.
 
 Details for the `<js-module>` tag:
 
-* The `src` points to a file in the plugin directory relative to the `plugin.xml` file.
-* The `name` gives the last part of the module name. It can generally be whatever you like,
and it only matters if you want to use `cordova.require` to import other parts of your plugins
in your JavaScript code. The module name for a `<js-module>` is your plugin's `id` followed
by the value of `name`. For the example above, with an `id` of `chrome.socket`, the module
name is `chrome.socket.Socket`.
-* Inside the `<js-module>` tag there are three legal sub-tags:
-    * `<clobbers target="some.value" />` indicates that the `module.exports` will be
inserted into the `window` object as `window.some.value`. You can have as many `<clobbers>`
as you like. If the object(s) does not exist on `window`, they will be created.
-    * `<merges target="some.value" />` indicates that your module should be merged
with any existing value at `window.some.value`. If any key already exists, you module's version
overrides the original. You can have as many `<merges>` as you like. If the object(s)
does not exist on `window`, they will be created.
-    * `<runs />` means that your code should be `cordova.require`d, but not installed
on the `window` object anywhere. This is useful for initializing the module, attaching event
handlers or otherwise. You can only have 0 or 1 `<runs />` tags. Note that including
a `<runs />` with `<clobbers />` or `<merges />` is redundant, since they
also `cordova.require` your module.
-    * An empty `<js-module>` will still be loaded and can be `cordova.require`d in
other modules.
+* The `src` references a file in the plugin directory relative to the
+  `plugin.xml` file.
 
-If `src` does not resolve to a file that can be found, plugman will stop/reverse the installation,
notify the user of the problem and exit with a non-zero code.
+* The `name` provides the last part of the module name. It can
+  generally be whatever you like, and it only matters if you want to
+  use `cordova.require` to import other parts of your plugins in your
+  JavaScript code. The module name for a `<js-module>` is your
+  plugin's `id` followed by the value of `name`. For the example
+  above, with an `id` of `chrome.socket`, the module name is
+  `chrome.socket.Socket`.
 
-`<js-module>` elements can also be nested under `<platform>`, to declare platform-specific
JavaScript module bindings.
+* Three tags are allowed within `<js-module>`:
 
+    * `<clobbers target="some.value" />` indicates that the
+      `module.exports` is inserted into the `window` object as
+      `window.some.value`. You can have as many `<clobbers>` as you
+      like. Any object not available on `window` is created.
+
+    * `<merges target="some.value" />` indicates that the module
+      should be merged with any existing value at `window.some.value`.
+      If any key already exists, the module's version overrides the
+      original. You can have as many `<merges>` as you like. Any
+      object not available on `window` is created.
+
+    * `<runs />` means that your code should be specified with
+      `cordova.require`, but not installed on the `window`
+      object. This is useful when initializing the module, attaching
+      event handlers or otherwise. You can only have up to one
+      `<runs/>` tag. Note that including a `<runs/>` with
+      `<clobbers/>` or `<merges/>` is redundant, since they also
+      `cordova.require` your module.
+
+    * An empty `<js-module>` still loads and can be acccessed in other
+      modules via `cordova.require`.
+
+If `src` does not resolve to an existing file, plugman stops and
+reverses the installation, issues a notification of the problem, and
+exits with a non-zero code.
+
+Nesting `<js-module>` elements within `<platform>` declares
+platform-specific JavaScript module bindings.
 
 ## &lt;dependency&gt;
 
-Dependency tags let you specify plugins on which this plugin depends. In the future there
will be plugin repositories to fetch plugins from. In the short term, plugins are directly
pointed to by URLs in `<dependency>` tags. These tags have the following format:
+The `<dependency>` tag allows you specify other plugins on which the
+current plugin depends. While future versions will access them from
+plugin repositories, in the short term plugins are directly referenced
+as URLs by `<dependency>` tags. They are formatted as follows:
 
     <dependency id="com.plugin.id" url="https://github.com/myuser/someplugin" commit="428931ada3891801"
subdir="some/path/here" />
 
-* `id`: gives the ID of the plugin. This should be globally unique, and in reverse-domain
style. Neither of these restrictions is currently enforced, but they may be in the future
and plugins should still follow them.
-* `url`: A URL for the plugin. This should point to a git repository, since plugman will
try to `git clone` it.
-* `commit`: This is any git ref. It can be a branch or tag name (eg. `master`, `0.3.1`),
a commit hash (eg. `975ddb228af811dd8bb37ed1dfd092a3d05295f9`), anything understood by `git
checkout`.
-* `subdir`: Specifies that the plugin we're interested in exists as a subdirectory of the
git repository. This is helpful because it allows one to keep several related plugins in a
sigle git repository, and specify the plugins in it individually.
+* `id`: provides the ID of the plugin. It should be globally unique,
+  and expressed in reverse-domain style. While neither of these
+  restrictions is currently enforced, they may be in the future.
 
-In the future, version constraints will be introduced, and a plugin repository will exist
to support fetching by name instead of explicit URLs.
+* `url`: A URL for the plugin. This should reference a git repository,
+  which plugman attempts to clone.
+
+* `commit`: This is any git reference understood by `git checkout`: a
+  branch or tag name (e.g., `master`, `0.3.1`), or a commit hash (e.g.,
+  `975ddb228af811dd8bb37ed1dfd092a3d05295f9`).
+
+* `subdir`: Specifies that the targeted plugin dependency exists as a
+  subdirectory of the git repository. This is helpful because it
+  allows the repository to contain several related plugins, each
+  specified individually.
+
+In the future, version constraints will be introduced, and a plugin
+repository will exist to support fetching by name instead of explicit
+URLs.
 
 ### Relative Dependency Paths
 
-You can set the `url` of a `<dependency>` tag to `"."`, and give it a `subdir`. Then
the dependent plugin will be installed from the same local or remote git repository as the
parent plugin where the `<dependency>` tag is.
+If you set the `url` of a `<dependency>` tag to `"."` and provide a
+`subdir`, the dependent plugin is installed from the same local or
+remote git repository as the parent plugin that specifies the
+`<dependency>` tag.
 
-Note that the `subdir` is, as always, relative to the _root of the git repository_, not the
parent plugin. This is true even if you installed the plugin with a local path directly to
it. Plugman will find the root of the git repository and then find the other plugin from there.
+Note that the `subdir` always specifies a path relative to the _root_
+of the git repository, not the parent plugin. This is true even if you
+installed the plugin with a local path directly to it. Plugman finds
+the root of the git repository and then finds the other plugin from
+there.
 
 ## &lt;platform&gt;
 
-Platform tags identify platforms that have associated native code and/or require configuration
file modifications. Tools using
-this specification can identify supported platforms and install the code into
-Cordova projects.
+The `<platform>` tag identifies platforms that have associated native
+code or require modifications to their configuration files. Tools
+using this specification can identify supported platforms and install
+the code into Cordova projects.
 
-Plugins without `<platform>` tags are assumed to be JS-only, and therefore installable
on any and all platforms.
+Plugins without `<platform>` tags are assumed to be JavaScript-only,
+and therefore installable on any and all platforms.
 
 A sample platform tag:
 
     <platform name="android">
-    <!-- android specific elements -->
+        <!-- android-specific elements -->
     </platform>
     <platform name="ios">
-    <!-- ios specific elements -->
+        <!-- ios-specific elements -->
     </platform>
 
-### name (required)
-
-The `name` attribute identifies a platform as supported - it also associates the
-element's children with that platform.
+The required `name` attribute identifies a platform as supported,
+associating the element's children with that platform.
 
-Platform names should be all-lowercase. Platform names, as arbitrarily chosen,
-are listed:
+Platform names should be lowercase. Platform names, as arbitrarily
+chosen, are listed:
 
 * android
 * bb10
@@ -211,8 +273,8 @@ are listed:
 
 ## &lt;source-file&gt;
 
-`source-file` elements identify executable source code that should be installed
-into a project. A couple of examples:
+The `<source-file>` element identifies executable source code that
+should be installed into a project. Examples:
 
     <!-- android -->
     <source-file src="src/android/Foo.java"
@@ -222,43 +284,46 @@ into a project. A couple of examples:
     <source-file src="src/ios/someLib.a" framework="true" />
     <source-file src="src/ios/someLib.a" compiler-flags="-fno-objc-arc" />
 
+It supports the following attributes:
 
-### src (required)
+* `src` (required):
+  Location of the file relative to `plugin.xml`.  If the `src` file
+  cannot be found, plugman stops and reverses the installation, issues
+  a notification about the problem, and exits with a non-zero code.
 
-Where the file is located, relative to the `plugin.xml` file.
+* `target-dir`:
+  A directory into which the files should be copied, relative to the
+  root of the Cordova project.  In practice, this is most important
+  for Java-based platforms, where a file in the `com.alunny.foo`
+  package must be located within the `com/alunny/foo` directory. For
+  platforms where the source directory is not important, this
+  attribute should be omitted.
 
-If `src` does not resolve to a file that can be found, plugman will stop/reverse the installation,
notify the user of the problem and exit with a non-zero code.
+  As with assets, if the `target` of a `source-file` would overwrite
+  an existing file, plugman stops and reverses the installation,
+  issues a notification about the problem, and exits with a non-zero
+  code.
 
-### target-dir
+* `framework` (iOS only):
+  If set to `true`, also adds the specified file as a framework to the
+  project.
 
-A directory where the files should be copied into, relative to the root of the
-Cordova project.
-
-In practice, this is most important for Java-based platforms, where a file in
-the package `com.alunny.foo` has be located under the directory
-`com/alunny/foo`. For platforms where the source directory is not important,
-plugin authors should omit this attribute.
-
-As with assets, if a `source-file`'s `target` would overwrite an existing file, plugman will
stop/reverse the installation, notify the user and exit with a non-zero code.
-
-### framework
-
-Only used for iOS. If set to `true`, will also add the specified file as a framework to the
project.
-
-### compiler-flags
-
-Only used for iOS. If set, will assign the specified compiler flags for the particular source
file.
+* `compiler-flags` (iOS only):
+  If set, assigns the specified compiler flags for the particular
+  source file.
 
 ## &lt;config-file&gt;
 
-Identifies an XML-based configuration file to be modified, where in that
-document the modification should take place, and what should be modified.
+Identifies an XML-based configuration file to be modified, where in
+that document the modification should take place, and what should be
+modified.
 
-Two file types that have been tested for modification with this element are `xml` and `plist`
files. 
+Two file types that have been tested for modification with this
+element are `xml` and `plist` files.
 
-The `config-file` element only allows for appending
-new children into an XML document. The children are XML literals that are the
-to be inserted in the target document.
+The `config-file` element only allows you to append new children to an
+XML document tree. The children are XML literals to be inserted in the
+target document.
 
 Example for XML:
 
@@ -269,8 +334,7 @@ Example for XML:
         </activity>
     </config-file>
 
-Example for plist:
-
+Example for `plist`:
 
     <config-file target="*-Info.plist" parent="CFBundleURLTypes">
         <array>
@@ -281,28 +345,40 @@ Example for plist:
         </array>
     </config-file>
 
-### target
+It supports the following attributes:
 
-The file to be modified, and the path relative to the root of the Cordova
-project.
+* `target`:
 
-The target can include a wildcard (`*`) element. In this case, plugman will recursively search
through the project directory structure and use the first match.
+  The file to be modified, and the path relative to the root of the
+  Cordova project.
 
-On iOS, the location of configuration files relative to the project directory root is not
known. Specifying a target of `config.xml` will resolve to `cordova-ios-project/MyAppName/config.xml`.
+  The target can include wildcard (`*`) elements. In this case,
+  plugman recursively searches through the project directory structure
+  and uses the first match.
 
-If the specified file does not exist, the tool will ignore the configuration change and continue
installation.
+  On iOS, the location of configuration files relative to the project
+  directory root is not known, so specifying a target of `config.xml`
+  resolves to `cordova-ios-project/MyAppName/config.xml`.
 
-### parent
+  If the specified file does not exist, the tool ignores the
+  configuration change and continues installation.
 
-An XPath selector pointing to the parent of the elements to be added to the config file.
If absolute selectors are used, you can use a wildcard (`*`) to specify the root element,
e.g. `/*/plugins`.
+* `parent`: An XPath selector referencing the parent of the elements
+  to be added to the config file. If you use absolute selectors, you
+  can use a wildcard (`*`) to specify the root element,
+  e.g., `/*/plugins`.
 
-For plist files, the parent is used to determine under what parent key should the specified
XML be inserted.
+  For `plist` files, the `parent` determines under what parent key the
+  specified XML should be inserted.
 
-If the selector does not resolve to a child of the specified document, the tool should stop/reverse
the installation process, warn the user, and exit with a non-zero code.
+  If the selector does not resolve to a child of the specified
+  document, the tool stops and reverses the installation process,
+  issues a warning, and exits with a non-zero code.
 
 ## &lt;plugins-plist&gt;
 
-This is OUTDATED as it only applies to cordova-ios 2.2.0 and below. Use `<config-file>`
tag for newer versions of Cordova.
+This is _outdated_ as it only applies to cordova-ios 2.2.0 and
+below. Use the `<config-file>` tag for newer versions of Cordova.
 
 Example:
 
@@ -310,18 +386,15 @@ Example:
          <plugin name="ChildBrowser" value="ChildBrowserCommand"/>
     </config-file>
 
-Specifies a key and value to append to the correct `AppInfo.plist` file in an
-iOS Cordova project. Example:
+Specifies a key and value to append to the correct `AppInfo.plist`
+file in an iOS Cordova project. For example:
 
     <plugins-plist key="Foo" string="CDVFoo" />
 
-
 ## &lt;resource-file&gt; and &lt;header-file&gt;
 
-Like source files, but specifically for platforms that distinguish between
-source files, headers, and resources (iOS).
-
-Examples:
+Like source files, but specifically for platforms such as iOS that
+distinguish between source files, headers, and resources.  Examples:
 
     <resource-file src="CDVFoo.bundle" />
     <resource-file src="CDVFooViewController.xib" />
@@ -329,42 +402,48 @@ Examples:
 
 ## &lt;lib-file&gt;
 
-Like source, resource and header files but specifically for platforms that use user generated
libraries (BB10).
-
+Like source, resource, and header files, but specifically for
+platforms such as BlackBerry 10 that use user-generated libraries.
 Examples:
 
     <lib-file src="src/BlackBerry10/native/device/libfoo.so" arch="device" />
     <lib-file src="src/BlackBerry10/native/simulator/libfoo.so" arch="simulator" />
 
+Supported attributes:
 
-### src (required)
-
-Where the file is located, relative to the `plugin.xml` file.
-
-If `src` does not resolve to a file that can be found, plugman will stop/reverse the installation,
notify the user of the problem and exit with a non-zero code.
+* `src` (required):
+  The location of the file relative to `plugin.xml`.
+  If `src` cannot be found, plugman stops and reverses the
+  installation, issues a warning about the problem, and exits with a
+  non-zero code.
 
-### arch
-
-The architecture that the `.so` file has been built for. Valid values are `device` and `simulator`.
+* `arch`: The architecture for which the `.so` file has been built,
+  either `device` or `simulator`.
 
 ## &lt;framework&gt;
 
-Identifies a framework (usually part of the OS/platform) that the plugin depends on.
+Identifies a framework (usually part of the OS/platform) on which the plugin depends.
 
 Examples:
 
     <framework src="libsqlite3.dylib" />
     <framework src="social.framework" weak="true" />
 
-plugman identifies the framework through the `src` attribute and attempts to add the framework
to the Cordova project, in the correct fashion for a given platform.
 
-The optional `weak` attribute is a boolean denoting whether the framework should be weakly-linked.
Default is `false`.
 
-## &lt;info&gt;
 
-The tool will provide additional information to users. This is useful when you require some
extra steps that can't be easily automated or are out of the scope of plugman.
+The `src` attribute identifies the framework, which plugman attempts
+to add to the Cordova project, in the correct fashion for a given
+platform.
 
-Examples:
+The optional `weak` attribute is a boolean indicating whether the
+framework should be weakly linked. The default is `false`.
+
+## &lt;info&gt;
+
+Additional information provided to users. This is useful when you
+require extra steps that can't be easily automated or are beyond
+plugman's scope.  Examples:
 
     <info>
     You need to install **Google Play Services** from the `Android Extras` section using
the Android SDK manager (run `android`).
@@ -376,41 +455,48 @@ Examples:
 
 # Variables
 
-In certain cases, a plugin may need to make configuration changes dependent on
-the target application. For example, to register for C2DM on Android, an app
-with package id `com.alunny.message` would need a permission like:
+In certain cases, a plugin may need to make configuration changes
+dependent on the target application. For example, to register for C2DM
+on Android, an app whose package id is `com.alunny.message` would
+require a permission such as:
 
     <uses-permission
     android:name="com.alunny.message.permission.C2D_MESSAGE"/>
 
-In cases like this (where the content inserted from the `plugin.xml` file is
-not known ahead of time), variables can be indicated by a dollar-sign and a
-series of capital letters, digits and underscores. For the above example, the
-`plugin.xml` file would include this tag:
+In such cases where the content inserted from the `plugin.xml` file is
+not known ahead of time, variables can be indicated by a dollar-sign
+followed by a series of capital letters, digits, or underscores. For
+the above example, the `plugin.xml` file would include this tag:
 
     <uses-permission
     android:name="$PACKAGE_NAME.permission.C2D_MESSAGE"/>
 
-plugman replaces variable references with the
-correct value, if specified, or the empty string otherwise. The value of the
-variable reference may be detected (in this case, from the `AndroidManifest.xml`
-file), or specified by the user of the tool; the exact process is dependent on
+plugman replaces variable references with the specified value, or the
+empty string if not found. The value of the variable reference may be
+detected (in this case, from the `AndroidManifest.xml` file) or
+specified by the user of the tool; the exact process is dependent on
 the particular tool.
 
-plugman can request users to specify variables required by a plugin. For example API keys
for C2M and Google Maps can be specified as a command line argument like so:
+plugman can request users to specify a plugin's required
+variables. For example, API keys for C2M and Google Maps can be
+specified as a command-line argument:
 
     plugman --platform android --project /path/to/project --plugin name|git-url|path --variable
API_KEY=!@CFATGWE%^WGSFDGSDFW$%^#$%YTHGsdfhsfhyer56734
 
-A preference tag will need to be present inside the platform tag to make the variable mandatory
like so:
+To make the variable mandatory, the `<platform>` tag needs to contain
+a `<preference>` tag. For example:
 
     <preference name="API_KEY" />
 
-plugman should check that these required preferences are passed in, and if not, should warn
the user on how to pass the variable in and exit with a non-zero code.
+plugman checks that these required preferences are passed in.  If not,
+it should warn the user how to pass the variable in and exit with a
+non-zero code.
 
-Certain variable names should be reserved - these are listed below.
+Certain variable names should be reserved, as listed below.
 
 ## $PACKAGE_NAME
 
-The reverse-domain style unique identifier for the package - corresponding to
-the `CFBundleIdentifier` on iOS or the `package` attribute of the top-level
-`manifest` element in an `AndroidManifest.xml` file.
+The reverse-domain style unique identifier for the package,
+corresponding to the `CFBundleIdentifier` on iOS or the `package`
+attribute of the top-level `manifest` element in an
+`AndroidManifest.xml` file.


Mime
View raw message