Improve native messaging documentation

chrome/common/extensions/docs/templates/articles/messaging.html

Index: chrome/common/extensions/docs/templates/articles/messaging.html
diff --git a/chrome/common/extensions/docs/templates/articles/messaging.html b/chrome/common/extensions/docs/templates/articles/messaging.html
index 4efe374ecb311eaf423cf1f15566b0ac21fd0822..782c3a454d3b0f89964471308b524837f9953b67 100644
--- a/chrome/common/extensions/docs/templates/articles/messaging.html
+++ b/chrome/common/extensions/docs/templates/articles/messaging.html
@@ -279,142 +279,17 @@ chrome.runtime.onMessageExternal.addListener(
 </pre>
 
 
+<!-- Anchors to make sure that pages that link to a previous version of the
+     documentation do not break. -->
+<a id="native-messaging-host"></a>
+<a id="native-messaging-client"></a>
 <h2 id="native-messaging">Native messaging</h2>
 <p>
-Extensions can exchange messages with native applications. Native
-applications that support this feature must register a <em>native messaging
-host</em> that knows how to communicate with the extension. Chrome starts the
-host in a separate process and communicates with it using standard input and
-standard output streams.
+Extensions and apps <a href="nativeMessaging#native-messaging-client">can
+exchange messages</a> with native applications that are registered as a
+<a href="nativeMessaging#native-messaging-host">native messaging host</a>.
+To learn more about this feature, see <a href="nativeMessaging">Native messaging</a>.
 
-<h3 id="native-messaging-host">Native messaging host</h3>
-<p>
-In order to register a native messaging host the application must install a
-manifest file that defines the native messaging host configuration. Below is an
-example of the manifest file:
-<pre data-filename="manifest.json">
-{
-  "name": "com.my_company.my_application",
-  "description": "My Application",
-  "path": "C:\\Program Files\\My Application\\chrome_native_messaging_host.exe",
-  "type": "stdio",
-  "allowed_origins": [
-    "chrome-extension://knldjmfmopnpolahpmmgbagdohdnhkik/"
-  ]
-}
-</pre>
-
-<p>Native messaging host manifest file contains the following fields:
-<table class="simple">
-  <tr>
-    <th>Name</th>
-    <th>Description</th>
-  </tr>
-  <tr>
-    <td><code>name</code></td>
-    <td>Name of the native messaging host. Clients pass this string to
-    $(ref:runtime.connectNative) or $(ref:runtime.sendNativeMessage).</td>
-  </tr>
-  <tr>
-    <td><code>description</code></td>
-    <td>Short application description.</td>
-  </tr>
-  <tr>
-    <td><code>path</code></td>
-    <td>Path to the native messaging host binary. On Linux and OSX the path must
-    be absolute. On Windows it can be relative to the directory in which the
-    manifest file is located.</td>
-  </tr>
-  <tr>
-    <td><code>type</code></td>
-    <td>Type of the interface used to communicate with the native messaging
-    host. Currently there is only one possible value for this parameter:
-    <code>stdio</code>. It indicates that Chrome should use <code>stdin</code>
-    and <code>stdout</code> to communicate with the host.</td>
-  </tr>
-  <tr>
-    <td><code>allowed_origins</code></td>
-    <td>List of extensions that should have access to the native messaging host.</td>
-  </tr>
-</table>
-
-<p>Location of the manifest file depends on the platform:
-
-<dl>
-  <dt>Windows:</dt>
-    <dd>The manifest file can be located anywhere in the file system.
-     The application installer must create registry key
-     <code>HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\<em>com.my_company.my_application</em></code>
-     or
-     <code>HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\<em>com.my_company.my_application</em></code>,
-     and set default value of that key to the full path to the manifest file.
-    </dd>
-
-  <dt>OSX:</dt>
-    <dd>The manifest file must be placed at
-    <code>/Library/Google/Chrome/NativeMessagingHosts/<em>com.my_company.my_application</em>.json</code>,
-    or, for applications installed on user level,
-    <code>~/Library/Application Support/Google/Chrome/NativeMessagingHosts/<em>com.my_company.my_application</em>.json</code>.
-    </dd>
-
-  <dt>Linux:</dt>
-    <dd>The manifest file must be placed at
-    <code>/etc/opt/chrome/native-messaging-hosts/<em>com.my_company.my_application</em>.json</code>,
-    or, for applications installed on user level,
-    <code>~/.config/google-chrome/NativeMessagingHosts/<em>com.my_company.my_application</em>.json</code>.
-    </dd>
-</dl>
-
-<p>
-Chrome starts each native messaging host in a separate process and communicates
-with it using standard input (<code>stdin</code>) and standard output
-(<code>stdout</code>). The same format is used to send messages in both
-directions: each message is serialized using JSON, UTF-8 encoded
-and is preceded with 32-bit message length in native byte order.
-
-<p>
-When a messaging port is created using $(ref:runtime.connectNative) Chrome
-starts native messaging host process and keeps it running until the port is
-destroyed. On the other hand, when a message is sent using
-$(ref:runtime.sendNativeMessage), without creating a messaging port, Chrome starts
-a new native messaging host process for each message. In that case the first
-message generated by the host process is handled as a response to the original
-request, i.e. Chrome will pass it to the response callback specified when
-$(ref:runtime.sendNativeMessage) is called. All other messages generated by the
-native messaging host in that case are ignored.
-
-<h3 id="native-messaging-client">Connecting to a native application</h3>
-<p>
-Sending and receiving messages to and from a native application is very similar
-to cross-extension messaging. The main difference is that
-$(ref:runtime.connectNative) is used instead of $(ref:runtime.connect),
-and $(ref:runtime.sendNativeMessage) is used instead of $(ref:runtime.sendMessage).
-
-<p>
-The Following example creates a $(ref:runtime.Port) object that's connected to native
-messaging host <code>com.my_company.my_application</code>, starts listening for
-messages from that port and sends one outgoing message:
-<pre>
-var port = chrome.runtime.connectNative('com.my_company.my_application');
-port.onMessage.addListener(function(msg) {
-  console.log("Received" + msg);
-});
-port.onDisconnect.addListener(function() {
-  console.log("Disconnected");
-});
-port.postMessage({ text: "Hello, my_application" });
-</pre>
-
-<p>
-$(ref:runtime.sendNativeMessage) can be used to send a message to native
-application without creating a port, e.g.:
-<pre>
-chrome.runtime.sendNativeMessage('com.my_company.my_application',
-  { text: "Hello" },
-  function(response) {
-    console.log("Received " + response);
-  });
-</pre>
 
 <h2 id="security-considerations">Security considerations</h2>
 
@@ -459,8 +334,8 @@ chrome.tabs.sendMessage(tab.id, {greeting: "hello"}, function(response) {
 You can find simple examples of communication via messages in the
 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/messaging/">examples/api/messaging</a>
 directory.
-<a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/nativeMessaging/">examples/api/nativeMessaging</a>
-contains an example application that uses native messaging.
+The <a href="nativeMessaging#examples">native messaging sample</a> demonstrates
+how a Chrome app can communicate with a native app.
 For more examples and for help in viewing the source code, see
 <a href="samples">Samples</a>.
 </p>