README.txt in Syntax Highlighter 8

INSTALLATION
------------

Step 1) Download the latest SyntaxHighlighter Javascript library from
http://alexgorbatchev.com/SyntaxHighlighter/, extract the contents, rename the
directory to "syntaxhighlighter" and place the entire directory in any of the
locations supported by the libraries module, relative to the web site root,
e.g.:

  -  libraries
       Recommended. This is Drupal 8 standard location for third party
       libraries.

  -  sites/[sitename]/libraries
       Recommended if this library is to be site specific.

  -  profiles/[profilename]/libraries
       Recommended if this library is to be profile specific.

  -  Inside the syntaxhighlighter module directory
       This is not recommended. It's only for backward compatibility.


After the installation, there should be something like this:

  libraries/syntaxhighlighter/...

so that shCore.js is located at:

  libraries/syntaxhighlighter/scripts/shCore.js

Note: To use the toolbar with options to view source and the flash-based copy
to clipboard, the older 2.x version needs to be used

See http://alexgorbatchev.com/SyntaxHighlighter/ for details.

WARNING! The library location is determined by file scan. This scan is
performed only once and the location is cached. If the library location is
changed for any reason (such as after upgrading the js lib) the cache must be
invalidated in some way (drush, drupal-console, etc.).


AUTOMATIC INSTALLATION
----------------------

The SyntaxHighlighter Javascript library can be installed automatically with
composer by setting up a repository for it in the main composer.json of the
web project.

Here follows an example of usage with drupal-composer/drupal-project: the
"syntaxhighlighter/syntaxhighlighter" repository would go in the main
composer.json, where also the "drupal/syntaxhighlighter" dependency will be
specified, like this:

diff --git a/composer.json b/composer.json
index 28023b4..3a6bab2 100644
--- a/composer.json
+++ b/composer.json
@@ -13,6 +13,25 @@
         {
             "type": "composer",
             "url": "https://packages.drupal.org/8"
+        },
+        {
+            "type": "package",
+            "package": {
+                "name": "syntaxhighlighter/syntaxhighlighter",
+                "description": "...",
+                "type": "drupal-library",
...
+            }
         }
     ],
     "require": {
@@ -21,6 +40,7 @@
         "drupal-composer/drupal-scaffold": "^2.2",
         "drupal/console": "~1.0",
         "drupal/core": "~8.0",
+        "drupal/syntaxhighlighter": "*",
         "drush/drush": "~8.0",
         "webflo/drupal-finder": "^0.3.0",
         "webmozart/path-util": "^2.3"


Setting "type": "drupal-library" for the "syntaxhighlighter/syntaxhighlighter"
project makes sure that the latter is installed in the global libraries path,
i.e. the one specified in "installer-paths" when using "composer/installers".

See the composer.json file in the syntaxhighlighter module directory for the
full code for the repository.


SETUP
-----

Enable the syntaxhighlighter module.

Then enable the Syntax Highlighter filter in the text formats where
highlighting code using the syntaxhighlighter library is allowed.

It is not necessary to enable the Syntax Highlighter filter in any text format
that does not do HTML filtering (e.g. Full HTML).

IMPORTANT! If some HTML filtering is performed, like in the "Restricted HTML"
text format, place the filters in the following relative ordering positions:

+ Limit allowed HTML tags (or whatever HTML filter is used)
+ Syntax Highlighter
+ Convert line breaks into HTML (i.e. <br> and <p>)
+ ...


CONFIGURATION
-------------

Go to admin/config/content/syntaxhighlighter to configure the module settings.


USAGE
-----

Mark up code with as specified in http://alexgorbatchev.com/SyntaxHighlighter/

NOTE: make sure the markup is proper HTML. This means that if the code
contains any HTML tags or entities, they need to be escaped; some examples:
  - change the '<' character to '&lt;' (e.g. <script> to &lt;script>);
  - convert '&' in any HTML entity to '&amp;' (e.g. &gt; to &amp;gt;).


About AJAX Usage
----------------

On Ajax update, call Drupal.attachBehaviors(context) where context
is the element that has been updated.

Known problem:

Autoloader and Ajax will not work if the brush is not already used on the page
when the page is first loaded. For example: if on the page, there is no 'cpp'
code block, and there is an Ajax update on some 'cpp' code block, then
a "brush not found" error will be returned.

When Ajax is needed, it's probably better not to use the autoloader.