<p dir="auto">Via <a class="issue-link js-issue-link" data-error-text="Failed to load title" data-id="29180011" data-permission-text="Title is private" data-url="https://github.com/atom/atom-dark-ui/issues/19" data-hovercard-type="issue" data-hovercard-url="/atom/atom-dark-ui/issues/19/hovercard" href="https://github.com/atom/atom-dark-ui/issues/19">atom/atom-dark-ui#19</a></p>
<blockquote>
<p dir="auto">Currently it's quite easy to change the background colors for selections.</p>
<div class="snippet-clipboard-content notranslate position-relative overflow-auto" data-snippet-clipboard-copy-content=".selection .region { background-color: @red }"><pre class="notranslate"><code class="notranslate">.selection .region { background-color: @red }
</code></pre></div>
<p dir="auto">But it seems to be impossible to change the foreground color, due to the fact that the <code class="notranslate">selection</code> container simply overlays the text, and does nothing to change the actual <code class="notranslate">.line</code> element containing the text. (see screenshot)</p>
<p dir="auto"><a target="_blank" rel="noopener noreferrer nofollow" href="https://camo.githubusercontent.com/6279c1562f2ef216a0f58c0f11c58c438663716802bca9eb82beaed7ffa438ee/68747470733a2f2f662e636c6f75642e6769746875622e636f6d2f6173736574732f3433303837352f323338353934342f30353931303032342d613932352d313165332d393439652d6138353666633665353434392e706e67"><img src="https://camo.githubusercontent.com/6279c1562f2ef216a0f58c0f11c58c438663716802bca9eb82beaed7ffa438ee/68747470733a2f2f662e636c6f75642e6769746875622e636f6d2f6173736574732f3433303837352f323338353934342f30353931303032342d613932352d313165332d393439652d6138353666633665353434392e706e67" alt="screen shot 2014-03-11 at 14 55 11" data-canonical-src="https://f.cloud.github.com/assets/430875/2385944/05910024-a925-11e3-949e-a856fc6e5449.png" style="max-width: 100%;"></a></p>
</blockquote>
<p dir="auto">This is another stab at <a class="issue-link js-issue-link" data-error-text="Failed to load title" data-id="38760504" data-permission-text="Title is private" data-url="https://github.com/atom/api/issues/6" data-hovercard-type="pull_request" data-hovercard-url="/atom/api/pull/6/hovercard" href="https://github.com/atom/api/pull/6">atom/api#6</a>, but in more concrete terms of guides / docs I think we should write to place on atom.io.</p>
<p dir="auto">Many of the APIs these rely on are very in flux at the moment, though, so we'll probably need to write them near or after the API freeze.</p>
<h2 dir="auto">Bit of background: links to problems / talk about package writing</h2>
<ul dir="auto">
<li><a href="http://gnuu.org/2014/03/10/my-week-with-githubs-atom-editor/" rel="nofollow">http://gnuu.org/2014/03/10/my-week-with-githubs-atom-editor/</a></li>
<li><a href="https://discuss.atom.io/t/how-to-speed-up-your-packages/10903" rel="nofollow">https://discuss.atom.io/t/how-to-speed-up-your-packages/10903</a></li>
<li><a href="https://discuss.atom.io/t/looking-for-best-practices-for-iterative-development-on-atom/10889" rel="nofollow">https://discuss.atom.io/t/looking-for-best-practices-for-iterative-development-on-atom/10889</a></li>
</ul>
<h2 dir="auto">Guides We Should Write</h2>
<h3 dir="auto">Events</h3>
<p dir="auto">Events seem to be the number one issue folks have with the API. There is confusion around</p>
<ul dir="auto">
<li>Which classes produce which events?</li>
<li>What is the difference between events and commands?</li>
<li>What is a subscription object?</li>
<li>Subscribe? on? which one? Where am I? It's dark in here!</li>
</ul>
<p dir="auto">This guide (and new APIs!) should address these things.</p>
<h3 dir="auto">Serialization</h3>
<ul dir="auto">
<li>WTF is it?</li>
<li>How does it work?</li>
<li>How to use it?</li>
</ul>
<h3 dir="auto">Inter-package communication</h3>
<p dir="auto">(API needs to be written!)</p>
<ul dir="auto">
<li>How to use</li>
<li>Best practices</li>
</ul>
<h3 dir="auto">Testing your package</h3>
<ul dir="auto">
<li>Setting it up</li>
<li>Best practices</li>
</ul>
<h3 dir="auto">Grammar scopes</h3>
<p dir="auto">Creating a language package? A syntax theme? It's impossible to know what scopes to generate / select for in common cases. What are the scopes for a function? Punctuation? Class names? I have no idea. Currently, the only way to know what to do is to look through several other lang packages and themes to get an idea of the scopes involved.</p>
<h3 dir="auto">Decorations</h3>
<p dir="auto">Currently the best docs are the example package and the blog post.</p>
<h2 dir="auto">List of cookbooks / recipes</h2>
<p dir="auto">Cookbooks / Recipes (have not decided on naming) are small snippets that solve a specific problem. Often package authors (and me!) want to know "how do I do That Common Thing that I saw in package Y". They can also be an entry point into a related guide.</p>
<p dir="auto">This list should be exhaustive. If you have ideas, let me know and I will add them.</p>
<ul dir="auto">
<li>Observing all the editors</li>
<li>Observing the active editor / pane item</li>
<li>Adding a pane item in a tab (like settings view)</li>
<li>Adding a panel (like find and replace)</li>
<li>Subscribing to a command</li>
<li>Highlighting a line / gutter-number (decoration)</li>
<li>Adding something to the status bar</li>
<li>How to get user input (like jump to line)</li>
<li>How to display a filterable list in a dialog (like command palette)</li>
</ul>
<h2 dir="auto">Changes we should make to existing guides</h2>
<h3 dir="auto">In <a href="https://atom.io/docs/latest/creating-a-package" rel="nofollow">Creating a package</a></h3>
<ul dir="auto">
<li>This could provide more of an overview and be the entry point / index into other guides (like the one on events or serialization).</li>
<li>Section about activation events</li>
</ul>
<h2 dir="auto">Less concrete ideas for guides</h2>
<p dir="auto">Here are some ideas from <a class="issue-link js-issue-link" data-error-text="Failed to load title" data-id="38760504" data-permission-text="Title is private" data-url="https://github.com/atom/api/issues/6" data-hovercard-type="pull_request" data-hovercard-url="/atom/api/pull/6/hovercard" href="https://github.com/atom/api/pull/6">atom/api#6</a> and from the summit that are less fleshed out.</p>
<ul dir="auto">
<li>Making your package fast: common pitfalls</li>
<li>Debugging your package</li>
<li>Package manager guide</li>
<li>Theme manager</li>
<li>Syntax/Grammar</li>
<li>Editor</li>
<li>Workspace/Panes</li>
<li>apm</li>
<li>~/.atom</li>
<li>cross-platform</li>
<li>dependency management in packages (where do I get the things I need?)</li>
</ul>
<h2 dir="auto">Updates</h2>
<p dir="auto">Writing these is getting closer, so I will be updating the body of this issue as comments roll in and we think of things.</p>