I want do the translation for the atom docs, what should I do first? How to get started?

@ docs: "If you only want to invoke the callback when the next time the value changes..."

Proposed fix: removal ("If you only want to invoke the callback the next time the value changes...")

Example from https://atom.io/docs/latest/behind-atom-maintaining-your-packages#rename-your-package

Source

WARNING: Once a package name has been used, it cannot be re-used by another package even if the original package is unpublished.

PDF

asciidoc-preview

Web

https://atom.io/docs/v0.194.0/getting-started-atom-basics -- Section 1.3 under Opening, Modifying and Saving Files

Another way to open a file in Atom is from the command line. In the Atom menu bar there is a command named “Install Shell Commands” which installs a new command in your Terminal called atom. You can run this with one or more file paths to open up those files in Atom.

This seems to be included by default (at least in the Linux 0.194.0 .deb) and the menu item does not exist, which is misleading.

@ docs: "Of all the keybinding that are listed..."

Proposed: keybinding -> keybindings ("If you only want to invoke the callback the next time the value changes...")

Related file: https://github.com/atom/docs/blob/master/book/03-hacking-atom/sections/A01-debugging.asc

The Figure 1-1 link in https://atom.io/docs/v0.189.0/getting-started-installing-atom goes to https://atom.io/docs/v0.189.0/ , but IMHO it should be a URL fragment (a name preceded by a hash mark, which specifies an ID within the current document) that links to a(n) image/figure below (in this case, images/linux-downloads.png).

It seems that the link is actually https://atom.io/docs/v0.189.0/ch00/_download_button , but redirects (correct me if I'm wrong) me (or the browser) to https://atom.io/docs/v0.189.0/ .

I have tried Firefox 37.0, Google Chrome 41.0.2272.118, Opera 28.0.1750.48, and Safari 8.0.4 on OS X 10.10.2. This issue can be reproduced.

When I created the modifying text package in Chapter 3 on Ubuntu 12.04 with Node.js 0.12.7, figlet 1.0.8 (and 1.1.1) produced an error saying that the font o8 couldn't be found. It seems that figlet on Ubuntu needs the first letter of the font name to be capitalised: O8 works on Ubuntu whereas o8 doesn't.

I've created the modifying text package on Windows 7 and OS X Yosemite (both with Node.js 0.12.7 and figlet 1.0.8) and didn't get an error when I used the o8 font.

A simple fix for this is to change o8 to O8 in the example as O8 seems to work on all platforms.

When I visit https://atom.io/docs/v1.0.5/ I dont get any docs shown. https://atom.io/docs/v1.0.4/ however works fine.

Use major when you make a huge change, like a rewrite, or a large change to the functionality or interface. _Use minor when adding or removing a feature_. Use patch when you make a small change like a bug fix that does not add or remove features.

Check out semantic versioning to learn more about versioning your package releases.

Wait, removing a feature breaks backwards compatibility. People may be using that feature, you can't remove it in a minor version.

The Autocomplete section could use an update since Atom uses autocomplete-plus now.

The notes here are not super-discoverable (some users have trouble finding them) and would be neat to add this to the docs.

I am interested in contributing the TODOs like fixing the tests -( TODO: Fix the tests ) in 3.2 Package: Word Count . Can i take it up ?

I have been trying to use init.coffee, but couldn't find any information anywhere on how to use it.

This could be a useful addition to the flight manual.

The third chapter content will be structured as a series of increasingly complex cookbook like examples, each introducing a new API or Atom development feature. The end of the chapter will have an appendix which indexes the features and APIs covered by utility instead, so you can search for examples of specific types of functionality if you wish.

Here is the current model of the outline of the chapter.

• Cookbook
  • Word Count Package (Basic) #3
  • Word Count Status Bar (status bar manipulation)
  • Go To Line Package (simple with feedback and cursor movement)
  • Open On GitHub - (no UI, just run command)
  • Snippets - (modify text in a buffer)
  • Linter - (modify text in a buffer, shell to external command)
  • Preview Pane (add a panel)
  • Fuzzy Finder (modal and open file in new tab)
  • Tree View / Mini-map (add a sidebar panel)
  • Status Bar (add small panel)
  • Git-Log / Settings View (standalone UI in tab)
  • Git-status / Bookmarks (decorate gutter)
  • Autocomplete / Color picker (in-context UI)
  • Vim-mode (editor remapping)
  • Image View (file type rendering handler)
  • GitHub Markdown (language grammar)
  • Unity UI (UI theme)
• Advanced Dev Tools
• Maintaining Packages
• Best practices (patterns and anti-patterns)

We want to make sure to include examples of:

• scopes
• views / models
• settings
• notifications package
• config api
• subscriptions
• creating dom elements
• runners
• configure my package
• add application menu/context menu
• get all the editors
• understand when the active editor changes
• background tasks
• messages to the user
• dialogs
• advanced keymaps
• serialization
• converting textmate bundles
• decorations
• modal panel
• modal decorations
• notifications

This issue is sort of a master plan for the chapter, which will be implemented in multiple PRs.

What do you think of allowing the coffe code examples in the docs to be compiled on the fly to JS?

I did that once for a pet project and found that it was quite useful.

I think the following feature would also be needed:

• A toggle in the interface so that the user can select the output it prefer for the whole docs, the setting would be stored in a cookie and used on every pages to force the examples compilation on page load.
• As the JS output is not always the most beautiful one, maybe it could be useful to have a way to specify a JS example along the coffee one that will be used instead of compiling the coffee code.

I would love to have a plugin for Atom that perhaps even ships with Atom at some point that provides the latest version of this documentation directly in the editor. Similar to built-in Emacs and Vim docs that you can search through and read. It would ideally have a key shortcut that would bring up a search dialog or table of contents so you could either search through or browse the documentation offline.

According to this EPUB verification site there are errors in the EPUB file. I discovered this after I tried to upload it to my Google Play Books Library.

See this. Can probably be documented in this section.

#!/usr/bin/env python
# coding: utf-8

# The .epub url below should open a book in the iBooks app on an iPad but does not.
# The .mobi url below should open a book in the Kindle app on an iPad but does not.

import requests

url = 'http://atom.io/docs/v0.209.0'
html = requests.get(url).text
for line in html.splitlines():
    if 'eBook' in line:
        for clump in line.split():
            for word in clump.split('"'):
                if '://' in word:
                    print(word)

'''
http://orm-atlas2-prod.s3.amazonaws.com/epub/622e5c6754ecec37fa5d0b2695a5f831.epub
http://orm-atlas2-prod.s3.amazonaws.com/html/b530f4da9b9b47f512683d47966f1efd.zip
http://orm-atlas2-prod.s3.amazonaws.com/mobi/cbd8ff005dd780a14232095d079f8189.mobi
http://orm-atlas2-prod.s3.amazonaws.com/pdf/2d435d1a25f3cfda3471aaca5a1e2b5a.pdf
'''

Perhaps also related to issue #63

@ docs: To open a directory, choose "File >> Open"

Actually, "File >> Open Folder..." does the trick nowadays (v1.0.7)

Taken from atom/atom#6006: the docs say that user snippets are loaded from a snippets folder as well, but that doesn't seem to be true (they're loaded from the snippets.cson file only):

https://atom.io/docs/latest/using-atom-snippets#creating-your-own-snippets

There is also a directory called ~/.atom/snippets that you can fill with multiple json or cson files in the snippets format if you want to organize your snippets in a more coherent way.

cc @Enkouyami @thomasjo @mnquintana (folks from the issue in atom/atom)

If I click https://atom.io/docs/latest/contributing, browser redirects to https://atom.io/docs/v0.186.0/contributing

This is a tracking issue for all the things that need to be done to successfully open source this repository.

• Ship github/atom.io#798
• PR to remove existing docs/ folder from atom/atom and replace with redirect to atom/docs
• Script in atom/docs to pull, push to Atlas and publish (until Atlas can do it)

We should take the HTML output of the book and present it on Atom.io in place of the current Guides content.

This includes being able to version the documentation much like the current Guides are (1.0, 1.1, latest, etc). We should probably do this with branch names so universal updates or errata can be backported.

We'll also want to consider a multi-language approach so we can have /fr/1.1 or something.

There should probably only be the book/, theme/html/*.css and HTML files in this download (although for portability it might be nice if the CSS were inlined in the HTML files).

At one point there was a link to the apm/atom.io API on https://atom.io/docs. I can't seem to find it now after the shift to the new docs system. Can someone locate the link and add it to the main https://atom.io/docs page?

Ref: https://discuss.atom.io/t/private-apm-registries/16592

hi,

The atom.io website loads pages very slow, is there anything that can be done about that? It makes looking for documentation tedious.

Thanks!
Francois

This is a continuation of #86 where @rachelmyers.

To summarize: if you visit this page of the docs for version 1.0.1, then clicking the “Package: Word Count” link takes you to https://atom.io/docs/v1.0.1/ instead of to https://atom.io/docs/v1.0.1/hacking-atom-package-word-count, even though that page exists. This doesn't happen for version 1.0.0 nor 1.0.2.

The troubling part of all of this is -- there was no indication that something was broken neither when content-change PRs were merged in this repository nor when a new version of Atom was published. In other words -- we had no idea this happened or why until the issue was reported by a user. And that's scary because it might happen again.

@gjtorikian and I were looking into this a bit today, and this seems to be related to the redirection which happens when the link is clicked. In the version of the docs which has the described problem, the site redirects to the wrong location for some reason. This made us suspect that the site wasn't generated correctly and it wasn't a problem in the content in this repository. We also looked at the webhook deliveries to Atlas made to from this repository and noticed some 500 and 404 statuses, but not sure if this is related.

cc @schacon @thedaniel @benogle

https://github.com/atom/docs/blob/master/LICENSE.asc

The CC BY-NC-SA is not a free culture license. It is suggested to use CC BY-SA (or just CC BY, which makes sense since you're using the MIT license) instead. Like MIT, CC BY is also GPL-compatible.

This may eventually be problematic for inclusion in distribution repositories (like Debian).

For more information on why not to use non-commercial clauses, see: http://freedomdefined.org/Licenses/NC

Using a such a license also kind of a betrayal when saying this on the FAQ:

Is Atom open source?

Yes. Atom is MIT licensed and the source is freely available from the atom/atom repository.

All core Atom packages provided by GitHub are also available under the MIT license.

Set up automatic ebook builds from Atlas and auto-link the builds to atom.io documentation page.

It'd be nice to have an alphabetical list of terms in the documentation, with and/or without definitions. The list can be included as an appendix for the Atom Flight Manual, and we can link to the list here. To me, this kind of lists are often more useful than search engines because they are very selective, and search engines may miss relevant information if the information is not phrased in exactly the way I expect.

Here's an example for a list of terms with definitions: https://www.gnu.org/software/emacs/manual/html_node/emacs/Glossary.html#Glossary

Here's an example for a list of terms without definitions (but with links): https://www.gnu.org/software/emacs/manual/html_node/emacs/Concept-Index.html#Concept-Index

The HTML download contains links to toc.html, but there is no toc.html.

If I use the ePub, Kindle or PDF versions, I can search the documentation in their respective viewers. From the main documentation page, there is a search box that will allow me to search the Atom Flight Manual. But in the API documentation, there is a search box at the top of every page:

The same is not true for the Flight Manual:

I noticed that the usage of the command palette is not described correctly. Examples:

/getting-started-atom-basics
"To open the Settings screen ... You can also search for settings-view:open"
Here one should enter something like "settingsviewopen"

/getting-started-atom-basics
"... the tree-view:toggle command from the Palette ..."
One should enter "treeto" for example.

See: https://discuss.atom.io/t/why-isnt-doesnt-this-snippet-work/15922

This is a frustratingly common question, not just for snippets (though it comes up most commonly for snippets), but for any of the CSON configuration files.

In the docs, it currently says that you can move up and down with "ctrl+p" and "ctrl+n". But that doesn't work in atom out of the box:
"First of all, Atom ships with many of the basic Emacs keybindings for navigating a document. To go up and down a single character, you can use ctrl-P and ctrl-N."

See link (April 22, 2015):
https://atom.io/docs/latest/using-atom-moving-in-atom

Is this supposed to work? I am using Windows 7, 64bit.

In the Atom on Mac and Opening a File sections of the Atom Flight Manual, the text recommends installing the OS X command line utilities (atom and apm).

The latest version (1.0.2) installs atom and apm when Atom is first opened.

If this is the new default behaviour on OS X, should I update the docs to reflect this?

The screenshot of Settings View in this page is pretty old now. I think this image from the settings-view repo can be used to replace the current one.

I haven't find a new screenshot for ThemesPanel (https://atom.io/docs/v0.189.0/getting-started-atom-basics#changing-the-color-theme) yet.

See: atom/settings-view#554

Currently only the UI variables are listed, but not the syntax variables. Having also the syntax variables makes them more enforceable.

One bone of contention from users of platforms other than OS X is that key maps exclusively use Mac bindings. See https://discuss.atom.io/t/dumb-question-why-is-control-denoted-cmd-in-the-docs/10737 and linked posts.

In that topic I mention a system whereby the appropriate key binding for the OS of the viewer of the document could be determined. This might be complicated given that Atlas generates documentation for more than just the web (i.e. ePub, Kindle, PDF) but I did see plans to create multiple language versions of the documentation ... could we have a multivariate customized version? Like French for Windows or German for OS X?

Thoughts?

A few not-straigthforward things were highlighted in atom/atom#8226 :

• The order of operations is not clear between consuming services and activate
• How to deal with the unknown operations is confusing, and maybe difficult to come up with.

We should improve the docs to explain that there is no order of operations to be relied on, and have some examples on how to deal with that.

There are a two examples in the feedback package: consuming the status bar, and consuming the metrics reporter.

I haven't tried it on Kindle for other platforms.

Steps to Reproduce

1. Open a Terminal window
2. Follow the build instructions to generate the Mobi format
3. Enter open atom.mobi

Expected: Kindle for Mac to open and display the eBook
Actual: Kindle for Mac opens and pretty quickly closes again

Once the above is completed, the broken eBook is in your Kindle library:

1. Launch Kindle for Mac
2. Navigate to the Kindle Library
3. Click the Atom Flight Manual eBook

Expected: eBook opens
Actual: Kindle for Mac crashes

These Doc pages need updating.

• Atom Selections
• Editing and Deleting Text

Quit a few keybindings in the doc of atom.io are incorrect.

A best example is ctrl-shift-P which is false explained as "Select up".

Some other examples:

• ctrl-T: Transpose characters. In fact, fuzzy-finder:toggle-file-finder.
• alt-backspace: Delete to beginning of word. In fact, no such keybinding.
• cmd-shift-L: Convert a multi-line selection into multiple cursors. In fact, grammar-selector:show. (Note: I'm using Windows)

https://atom.io/docs/latest/getting-started-installing-atom#atom-on-windows

The best way to install Atom on Windows is by installing chocolatey, which you can get from https://chocolatey.org,

It would be awesome for API methods mentioned in prose to link to their API doc definitions. This has been a common workflow for me – I'll read along in the guide, hit a method, and wonder more specifically how it works and open a new tab to search for it in the API docs. This would just shorten that process a bit. 😄

From atom/atom#4420 and atom/atom#4420 (comment)

We should explicitly document the need to reach inside the Shadow DOM to style certain elements in styles.less.

For example, the introduction into Chapter 2 and the summary are in this file.

The HTML version generated locally using bundle exec rake book:build contains that content:

But the online version (on atom.io) doesn't -- the section is not clickable in the TOC:

cc @schacon @thedaniel @benogle for 💭

It'd be nice to have a troubleshooting section. For example, how to deal with errors in config/script/keymap/stylesheet/snippet files, how to start a clean Atom instance, what to do when/after Atom crashes, how to debug the problem (Atom is a hackable editor ;-), how to report a bug (link to the bug-report package, perhaps), etc. A link to The One True FAQ on Atom Discussion is helpful, too.

Without knowing too much about the asciidoc build process on Atlas, I'm wondering if it would be worth adding some basic CI support to prevent things like broken links, typos, and broken downloads / exports. Maybe we could run a test suite on Travis and test builds on Atlas to catch things like this before merging PRs?

/cc @atom/issue-triage @schacon