Improve native messaging documentation

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

 <h1>Message Passing</h1>
 
 
 <p>
 Since content scripts run in the context of a web page and not the extension,
 they often need some way of communicating with the rest of the extension. For
 example, an RSS reader extension might use content scripts to detect the
 presence of an RSS feed on a page, then notify the background page in order to
 display a page action icon for that page.
 
@@ skipping 261 matching lines @@
 chrome.runtime.onMessageExternal.addListener(
   function(request, sender, sendResponse) {
     if (sender.url == blacklistedWebsite)
       return;  // don't allow this web page access
     if (request.openUrlInEditor)
       openUrl(request.openUrlInEditor);
   });
 </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>
 
 <p>
 When receiving a message from a content script or another extension, your
 background page should be careful not to fall victim to <a
 href="http://en.wikipedia.org/wiki/Cross-site_scripting">cross-site
 scripting</a>.  Specifically, avoid using dangerous APIs such as the
 below:
 </p>
@@ skipping 24 matching lines @@
   document.getElementById("resp").innerText = response.farewell;
 });
 </pre>
 
 <h2 id="examples">Examples</h2>
 
 <p>
 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>