From 67eeb8d17d9db3164ec9ad6fd17e770cb24040c8 Mon Sep 17 00:00:00 2001 From: chbk Date: Sat, 21 Sep 2019 07:01:09 +0200 Subject: [PATCH 1/5] Add a "Syntax Naming Conventions" section --- .../sections/syntax-naming-conventions.md | 712 ++++++++++++++++++ data/toc.yml | 1 + 2 files changed, 713 insertions(+) create mode 100644 content/hacking-atom/sections/syntax-naming-conventions.md 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 From 80c6f6405c9382df8054db8068bb324076ee8de7 Mon Sep 17 00:00:00 2001 From: chbk Date: Mon, 1 Feb 2021 14:56:30 +0100 Subject: [PATCH 2/5] Add CSS rules for the
tag --- assets/stylesheets/app/_flight_manual.scss | 32 ++++++++++++++++++++++ 1 file changed, 32 insertions(+) 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; From ec58150233a6f20bd71df888a381db118c4e8ec7 Mon Sep 17 00:00:00 2001 From: chbk Date: Mon, 1 Feb 2021 15:02:55 +0100 Subject: [PATCH 3/5] Update syntax classes in "Creating a Grammar" --- .../sections/creating-a-grammar.md | 50 +++++++++++-------- 1 file changed, 30 insertions(+), 20 deletions(-) diff --git a/content/hacking-atom/sections/creating-a-grammar.md b/content/hacking-atom/sections/creating-a-grammar.md index d2dda0fdbe..a095acbf80 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`. 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'}, ] ``` From d0a3a3a0c477ce22c1c0f94d599b1516aeb758b0 Mon Sep 17 00:00:00 2001 From: chbk Date: Mon, 1 Feb 2021 15:03:48 +0100 Subject: [PATCH 4/5] Add link to "Syntax Naming Conventions" in "Creating a Grammar" --- content/hacking-atom/sections/creating-a-grammar.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/hacking-atom/sections/creating-a-grammar.md b/content/hacking-atom/sections/creating-a-grammar.md index a095acbf80..164479ec72 100644 --- a/content/hacking-atom/sections/creating-a-grammar.md +++ b/content/hacking-atom/sections/creating-a-grammar.md @@ -90,7 +90,7 @@ scopes: '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--function`, and `syntax--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--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. From 05679be7d47404f4a5ba651dadc223ef9a365bae Mon Sep 17 00:00:00 2001 From: chbk Date: Mon, 1 Feb 2021 15:04:46 +0100 Subject: [PATCH 5/5] Update template theme paths in "Creating a Theme" --- content/hacking-atom/sections/creating-a-theme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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`.