(docs) update docs for className -> scope change

highlightjs · Apr 21, 2021 · 0e8f0d2 · 0e8f0d2
1 parent a09887b
commit 0e8f0d2
Show file tree

Hide file tree

Showing 3 changed files with 75 additions and 46 deletions.
diff --git a/docs/css-classes-reference.rst b/docs/css-classes-reference.rst
@@ -1,22 +1,21 @@
-CSS classes reference
-=====================
+Scopes Reference
+================
 
 
-Stylable classes
+Stylable Scopes
 ----------------
 
-The general purpose classes are intended to be used for any language, but the
-other classes may also be used when they are semantically correct.  For example
-if you had a general purpose language that allowed inline URLs:
+The general purpose scopes are intended to be used for any language, but the
+other scopes may also be used when semantically correct.  For example if you had
+a general purpose language that allowed inline URLs:
 
 ::
 
   var GOOGLE = https://www.google.com/
 
-
 It would be reasonable to use the ``link`` class for this, even if your language
 is not a markup language.  However, many themes might not be designed with this
-in mind so a better choice might be ``string`` or perhaps ``string.link``.
+in mind so a better choice (for best theme support) might possibly be ``string``.
 
 +----------------------------------------------------------------------------------------+
 | **General purpose**                                                                    |
@@ -139,8 +138,8 @@ in mind so a better choice might be ``string`` or perhaps ``string.link``.
 | deletion                 | deleted line                                                |
 +--------------------------+-------------------------------------------------------------+
 
-A note on classes with sub-scopes
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A note on scopes with sub-scopes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Some scope names above have a ``.`` in them.  We use this notation to specify
 sub-scopes.  In the generated HTML this will output multiple computed class
@@ -170,25 +169,25 @@ A theme could then simply target that using the following CSS:
   }
 
 
-A note on newer classes
-^^^^^^^^^^^^^^^^^^^^^^^
+A note on newer scopes
+^^^^^^^^^^^^^^^^^^^^^^
 
-Some classes have been added more recently and do not enjoy universal theme
+Some scopes have been added more recently and do not enjoy universal theme
 support.  For themes without support, these items will simply not be
 highlighted.  This doesn't mean not to use them, only that they will be
 highlighted better as support improves over time.
 
-A list of these classes:
+A list of these scopes:
 
 - operator
 - punctuation
 - property
 
 
-Reserved classes
-^^^^^^^^^^^^^^^^
+Reserved scopes
+^^^^^^^^^^^^^^^
 
-The below classes (ReasonML) are left here for documentation purposes but may
+The below scopes (ReasonML) are left here for documentation purposes but may
 not be used in other grammars because they are very poorly supported by all
 themes.
 

diff --git a/docs/language-guide.rst b/docs/language-guide.rst
@@ -41,7 +41,7 @@ Here's an example:
     keywords: 'for if while',
     contains: [
       {
-        className: 'string',
+        scope: 'string',
         begin: '"', end: '"'
       },
       hljs.COMMENT(
@@ -50,7 +50,7 @@ Here's an example:
         {
           contains: [
             {
-              className: 'doc', begin: '@\\w+'
+              scope: 'doc', begin: '@\\w+'
             }
           ]
         }
@@ -135,7 +135,7 @@ This is commonly used to define nested modes:
 ::
 
   {
-    className: 'object',
+    scope: 'object',
     begin: /\{/, end: /\}/,
     contains: [hljs.QUOTE_STRING_MODE, 'self']
   }
@@ -170,11 +170,11 @@ Modes usually generate actual highlighting markup — ``<span>`` elements with s
   {
     contains: [
       {
-        className: 'string',
+        scope: 'string',
         // ... other attributes
       },
       {
-        className: 'number',
+        scope: 'number',
         // ...
       }
     ]
@@ -189,7 +189,7 @@ A classic example is an escaping sequence inside strings allowing them to contai
 ::
 
   {
-    className: 'string',
+    scope: 'string',
     begin: '"', end: '"',
     contains: [{begin: '\\\\.'}],
   }
@@ -220,7 +220,7 @@ So these string modes are given high relevance:
 ::
 
   {
-    className: 'string',
+    scope: 'string',
     begin: 'r"', end: '"',
     relevance: 10
   }
@@ -231,7 +231,7 @@ and it makes sense to bring their relevance to zero to lessen statistical noise:
 ::
 
   {
-    className: 'string',
+    scope: 'string',
     begin: '"', end: '"',
     relevance: 0
   }
@@ -267,7 +267,7 @@ Illegal symbols are defined using a single regular expression:
 ::
 
   {
-    className: 'class',
+    scope: 'class',
     illegal: '[${]'
   }
 

diff --git a/docs/mode-reference.rst b/docs/mode-reference.rst
@@ -9,9 +9,11 @@ Types
 Types of attributes values in this reference:
 
 +------------+-------------------------------------------------------------------------------------+
-| identifier | String suitable to be used as a JavaScript variable and CSS class name              |
+| identifier | String suitable to be used as a JavaScript variable or CSS class name               |
 |            | (i.e. mostly ``/[A-Za-z0-9_]+/``)                                                   |
 +------------+-------------------------------------------------------------------------------------+
+| scope      | A valid grammar scope: ``title.function.call``                                      |
++------------+-------------------------------------------------------------------------------------+
 | regexp     | String representing a JavaScript regexp.                                            |
 |            | Note that since it's not a literal regexp all back-slashes should be repeated twice |
 +------------+-------------------------------------------------------------------------------------+
@@ -60,7 +62,7 @@ classNameAliases
 
 - **type**: object
 
-A mapping table of any custom class names your grammar uses and their supported  equivalencies.  Perhaps your language has a concept of "slots" that roughly correspond to variables in other languages.  This allows you to write grammar code like:
+A mapping table of any custom scope names your grammar uses and their supported equivalencies.  Perhaps your language has a concept of "slots" that roughly correspond to variables in other languages.  This allows you to write grammar code like:
 
 ::
 
@@ -71,15 +73,15 @@ A mapping table of any custom class names your grammar uses and their supported
     },
     contains: [
       {
-        className: "slot",
+        scope: "slot",
         begin: // ...
       }
     ]
   }
 
-The final HTML output will render slots with the CSS class as ``hljs-variable``.  This feature exists to make it easier for grammar maintainers to think in their own language when maintaining a grammar.
+The final HTML output will render slots with a CSS class of ``hljs-variable``.  This feature exists to make it easier for grammar maintainers to think in their own language when maintaining a grammar.
 
-For a list of all supported class names please see the :doc:`CSS class reference
+For a list of all supported scope names please see the :doc:`Scopes Reference
 </css-classes-reference>`.
 
 
@@ -139,17 +141,33 @@ mode itself.
 Mode Attributes
 ---------------
 
-
 className
 ^^^^^^^^^
 
-- **type**: identifier
+- **type**: scope
+
+Deprecated with version 11.  Use ``scope`` instead.
+
 
-The name of the mode. It is used as a class name in HTML markup.
+scope
+^^^^^
+
+- **type**: scope
+
+The scope of a given mode. Scopes are converted to CSS class names in HTML markup.
 
-Multiple modes can have the same name. This is useful when a language has multiple variants of syntax
+Multiple modes can have the same scope. This is useful when a language has multiple variants of syntax
 for one thing like string in single or double quotes.
 
+::
+
+  {
+    scope: "title.function.call",
+    begin: /[a-z]+\(/
+  }
+
+
+See :doc:`scopes reference</css-classes-reference>` for details on scopes and CSS classes.
 
 begin
 ^^^^^
@@ -160,7 +178,7 @@ Regular expression starting a mode. For example a single quote for strings or tw
 If absent, ``begin`` defaults to a regexp that matches anything, so the mode starts immediately.
 
 
-You can also pass an array when you need to individually highlight portions of the match with different classes:
+You can also pass an array when you need to individually highlight portions of the match using different scopes:
 
 ::
 
@@ -170,7 +188,7 @@ You can also pass an array when you need to individually highlight portions of t
     /\s+/,
     hljs.IDENT_RE
   ],
-  className: {
+  scope: {
     1: "keyword",
     3: "title"
   },
@@ -202,10 +220,19 @@ no sense).  It exists simply to help make grammars more readable.
 ::
 
   {
-    className: "title",
+    scope: "title",
     match: /Fish/
   }
 
+This is equivalent to:
+
+::
+
+  {
+    scope: "title",
+    begin: /Fish/
+  }
+
 
 on:begin
 ^^^^^^^^
@@ -303,9 +330,9 @@ This is when ``endsWithParent`` comes into play:
 ::
 
   {
-    className: 'rules', begin: /\{/, end: /\}/,
+    scope: 'rules', begin: /\{/, end: /\}/,
     contains: [
-      {className: 'rule', /* ... */ end: ';', endsWithParent: true}
+      {scope: 'rule', /* ... */ end: ';', endsWithParent: true}
     ]
   }
 
@@ -339,11 +366,11 @@ tell it to end the function definition after itself:
 ::
 
   {
-    className: 'function',
+    scope: 'function',
     beginKeywords: 'def', end: /\B\b/,
     contains: [
       {
-        className: 'title',
+        scope: 'title',
         begin: hljs.IDENT_RE, endsParent: true
       }
     ]
@@ -461,7 +488,7 @@ Modification to the main definitions of the mode, effectively expanding it into
 each having all the attributes from the main definition augmented or overridden by the variants::
 
   {
-    className: 'string',
+    scope: 'string',
     contains: ['self', hljs.BACKSLASH_ESCAPE],
     relevance: 0,
     variants: [
@@ -477,8 +504,8 @@ does not allow for this.
 
 The variants are compiled into to two *discrete* modes::
 
-  { className: 'string', begin: /"/, contains: ['self', ... ] }
-  { className: 'string', begin: /'/, contains: ['self', ... ] }
+  { scope: 'string', begin: /"/, contains: ['self', ... ] }
+  { scope: 'string', begin: /'/, contains: ['self', ... ] }
 
 Each mode's ``self`` refers only to the new expanded mode, not the original mode
 with variants (which no longer exists after compiling).
@@ -496,7 +523,10 @@ subLanguage
 
 Highlights the entire contents of the mode with another language.
 
-When using this attribute there's no point to define internal parsing rules like :ref:`lexemes` or :ref:`keywords`. Also it is recommended to skip ``className`` attribute since the sublanguage will wrap the text in its own ``<span class="language-name">``.
+When using this attribute there's no point to define internal parsing rules like
+:ref:`keywords`, etc. Also it is recommended to avoid the ``scope`` attribute
+since the sublanguage already wraps the text in its own ``<span
+class="language-name">`` tag.
 
 The value of the attribute controls which language or languages will be used for highlighting: