cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From purplecabb...@apache.org
Subject [14/50] [abbrv] docs commit: rewrite overview to clearly distinguish cross-platform/platform-centered workflows
Date Thu, 20 Feb 2014 21:08:53 GMT
rewrite overview to clearly distinguish cross-platform/platform-centered workflows


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

Branch: refs/heads/master
Commit: 25534a05d014c7d11440df89f2c061ea22c10884
Parents: 7fdf3dc
Author: Mike Sierra <msierra@adobe.com>
Authored: Fri Feb 7 11:48:17 2014 -0500
Committer: Mike Sierra <msierra@adobe.com>
Committed: Fri Feb 7 11:48:17 2014 -0500

----------------------------------------------------------------------
 docs/en/edge/guide/cli/index.md               |  15 +--
 docs/en/edge/guide/overview/index.md          | 135 +++++++++------------
 docs/en/edge/guide/platforms/android/index.md |  12 +-
 docs/en/edge/guide/platforms/ubuntu/index.md  |  22 ++--
 docs/en/edge/plugin_ref/plugman.md            |  30 +++--
 5 files changed, 101 insertions(+), 113 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/25534a05/docs/en/edge/guide/cli/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/cli/index.md b/docs/en/edge/guide/cli/index.md
index bc02753..071e646 100644
--- a/docs/en/edge/guide/cli/index.md
+++ b/docs/en/edge/guide/cli/index.md
@@ -279,13 +279,8 @@ Searching for only the `bar` term yields and additional result:
         org.apache.cordova.statusbar - Cordova StatusBar Plugin
 
 The `cordova plugin add` command requires you to specify the
-repository for the plugin code.  Please note that when you follow the 
-Web Project Dev workflow and use the CLI, the CLI will take care of adding
-the plugin code to the appropriate place for each platform. (If you are following the
-Native Project Dev Workflow, you will have to add plugins using Plugman (guide link here),
-multiple times for each platform.)
-
-Here are examples of how you might use the CLI to add features to the app:
+repository for the plugin code.  Here are examples of how you might
+use the CLI to add features to the app:
 
 * Basic device information (Device API):
 
@@ -338,6 +333,12 @@ Here are examples of how you might use the CLI to add features to the
app:
 
         $ cordova plugin add org.apache.cordova.console
 
+__NOTE__: The CLI adds plugin code as appropriate for each platform.
+If you want to develop with lower-level shell tools or platform SDKs
+as discussed in the Overview, you need to run the Plugman utility to
+add plugins separately for each platform. (For more information, see
+Using Plugman to Manage Plugins.)
+
 Use `plugin ls` (or `plugin list`, or `plugin` by itself) to view
 currently installed plugins. Each displays by its identifier:
 

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/25534a05/docs/en/edge/guide/overview/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/overview/index.md b/docs/en/edge/guide/overview/index.md
index b33e9f5..a29fca1 100644
--- a/docs/en/edge/guide/overview/index.md
+++ b/docs/en/edge/guide/overview/index.md
@@ -54,86 +54,65 @@ The application itself is implemented as a web page, named
 _index.html_ by default, that references whatever CSS, JavaScript,
 images, media files, or other resources are necessary for it to run.
 The app executes as a _WebView_ within the native application wrapper,
-which you distribute to app stores.  For the web app to interact with
-various device features the way native apps do, it must also reference
-a `cordova.js` file, which provides API bindings.
+which you distribute to app stores.
 
 The Cordova-enabled WebView may provide the application with its
-entire user interface. It can also be a component within a larger,
-hybrid application that mixes the WebView with native application
-components.  Cordova provides a _plugin_ interface for these
-components to communicate with each other.
+entire user interface. On some platforms, it can also be a component
+within a larger, hybrid application that mixes the WebView with native
+application components. (See Embedding WebViews for details.)
+
+A _plugin_ interface is available for Cordova and native components to
+communicate with each other. As of version 3.0, plugins provide
+bindings to standard device APIs.  Third-party plugins provide
+additional bindings to features not necessarily available on all
+platforms. You can also develop your own plugins, as described in
+Plugin Development Guide. Plugins may be necessary, for example, to
+communicate between Cordova and custom native components.
 
 ## Development Paths
 
-As of version 3.0, you can use two basic workflows to create
-a mobile application. While you can accomplish the same
-thing using both workflows, certain tasks are better suited to using one workflow 
-over the other. For this reason, you should understand both workflows so
-that you can use the best tool for the best situation.
-
-The two main workflows that are supported are the _Web Project Dev_ workflow and the _Native
Platform Dev_ workflow.
-
-### Web Project Dev
-
-You can think of the first workflow as the _Web Project Dev_ workflow. You should use
-this workflow when you want to create a Cordova application that runs on 
-as many mobile operating systems as possible with as little platform-specific
-development work as possible. This workflow came into existence with Cordova 3.0
-and the creation of the Cordova _Command-line Interface_ (CLI). The CLI abstracts
-away a lot of the functionality of lower-level shell scripts that take care of the
-details involved with building your app, such as copying your web assets into 
-the correct folders for each mobile platform, making platform specific configuration
-changes, or running specific build scripts to generate application binaries. You can read

-more about the _Web Project Dev_ workflow in The Command-line Interface. Please note
-that often when people speak of the "CLI," they are talking about this _Web Project Dev_
-workflow.
-
-### Native Platform Dev
-
-The second workflow can be thought of as a _Native Platform Dev_ workflow. You should use
it
-when you want to focus on building an application for a single platform and are 
-interested in changing the lower-level platform details. While you can still use this workflow
-to build cross-platform apps, the lack of tools to abstract away the various build steps
will
-make it more difficult. For example, you will have to use Plugman to
-install the same plugin once for each platform that you want to support. The 
-benefit to using this _Native Platform Dev_ workflow is that it gives you access to the lower-level
-shell scripts to build and test the application, so if you are hacking on the native 
-side of things, this workflow is the most efficient way to test your changes. This workflow
-is also appropriate if you want to use the CordovaWebView as a small part in a larger native
-application (See the Embedding WebViews guide.)  You can read about this workflow in the
different
-Shell Tool guides, for instance, Android Shell Tool Guide and iOS Shell Tool Guide.
-
-When first starting out, it might be easiest to use the _Web Project Dev_ workflow
-to create an application. (To install the CLI, see The Command-line Interface.)
-Depending on the set of platforms you wish to target, you can rely on
-the CLI for progressively greater shares of the development cycle:
-
-* In the most basic scenario, you can use the CLI simply to create a
-  new project that is populated with default configuration for you to
-  modify.
-
-* For many mobile platforms, you can also use the CLI to set up
-  additional project files required to compile within each SDK.  For
-  this to work, you must install each targeted platform's SDK.
-  (See the Platform Guides for instructions.)
-  As indicated in the Platform Support table, you may need to
-  run the CLI on different operating systems depending on the targeted
-  platform.
-
-* For supporting platforms, the CLI can compile executible
-  applications and run them in an SDK-based device emulator.
-  For comprehensive testing, you can also generate application files
-  and install them directly on a device.
-
-At any point in the development cycle, you can switch to using more of the _Native Platform
-Dev_ workflow. The platform-specific SDK tools provided may provide a richer set of
-options. (See the Platform Guides for details about each platform's SDK tool set.)
-
-An SDK environment is more appropriate if you want implement a hybrid
-app that mixes web-based and native application components.
-You may use the command-line utility to initially generate the app, or
-iteratively thereafter to feed updated code to SDK tools.  You may
-also build the app's configuration file yourself.
-(See The config.xml File for details.)
-
+As of version 3.0, you can use two basic workflows to create a mobile
+app. While you can often use either workflow to accomplish the same
+task, they each offer advantages:
+
+- __Cross-platform workflow__: Use this workflow if you want your app
+  to run on as many different mobile operating systems as possible,
+  with little need for platform-specific development.  This workflow
+  centers around the `cordova` utility, otherwise known as the Cordova
+  _CLI_, that was introduced with Cordova 3.0. (For details on the
+  CLI, see The Command-Line Interface.) The CLI is a high-level tool
+  that allows you to build projects for many platforms at once,
+  abstracting away much of the functionality of lower-level shell
+  scripts. The CLI copies a common set of web assets into
+  subdirectories for each mobile platform, makes any necessary
+  configuration changes for each, runs build scripts to generate
+  application binaries. The CLI also provides a common interface to
+  apply plugins to your app.
+
+- __Platform-centered workflow__: Use this workflow if you want to
+  focus on building an app for a single platform and need to be able
+  to modify it at a lower level. You need to use this approach, for
+  example, if you want your app to mix custom native components with
+  web-based Cordova components, as discussed in Embedding WebViews.
+  As a rule of thumb, use this workflow if you need to modify the
+  project within the SDK.  This workflow relies on a set of
+  lower-level shell scripts that are tailored for each supported
+  platform, and a separate Plugman utility that allows you to apply
+  plugins.  While you can use this workflow to build cross-platform
+  apps, it is generally more difficult because the lack of a
+  higher-level tool means separate build cycles and plugin
+  modifications for each platform. Still, this workflow allows you
+  greater access to development options provided by each SDK, and is
+  essential for complex hybrid apps. (See the various Platform Guides
+  for details on each platform's available shell utilities.)
+
+When first starting out, it may be easiest to use the cross-platform
+workflow to create an app. (See The Command-line Interface for
+details.) You then have the option to switch to a platform-centered
+workflow if you need the greater control the SDK provides. However,
+once you do so, you can't go back. The CLI maintains a common set of
+cross-platform source code, which on each build it uses to write over
+platform-specific source code.  To preserve any modifications you make
+to the platform-specific assets, you need to switch to the
+platform-centered shell tools, which ignore the cross-platform source
+code, and instead relies on the platform-specific source code.

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/25534a05/docs/en/edge/guide/platforms/android/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/android/index.md b/docs/en/edge/guide/platforms/android/index.md
index c6e50e9..faf863c 100644
--- a/docs/en/edge/guide/platforms/android/index.md
+++ b/docs/en/edge/guide/platforms/android/index.md
@@ -20,12 +20,12 @@ license: Licensed to the Apache Software Foundation (ASF) under one
 # Android Platform Guide
 
 This guide shows how to set up your SDK development environment to
-deploy Cordova apps for Android devices. It walks you through the process
-of installing the Android SDK, opening an Android project in Eclipse SDK, 
-and deploying to an emulator or device. You will need to follow this guide 
-to at least Install the Android SDK, regardless of which workflow you
-are following. (Both the _Web Project Dev_ and _Native Platform Dev_ workflows
-require the Android SDK to be installed and accessable via your PATH.)
+deploy Cordova apps for Android devices. It shows how to install the
+Android SDK, open an Android project in the SDK, and deploy it to an
+emulator or device.  You need to follow the instructions to install
+the Android SDK, regardless of whether you use the cross-platform
+workflow discussed in the Overview, or the platform-centered shell
+tools detailed at Android Command-line Tools.
 
 See the following for more detailed platform-specific information:
 

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/25534a05/docs/en/edge/guide/platforms/ubuntu/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/ubuntu/index.md b/docs/en/edge/guide/platforms/ubuntu/index.md
index e3f4c2b..11d3ea1 100644
--- a/docs/en/edge/guide/platforms/ubuntu/index.md
+++ b/docs/en/edge/guide/platforms/ubuntu/index.md
@@ -21,11 +21,12 @@ license: Licensed to the Apache Software Foundation (ASF) under one
 
 ## Initial Release
 
-Welcome to the initial release of Ubuntu platform support in Cordova. With this
-release, the focus is developing on an Ubuntu system and using the Cordova Web
-Project Dev Workflow. This includes adding the Ubuntu platform to your project,
-adding standard Cordova plugins, and, of course, building and running apps for
-the Ubuntu platform.
+Welcome to the initial release of Ubuntu platform support in
+Cordova. With this release, the focus is developing on an Ubuntu
+system and using the cross-platform workflow discussed in the
+Overview.  This includes adding the Ubuntu platform to your project,
+adding standard Cordova plugins, and building and running apps for the
+Ubuntu platform.
 
 ### Ubuntu SDK
 
@@ -36,11 +37,11 @@ app.)
 
 ### Ubuntu Runtime Platforms
 
-Ubuntu is well-known for its Desktop environment (for laptops, PCs and such).
+Ubuntu is well known for its Desktop environment (for laptops, PCs and such).
 Ubuntu Touch extends the Ubuntu OS onto phones and tablets. Ubuntu runtime
 platforms have varying CPU architectures (x86, armhf, etc.). App and plugin
 code must be compiled appropriately. Support for this broad area is rapidly
-evolving in the Ubuntu.
+evolving in Ubuntu.
 
 ### Latest Information
 
@@ -73,11 +74,14 @@ Install cordova-cli package (and its dependencies):
 
 ### Create a project
 
-    $ cordova create project1 REVERSEDNSNAME.project1 project1
+Creates an app in a `hello` directory whose display name is
+`HelloWorld`:
+
+    $ cordova create hello com.example.hello HelloWorld
 
 ### Move into the Project Directory
 
-    $ cd project1
+    $ cd hello
 
 ### Add the Ubuntu Platform
 

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/25534a05/docs/en/edge/plugin_ref/plugman.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/plugin_ref/plugman.md b/docs/en/edge/plugin_ref/plugman.md
index e6f0323..2287226 100644
--- a/docs/en/edge/plugin_ref/plugman.md
+++ b/docs/en/edge/plugin_ref/plugman.md
@@ -21,23 +21,27 @@ license: Licensed to the Apache Software Foundation (ASF) under one
 
 From version 3.0 onward, Cordova implements all device APIs as
 plugins, and leaves them disabled by default. It also supports two
-different ways to add and remove plugins. The first is by using the
-`cordova` CLI described in The Command-Line Interface. The second is
-by using a lower-level
-[Plugman](https://github.com/apache/cordova-plugman/)
-command-line interface ("Native platform dev" workflow.) The main difference between these
two development
-paths is that Plugman can only add plugins to one platform at a time, whereas the CLI will
add plugins
-to all of the platforms that you are targeting.  Because of this, it makes more sense to
use Plugman when
-you are working closely with a single platform, hence the "Native Platform Dev" name of the
workflow. 
-
-For more information on Plugman, especially if you are interested in consuming Plugman as
a node module 
-or hacking on the Plugman code, see [the README file in its repository](https://github.com/apache/cordova-plugman/blob/master/README.md).
+different ways to add and remove plugins, depending on your choice of
+workflow discussed in the Overview:
+
+- If you use a cross-platform workflow, you use the `cordova` CLI
+  utility to add plugins, as described in The Command-Line Interface.
+  The CLI modifies plugins for all specified platforms at once.
+
+- If you use a platform-centered workflow, you use a lower-level
+  [Plugman](https://github.com/apache/cordova-plugman/) command-line
+  interface, separately for each targeted platform.
+
+This section details the Plugman utility.  For more information on
+consuming Plugman as a node module or modifying the source code, see
+[the README file in its repository](https://github.com/apache/cordova-plugman/blob/master/README.md).
 
 ## Installing Plugman
 
 To install plugman, you must have [node](http://nodejs.org/) installed
-on your machine. Then you can run the following command from anywhere in your environment
to install plugman globally, so that it
-is available from any directory on your machine:
+on your machine. Then you can run the following command from anywhere
+in your environment to install plugman globally, so that it is
+available from any directory:
 
     $ npm install -g plugman
 


Mime
View raw message