Merge pull request #2750 from atom/jl-doc-bits

A Few More Documentation Things

CONTRIBUTING.md

@@ -29,6 +29,7 @@ possible with your report. If you can, please include:
 * Include screenshots and animated GIFs in your pull request whenever possible.
 * Follow the CoffeeScript, JavaScript, C++ and Python [coding style defined in docs](/docs/development/coding-style.md).
 * Write documentation in [Markdown](https://daringfireball.net/projects/markdown).
+  See the [Documentation Styleguide](/docs/styleguide.md).
 * Use short, present tense commit messages. See [Commit Message Styleguide](#git-commit-messages-styleguide).
 
 ## Styleguides

docs/README.md

@@ -1,32 +1,32 @@
 ## Guides
 
-* [Application distribution](tutorial/application-distribution.md)
-* [Application packaging](tutorial/application-packaging.md)
-* [Using native node modules](tutorial/using-native-node-modules.md)
-* [Debugging main process](tutorial/debugging-main-process.md)
+* [Application Distribution](tutorial/application-distribution.md)
+* [Application Packaging](tutorial/application-packaging.md)
+* [Using Native Node Modules](tutorial/using-native-node-modules.md)
+* [Debugging Main Process](tutorial/debugging-main-process.md)
 * [Using Selenium and WebDriver](tutorial/using-selenium-and-webdriver.md)
-* [DevTools extension](tutorial/devtools-extension.md)
-* [Using pepper flash plugin](tutorial/using-pepper-flash-plugin.md)
+* [DevTools Extension](tutorial/devtools-extension.md)
+* [Using Pepper Flash Plugin](tutorial/using-pepper-flash-plugin.md)
 
 ## Tutorials
 
-* [Quick start](tutorial/quick-start.md)
-* [Desktop environment integration](tutorial/desktop-environment-integration.md)
-* [Online/offline event detection](tutorial/online-offline-events.md)
+* [Quick Start](tutorial/quick-start.md)
+* [Desktop Environment Integration](tutorial/desktop-environment-integration.md)
+* [Online/Offline Event Detection](tutorial/online-offline-events.md)
 
-## API references
+## API References
 
 * [Synopsis](api/synopsis.md)
-* [Process object](api/process.md)
-* [Supported Chrome command line switches](api/chrome-command-line-switches.md)
+* [Process Object](api/process.md)
+* [Supported Chrome Command Line Switches](api/chrome-command-line-switches.md)
 
-Custom DOM elements:
+### Custom DOM Elements:
 
-* [`File` object](api/file-object.md)
-* [`<webview>` tag](api/web-view-tag.md)
-* [`window.open` function](api/window-open.md)
+* [`File` Object](api/file-object.md)
+* [`<webview>` Tag](api/web-view-tag.md)
+* [`window.open` Function](api/window-open.md)
 
-Modules for the main process:
+### Modules for the Main Process:
 
 * [app](api/app.md)
 * [auto-updater](api/auto-updater.md)
@@ -41,16 +41,16 @@ Modules for the main process:
 * [power-save-blocker](api/power-save-blocker.md)
 * [protocol](api/protocol.md)
 * [session](api/session.md)
-* [webContents](api/web-contents.md)
+* [web-contents](api/web-contents.md)
 * [tray](api/tray.md)
 
-Modules for the renderer process (web page):
+### Modules for the Renderer Process (Web Page):
 
 * [ipc (renderer)](api/ipc-renderer.md)
 * [remote](api/remote.md)
 * [web-frame](api/web-frame.md)
 
-Modules for both processes:
+### Modules for Both Processes:
 
 * [clipboard](api/clipboard.md)
 * [crash-reporter](api/crash-reporter.md)
@@ -60,11 +60,11 @@ Modules for both processes:
 
 ## Development
 
-* [Coding style](development/coding-style.md)
-* [Source code directory structure](development/source-code-directory-structure.md)
-* [Technical differences to NW.js (formerly node-webkit)](development/atom-shell-vs-node-webkit.md)
-* [Build system overview](development/build-system-overview.md)
-* [Build instructions (Mac)](development/build-instructions-osx.md)
-* [Build instructions (Windows)](development/build-instructions-windows.md)
-* [Build instructions (Linux)](development/build-instructions-linux.md)
-* [Setting up symbol server in debugger](development/setting-up-symbol-server.md)
+* [Coding Style](development/coding-style.md)
+* [Source Code Directory Structure](development/source-code-directory-structure.md)
+* [Technical Differences to NW.js (formerly node-webkit)](development/atom-shell-vs-node-webkit.md)
+* [Build System Overview](development/build-system-overview.md)
+* [Build Instructions (Mac)](development/build-instructions-osx.md)
+* [Build Instructions (Windows)](development/build-instructions-windows.md)
+* [Build Instructions (Linux)](development/build-instructions-linux.md)
+* [Setting Up Symbol Server in debugger](development/setting-up-symbol-server.md)

docs/api/app.md

@@ -152,7 +152,7 @@ Emitted when the gpu process crashes.
 
 The `app` object has the following methods:
 
-**Note** Some methods are only available on specific operating systems and are labeled as such.
+**Note:** Some methods are only available on specific operating systems and are labeled as such.
 
 ### `app.quit()`
 

docs/api/auto-updater.md

@@ -53,7 +53,7 @@ server that you are requesting updates from. A common approach is to use query
 parameters, like this:
 
 ```javascript
-// On the main process
+// In the main process
 var app = require('app');
 var autoUpdater = require('auto-updater');
 autoUpdater.setFeedUrl('http://mycompany.com/myapp/latest?version=' + app.getVersion());

docs/api/browser-window.md

@@ -117,7 +117,7 @@ Properties `width` and `height` are required.
 
 The `BrowserWindow` object emits the following events:
 
-+**Note** Some events are only available on specific operating systems and are labeled as such.
++**Note:** Some events are only available on specific operating systems and are labeled as such.
 
 ### Event: 'page-title-updated'
 
@@ -224,15 +224,15 @@ Emitted when the window leaves full screen state triggered by html api.
 
 ### Event: 'devtools-opened'
 
-Emitted when devtools is opened.
+Emitted when DevTools is opened.
 
 ### Event: 'devtools-closed'
 
-Emitted when devtools is closed.
+Emitted when DevTools is closed.
 
 ### Event: 'devtools-focused'
 
-Emitted when devtools is focused / opened.
+Emitted when DevTools is focused / opened.
 
 ### Event: 'app-command' _Windows_
 
@@ -277,7 +277,7 @@ Find a window according to its ID.
 
 * `path` String
 
-Adds devtools extension located at `path`, and returns extension's name.
+Adds DevTools extension located at `path`, and returns extension's name.
 
 The extension will be remembered so you only need to call this API once, this
 API is not for programming use.
@@ -286,13 +286,13 @@ API is not for programming use.
 
 * `name` String
 
-Remove the devtools extension whose name is `name`.
+Remove the DevTools extension whose name is `name`.
 
 ## Instance Methods
 
 Objects created with `new BrowserWindow` have the following instance methods:
 
-+**Note** Some methods are only available on specific operating systems and are labeled as such.
++**Note:** Some methods are only available on specific operating systems and are labeled as such.
 
 ```javascript
 var BrowserWindow = require('browser-window');
@@ -315,10 +315,10 @@ when the renderer process (web page) has crashed.
 
 ### `win.devToolsWebContents()`
 
-Get the `WebContents` of devtools for this window.
+Get the `WebContents` of DevTools for this window.
 
 **Note:** Users should never store this object because it may become `null`
-when the devtools has been closed.
+when the DevTools has been closed.
 
 ### `win.id()`
 
@@ -577,7 +577,7 @@ Whether the window's document has been edited.
 ### `win.openDevTools([options])`
 
 * `options` Object (optional). Properties:
-  * `detach` Boolean - opens devtools in a new window
+  * `detach` Boolean - opens DevTools in a new window
 
 Opens the developer tools.
 

docs/api/global-shortcut.md

@@ -4,7 +4,7 @@ The `global-shortcut` module can register/unregister a global keyboard shortcut
 with the operating system so that you can customize the operations for various
 shortcuts.
 
-**Note**: The shortcut is global; it will work even if the app does
+**Note:** The shortcut is global; it will work even if the app does
 not have the keyboard focus. You should not use this module until the `ready`
 event of the app module is emitted.
 

docs/api/ipc-renderer.md

@@ -4,7 +4,7 @@ The `ipc` module provides a few methods so you can send synchronous and
 asynchronous messages from the render process (web page) to the main process.
 You can also receive replies from the main process.
 
-**Note**: If you want to make use of modules in the main process from the renderer
+**Note:** If you want to make use of modules in the main process from the renderer
 process, you might consider using the [remote](remote.md) module.
 
 See [ipc (main process)](ipc-main-process.md) for code examples.
@@ -13,7 +13,7 @@ See [ipc (main process)](ipc-main-process.md) for code examples.
 
 The `ipc` module has the following methods for sending messages:
 
-**Note**: When using these methods to send a `message` you must also listen
+**Note:** When using these methods to send a `message` you must also listen
 for it in the main process with [`ipc (main process)`](ipc-main-process.md).
 
 ### `ipc.send(channel[, arg1][, arg2][, ...])`

docs/api/native-image.md

@@ -74,7 +74,7 @@ mixed with other content to create the desired final appearance.
 The most common case is to use template images for a menu bar icon so it can
 adapt to both light and dark menu bars.
 
-**Note**: Template image is only supported on OS X.
+**Note:** Template image is only supported on OS X.
 
 To mark an image as a template image, its filename should end with the word
 `Template`. For example:

docs/api/power-monitor.md

@@ -1,7 +1,7 @@
 # power-monitor
 
 The `power-monitor` module is used to monitor power state changes. You can
-only use it on the main process. You should not use this module until the `ready`
+only use it in the main process. You should not use this module until the `ready`
 event of the `app` module is emitted.
 
 For example:

docs/api/remote.md

@@ -20,7 +20,7 @@ var win = new BrowserWindow({ width: 800, height: 600 });
 win.loadUrl('https://github.com');
 ```
 
-**Note**: for the reverse (access the renderer process from the main process),
+**Note:** for the reverse (access the renderer process from the main process),
 you can use [webContents.executeJavascript](browser-window.md#webcontents-executejavascript-code).
 
 ## Remote Objects

docs/api/screen.md

@@ -6,7 +6,7 @@ position, etc. You should not use this module until the `ready` event of the
 
 `screen` is an [EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter).
 
-**Note**: In the renderer / DevTools, `window.screen` is a reserved
+**Note:** In the renderer / DevTools, `window.screen` is a reserved
 DOM property, so writing `var screen = require('screen')` will not work. In our
 examples below, we use `atomScreen` as the variable name instead.
 

docs/api/synopsis.md

@@ -5,13 +5,13 @@ Electron and third-party node modules also fully supported as well (including
 the [native modules](../tutorial/using-native-node-modules.md)).
 
 Electron also provides some extra built-in modules for developing native
-desktop applications. Some modules are only available on the main process, some
+desktop applications. Some modules are only available in the main process, some
 are only available in the renderer process (web page), and some can be used in
 both processes.
 
 The basic rule is: if a module is
 [GUI](https://en.wikipedia.org/wiki/Graphical_user_interface) or low-level
-system related, then it should be only available on the main process. You need
+system related, then it should be only available in the main process. You need
 to be familiar with the concept of
 [main process vs. renderer process](../tutorial/quick-start.md#the-main-process)
 scripts to be able to use those modules.

docs/api/tray.md

@@ -123,7 +123,7 @@ Emitted when dragged files are dropped in the tray icon.
 
 The `Tray` module has the following methods:
 
-**Note**: Some methods are only available on specific operating systems and are
+**Note:** Some methods are only available on specific operating systems and are
 labeled as such.
 
 ### `Tray.destroy()`

docs/api/web-contents.md

@@ -427,13 +427,13 @@ win.webContents.on("did-finish-load", function() {
 
 * `path` String
 
-Adds the specified path to devtools workspace.
+Adds the specified path to DevTools workspace.
 
 ### `webContents.removeWorkSpace(path)`
 
 * `path` String
 
-Removes the specified path from devtools workspace.
+Removes the specified path from DevTools workspace.
 
 ### `webContents.send(channel[, args...])`
 
@@ -446,7 +446,7 @@ page can handle it by listening to the `channel` event of the `ipc` module.
 An example of sending messages from the main process to the renderer process:
 
 ```javascript
-// On the main process.
+// In the main process.
 var window = null;
 app.on('ready', function() {
   window = new BrowserWindow({width: 800, height: 600});
@@ -473,6 +473,6 @@ app.on('ready', function() {
 **Note:**
 
 1. The IPC message handler in web pages does not have an `event` parameter,
-   which is different from the handlers on the main process.
+   which is different from the handlers in the main process.
 2. There is no way to send synchronous messages from the main process to a
    renderer process, because it would be very easy to cause dead locks.

docs/api/web-view-tag.md

@@ -153,7 +153,7 @@ value will fail with a DOM exception.
 
 The `webview` tag has the following methods:
 
-**Note**: The webview element must be loaded before using the methods.
+**Note:** The webview element must be loaded before using the methods.
 
 **Example**
 ```javascript
@@ -260,15 +260,15 @@ user action, can take advantage of this option for automation.
 
 ### `<webview>.openDevTools()`
 
-Opens a devtools window for guest page.
+Opens a DevTools window for guest page.
 
 ### `<webview>.closeDevTools()`
 
-Closes the devtools window of guest page.
+Closes the DevTools window of guest page.
 
 ### `<webview>.isDevToolsOpened()`
 
-Returns a boolean whether guest page has a devtools window attached.
+Returns a boolean whether guest page has a DevTools window attached.
 
 ### `<webview>.inspectElement(x, y)`
 
@@ -279,7 +279,7 @@ Starts inspecting element at position (`x`, `y`) of guest page.
 
 ### `<webview>.inspectServiceWorker()`
 
-Opens the devtools for the service worker context present in the guest page.
+Opens the DevTools for the service worker context present in the guest page.
 
 ### `<webview>.setAudioMuted(muted)`
 

docs/styleguide.md

@@ -1,7 +1,7 @@
 # Electron Documentation Styleguide
 
-Find the appropriate section for your task: [reading Electron documentation](#)
-or [writing Electron documentation](#).
+Find the appropriate section for your task: [reading Electron documentation](#reading-electron-documentation)
+or [writing Electron documentation](#writing-electron-documentation).
 
 ## Writing Electron Documentation
 
@@ -25,6 +25,22 @@ These are the ways that we construct the Electron documentation.
 - Line length is 80-column wrapped.
 - Platform specific methods are noted in italics following method header.
  - ```### `method(foo, bar)` _OS X_```
+- Prefer 'in the ___ process' over 'on'
+
+### Documentation Translations
+
+Translations of the Electron docs are located within the `docs-translations`
+directory.
+
+To add another set (or partial set):
+
+- Create a subdirectory named by language abbreviation.
+- Within that subdirectory, duplicate the `docs` directory, keeping the
+  names of directories and files same.
+- Translate the files.
+- Update the `README.md` within your language directory to link to the files
+  you have translated.
+- Add a link to your translation directory on the main Electron [README](https://github.com/atom/electron#documentation-translations).
 
 ## Reading Electron Documentation
 

docs/tutorial/debugging-main-process.md

@@ -1,6 +1,6 @@
 # Debugging the Main Process
 
-The browser window devtools can only debug the renderer process scripts (i.e.
+The browser window DevTools can only debug the renderer process scripts (i.e.
 the web pages). In order to provide a way to debug the scripts from the main
 process, Electron has provided the `--debug` and `--debug-brk` switches.