diff --git a/assets/stylesheets/app/_flight_manual.scss b/assets/stylesheets/app/_flight_manual.scss index 5603493fe6..fb5092159f 100644 --- a/assets/stylesheets/app/_flight_manual.scss +++ b/assets/stylesheets/app/_flight_manual.scss @@ -516,6 +516,38 @@ h1.document-title { } } + details { + &:not([open]) summary { + cursor: pointer; + } + + summary:focus { + outline: none; + } + + ul { + margin-top: 9px; + } + + li { + margin-bottom: 9px; + } + + > ul { + margin-left: 12px; + } + + > br, + ul > br, + li > br:last-of-type { + display: none; + } + + strong code { + color: #00AA88; + } + } + pre.highlight { color: $codeTextColor; background: $codeBgColor; diff --git a/content/hacking-atom/sections/creating-a-grammar.md b/content/hacking-atom/sections/creating-a-grammar.md index d2dda0fdbe..164479ec72 100644 --- a/content/hacking-atom/sections/creating-a-grammar.md +++ b/content/hacking-atom/sections/creating-a-grammar.md @@ -87,10 +87,10 @@ Here is a simple example: ```coffee scopes: - 'call_expression > identifier': 'entity.name.function' + 'call_expression > identifier': 'entity.function.call' ``` -This entry means that, in the syntax tree, any `identifier` node whose parent is a `call_expression` should be highlighted using three classes: `syntax--entity`, `syntax--name`, and `syntax--function`. +This entry means that, in the syntax tree, any `identifier` node whose parent is a `call_expression` should be highlighted using three classes: `syntax--entity`, `syntax--function`, and `syntax--call`. For a list of conventional classes, see the [Syntax Naming Conventions](../syntax-naming-conventions/) section. Note that in this selector, we're using the [immediate child combinator](https://developer.mozilla.org/en-US/docs/Web/CSS/Child_selectors) (`>`). Arbitrary descendant selectors without this combinator (for example `'call_expression identifier'`, which would match any `identifier` occurring anywhere within a `call_expression`) are currently not supported. @@ -104,14 +104,14 @@ scopes: function_declaration > identifier, call_expression > identifier, call_expression > field_expression > field_identifier - ''': 'entity.name.function' + ''': 'entity.function' ``` You can use the [`:nth-child` pseudo-class](https://developer.mozilla.org/en-US/docs/Web/CSS/:nth-child) to select nodes based on their order within their parent. For example, this example selects `identifier` nodes which are the fourth (zero-indexed) child of a `singleton_method` node. ```coffee scopes: - 'singleton_method > identifier:nth-child(3)': 'entity.name.function' + 'singleton_method > identifier:nth-child(3)': 'entity.function' ``` Finally, you can use double-quoted strings in the selectors to select *anonymous* tokens in the syntax tree, like `(` and `:`. See [the Tree-sitter documentation](http://tree-sitter.github.io/tree-sitter/using-parsers#named-vs-anonymous-nodes) for more information about named vs anonymous tokens. @@ -123,7 +123,7 @@ scopes: "/", "+", "-" - ''': 'keyword.operator' + ''': 'keyword.operator.arithmetic.symbolic' ``` ##### Text-based Mappings @@ -133,21 +133,31 @@ You can also apply different classes to a syntax node based on its text. Here ar ```coffee scopes: - # Apply the classes `syntax--builtin` and `syntax--variable` to all - # `identifier` nodes whose text is `require`. - 'identifier': {exact: 'require', scopes: 'builtin.variable'}, + # Apply the classes `syntax--entity`, `syntax--function`, and + # `syntax--support` to all `identifier` nodes whose text is `require`. + 'identifier': { + exact: 'require', + scopes: 'entity.function.support' + }, - # Apply the classes `syntax--type` and `syntax--integer` to all - # `primitive_type` nodes whose text starts with `int` or `uint`. - 'primitive_type': {match: /^u?int/, scopes: 'type.integer'}, + # Apply the classes `syntax--entity`, `syntax--type`, `syntax--fundamental`, + # and `syntax--integer` to all `primitive_type` nodes whose text starts + # with `int` or `uint`. + 'primitive_type': { + match: /^u?int/, + scopes: 'entity.type.fundamental.integer' + }, - # Apply the classes `syntax--builtin`, `syntax--class`, and - # `syntax--name` to `constant` nodes with the text `Array`, - # `Hash` and `String`. For all other `constant` nodes, just - # apply the classes `syntax--class` and `syntax--name`. + # Apply the classes `syntax--entity`, `syntax--type`, `syntax--class`, and + # `syntax--support` to `constant` nodes with the text `Array`, `Hash` or + # `String`. For other `constant` nodes, apply the classes `syntax--entity`, + # `syntax--type`, and `syntax--class`. 'constant': [ - {match: '^(Array|Hash|String)$', scopes: 'builtin.class.name'}, - 'class.name' + { + match: '^(Array|Hash|String)$', + scopes: 'entity.type.class.support' + }, + 'entity.type.class' ] ``` @@ -164,15 +174,15 @@ If multiple selectors in the `scopes` object match a node, the node's classes wi ```coffee scopes: - 'call_expression > identifier': 'entity.name.function' + 'call_expression > identifier': 'entity.function' # If we did not include the second selector here, then this rule # would not apply to identifiers inside of call_expressions, # because the selector `call_expression > identifier` is more # specific than the selector `identifier`. 'identifier, call_expression > identifier': [ - {exact: 'require', scopes: 'builtin.variable'}, - {match: '^[A-Z]', scopes: 'constructor'}, + {exact: 'require', scopes: 'entity.function.support'}, + {match: '^[A-Z]', scopes: 'entity.type.constructor'}, ] ``` diff --git a/content/hacking-atom/sections/creating-a-theme.md b/content/hacking-atom/sections/creating-a-theme.md index a5dd9fa865..40f871b332 100644 --- a/content/hacking-atom/sections/creating-a-theme.md +++ b/content/hacking-atom/sections/creating-a-theme.md @@ -36,7 +36,7 @@ Atom will display a new window, showing the motif-syntax theme, with a default s Open up `styles/colors.less` to change the various color variables which have already been defined. For example, turn `@red` into `#f4c2c1`. -Then open `styles/base.less` and modify the various selectors that have already been defined. These selectors style different parts of code in the editor such as comments, strings and the line numbers in the gutter. +Then open `styles/editor.less` and `styles/syntax.less` and modify the various selectors that have already been defined. These selectors style different parts of code in the editor such as keywords, strings, and the line numbers in the gutter. As an example, let's make the `.gutter` `background-color` into `@red`. diff --git a/content/hacking-atom/sections/syntax-naming-conventions.md b/content/hacking-atom/sections/syntax-naming-conventions.md new file mode 100644 index 0000000000..383b674be1 --- /dev/null +++ b/content/hacking-atom/sections/syntax-naming-conventions.md @@ -0,0 +1,712 @@ +--- +title: Syntax Naming Conventions +--- + +### Syntax Naming Conventions + +Naming conventions provide predefined names for similar tokens in different languages. These language-agnostic names, called syntax classes, help themes highlight code without relying on language-specific vocabulary. + +When creating a language grammar, use these conventions to determine which syntax classes correspond to your syntax nodes. When creating a syntax theme, use these conventions to determine which syntax classes correspond to your theme colors. + +#### Guidelines for Language Grammars + +The syntax classes are organized into nested categories. In a language grammar, multiple nested classes can be applied to a syntax node by appending them with periods, as in `entity.function.call`. The order in which classes are appended does not affect the resulting highlighting. However, we recommend following their hierarchy to stay consistent. + +Root classes, like `▶ entity`, must not be appended to other root classes, unless explicitly allowed in this documentation. Main classes indicated in bold green, like __function__, must be used for coherent highlighting. Shared classes indicated in brackets, like `[call]`, can be appended when relevant. You may create additional classes if they clarify your grammar and do not introduce conflicts with existing classes. + +#### Guidelines for Syntax Themes + +In a syntax theme, styling can be applied to a syntax class with the `syntax--` prefix, as in `syntax--entity`. When targeting a nested class, specify its parent classes by prepending them with periods, as in `syntax--entity.syntax--function.syntax--call`. A typical styling rule would look like this: + +```css +.syntax--entity.syntax--function.syntax--call { + color: blue; +} +``` + +#### List of Syntax Classes + +Click on root classes to reveal more nested classes. + +
+ __`keyword`__ — A keyword. + +
+
+ __`entity`__ — An identifier. + +
+
+ __`string`__ — A string or part of a string. + +
+
+ __`constant`__ — A literal other than a string. + +
+
+ __`text`__ — Plain text. +
+
+ __`markup`__ — Stylized text. + +
+
+ __`comment`__ — A comment or part of a comment. Includes comments in strings. + +
+
+ __`punctuation`__ — A punctuation mark. + +
+
+ `[invalid]` — An invalid token. Appendable to every class. + +
+
+ `meta` — A larger part of the document encompassing multiple tokens. + +
diff --git a/data/toc.yml b/data/toc.yml index 3c7727fef0..c21f0cefe7 100644 --- a/data/toc.yml +++ b/data/toc.yml @@ -32,6 +32,7 @@ Chapters: - Creating a Theme - Creating a Grammar - Creating a Legacy TextMate Grammar + - Syntax Naming Conventions - Publishing - Iconography - Debugging