From b797804fd92a3bed68223f63434ed3d63ba0f349 Mon Sep 17 00:00:00 2001 From: Jessica Lord Date: Fri, 4 Sep 2015 13:44:40 -0700 Subject: [PATCH 1/7] Use "in" over "on" --- docs/api/auto-updater.md | 2 +- docs/api/power-monitor.md | 2 +- docs/api/synopsis.md | 4 ++-- docs/api/web-contents.md | 4 ++-- docs/styleguide.md | 1 + 5 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/api/auto-updater.md b/docs/api/auto-updater.md index 3901e1be2062..9734f592c8fe 100644 --- a/docs/api/auto-updater.md +++ b/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()); diff --git a/docs/api/power-monitor.md b/docs/api/power-monitor.md index c9a33cc1a128..6ffb910e164d 100644 --- a/docs/api/power-monitor.md +++ b/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: diff --git a/docs/api/synopsis.md b/docs/api/synopsis.md index 21f4ff2aa4de..85d9e3f8dfa6 100644 --- a/docs/api/synopsis.md +++ b/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. diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md index 89afae43d1c0..c49b64743bed 100644 --- a/docs/api/web-contents.md +++ b/docs/api/web-contents.md @@ -445,7 +445,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}); @@ -472,6 +472,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. diff --git a/docs/styleguide.md b/docs/styleguide.md index 23c590e64211..687b5c4dea3e 100644 --- a/docs/styleguide.md +++ b/docs/styleguide.md @@ -25,6 +25,7 @@ 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' ## Reading Electron Documentation From b9da81ee6ac7114dbc10992a284b0225ded2c7c7 Mon Sep 17 00:00:00 2001 From: Jessica Lord Date: Fri, 4 Sep 2015 13:50:26 -0700 Subject: [PATCH 2/7] Title Case --- docs/README.md | 56 +++++++++++++++++++++++++------------------------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/docs/README.md b/docs/README.md index 5d6d825d1bcb..4531c1d2a236 100644 --- a/docs/README.md +++ b/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) -* [`` tag](api/web-view-tag.md) -* [`window.open` function](api/window-open.md) +* [`File` Object](api/file-object.md) +* [`` 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) From b980650b6e1f139d86a09c3c0055517b3a630002 Mon Sep 17 00:00:00 2001 From: Jessica Lord Date: Fri, 4 Sep 2015 14:31:33 -0700 Subject: [PATCH 3/7] Use headers so titles are linkable --- docs/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/README.md b/docs/README.md index 4531c1d2a236..b2f95fe4b579 100644 --- a/docs/README.md +++ b/docs/README.md @@ -20,13 +20,13 @@ * [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) * [`` 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) @@ -44,13 +44,13 @@ Modules for the Main Process: * [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) From ce49bba2fc36d3d99ac28066beda4ca0af88f497 Mon Sep 17 00:00:00 2001 From: Jessica Lord Date: Wed, 9 Sep 2015 13:32:56 -0700 Subject: [PATCH 4/7] Add section links --- docs/styleguide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/styleguide.md b/docs/styleguide.md index 687b5c4dea3e..d02b7f56861f 100644 --- a/docs/styleguide.md +++ b/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 From e9712e2998a78001998c4ca66fd4f58f80f59677 Mon Sep 17 00:00:00 2001 From: Jessica Lord Date: Wed, 9 Sep 2015 13:33:11 -0700 Subject: [PATCH 5/7] Add section on documentation translations --- CONTRIBUTING.md | 1 + docs/styleguide.md | 15 +++++++++++++++ 2 files changed, 16 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 61a8e474099a..516f6289ac0f 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/docs/styleguide.md b/docs/styleguide.md index d02b7f56861f..77c90467ca93 100644 --- a/docs/styleguide.md +++ b/docs/styleguide.md @@ -27,6 +27,21 @@ These are the ways that we construct the Electron documentation. - ```### `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 Here are some tips for understanding Electron documentation syntax. From 279fd0a4610afc6691ab16f0341e3b8f63a998c2 Mon Sep 17 00:00:00 2001 From: Jessica Lord Date: Wed, 9 Sep 2015 14:09:14 -0700 Subject: [PATCH 6/7] Standardize **Note:** --- docs/api/app.md | 2 +- docs/api/browser-window.md | 4 ++-- docs/api/global-shortcut.md | 2 +- docs/api/ipc-renderer.md | 4 ++-- docs/api/native-image.md | 2 +- docs/api/remote.md | 2 +- docs/api/screen.md | 2 +- docs/api/tray.md | 2 +- docs/api/web-view-tag.md | 2 +- 9 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/api/app.md b/docs/api/app.md index 07b26f2c5663..42a5dfc24249 100644 --- a/docs/api/app.md +++ b/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()` diff --git a/docs/api/browser-window.md b/docs/api/browser-window.md index e9d2c7f6feb8..53a9487733b7 100644 --- a/docs/api/browser-window.md +++ b/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' @@ -292,7 +292,7 @@ Remove the devtools extension whose name is `name`. 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'); diff --git a/docs/api/global-shortcut.md b/docs/api/global-shortcut.md index f9ca654cf50a..adba06e1adcf 100644 --- a/docs/api/global-shortcut.md +++ b/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. diff --git a/docs/api/ipc-renderer.md b/docs/api/ipc-renderer.md index 3adb0bc95476..752af2ebe293 100644 --- a/docs/api/ipc-renderer.md +++ b/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][, ...])` diff --git a/docs/api/native-image.md b/docs/api/native-image.md index c00ec3a9458a..df2bb96ff9da 100644 --- a/docs/api/native-image.md +++ b/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: diff --git a/docs/api/remote.md b/docs/api/remote.md index ccb16b4b3cc3..5a048fc0789f 100644 --- a/docs/api/remote.md +++ b/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 diff --git a/docs/api/screen.md b/docs/api/screen.md index c22530ca8d0a..934e3eaf5a70 100644 --- a/docs/api/screen.md +++ b/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. diff --git a/docs/api/tray.md b/docs/api/tray.md index a673307804a7..528705acb325 100644 --- a/docs/api/tray.md +++ b/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()` diff --git a/docs/api/web-view-tag.md b/docs/api/web-view-tag.md index 6b64a0269c52..1d49a3db130c 100644 --- a/docs/api/web-view-tag.md +++ b/docs/api/web-view-tag.md @@ -135,7 +135,7 @@ If "on", the guest page will have web security disabled. 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 From c29a2e4992f6dc063abdb847502790436439b1ba Mon Sep 17 00:00:00 2001 From: Jessica Lord Date: Wed, 9 Sep 2015 14:11:06 -0700 Subject: [PATCH 7/7] Standardize DevTools --- docs/api/browser-window.md | 16 ++++++++-------- docs/api/web-contents.md | 4 ++-- docs/api/web-view-tag.md | 8 ++++---- docs/tutorial/debugging-main-process.md | 2 +- 4 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/api/browser-window.md b/docs/api/browser-window.md index 53a9487733b7..289f96cd21ea 100644 --- a/docs/api/browser-window.md +++ b/docs/api/browser-window.md @@ -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,7 +286,7 @@ 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 @@ -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. diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md index c49b64743bed..7324b6b17976 100644 --- a/docs/api/web-contents.md +++ b/docs/api/web-contents.md @@ -426,13 +426,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...])` diff --git a/docs/api/web-view-tag.md b/docs/api/web-view-tag.md index 1d49a3db130c..a61625023bff 100644 --- a/docs/api/web-view-tag.md +++ b/docs/api/web-view-tag.md @@ -242,15 +242,15 @@ user action, can take advantage of this option for automation. ### `.openDevTools()` -Opens a devtools window for guest page. +Opens a DevTools window for guest page. ### `.closeDevTools()` -Closes the devtools window of guest page. +Closes the DevTools window of guest page. ### `.isDevToolsOpened()` -Returns a boolean whether guest page has a devtools window attached. +Returns a boolean whether guest page has a DevTools window attached. ### `.inspectElement(x, y)` @@ -261,7 +261,7 @@ Starts inspecting element at position (`x`, `y`) of guest page. ### `.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. ### `.setAudioMuted(muted)` diff --git a/docs/tutorial/debugging-main-process.md b/docs/tutorial/debugging-main-process.md index f4e345a2f3a5..38c6e61ffcde 100644 --- a/docs/tutorial/debugging-main-process.md +++ b/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.