Merge pull request #19 from samakhov/master

Update templates to use the latest version of highlight #17

themes/common/highlight/README.md

@@ -2,32 +2,34 @@
 
 [![Build Status](https://travis-ci.org/isagalaev/highlight.js.svg?branch=master)](https://travis-ci.org/isagalaev/highlight.js)
 
-Highlight.js is a syntax highlighter written in JavaScript. It works in the
-browser as well as on the server. It works with pretty much any markup,
-doesn’t depend on any framework and has automatic language detection.
-
+Highlight.js is a syntax highlighter written in JavaScript. It works in
+the browser as well as on the server. It works with pretty much any
+markup, doesn’t depend on any framework and has automatic language
+detection.
 
 ## Getting Started
 
-The bare minimum for using highlight.js on a web page is linking to the library
-along with one of the styles and calling [`initHighlightingOnLoad`][1]:
+The bare minimum for using highlight.js on a web page is linking to the
+library along with one of the styles and calling
+[`initHighlightingOnLoad`][1]:
 
 ```html
 <link rel="stylesheet" href="/path/to/styles/default.css">
 <script src="/path/to/highlight.pack.js"></script>
 <script>hljs.initHighlightingOnLoad();</script>
 ```
 
-This will find and highlight code inside of `<pre><code>` tags; it tries to detect
-the language automatically. If automatic detection doesn’t work for you, you can
-specify the language in the `class` attribute:
+This will find and highlight code inside of `<pre><code>` tags; it tries
+to detect the language automatically. If automatic detection doesn’t
+work for you, you can specify the language in the `class` attribute:
 
 ```html
 <pre><code class="html">...</code></pre>
 ```
 
-The list of supported language classes is available in the [class reference][8].
-Classes can also be prefixed with either `language-` or `lang-`.
+The list of supported language classes is available in the [class
+reference][2].  Classes can also be prefixed with either `language-` or
+`lang-`.
 
 To disable highlighting altogether use the `nohighlight` class:
 
@@ -38,10 +40,11 @@ To disable highlighting altogether use the `nohighlight` class:
 ## Custom Initialization
 
 When you need a bit more control over the initialization of
-highlight.js, you can use the [`highlightBlock`][2] and [`configure`][3]
+highlight.js, you can use the [`highlightBlock`][3] and [`configure`][4]
 functions. This allows you to control *what* to highlight and *when*.
 
-Here’s an equivalent way to calling [`initHighlightingOnLoad`][1] using jQuery:
+Here’s an equivalent way to calling [`initHighlightingOnLoad`][1] using
+jQuery:
 
 ```javascript
 $(document).ready(function() {
@@ -51,9 +54,9 @@ $(document).ready(function() {
 });
 ```
 
-You can use any tags instead of `<pre><code>` to mark up your code. If you don't
-use a container that preserve line breaks you will need to configure
-highlight.js to use the `<br>` tag:
+You can use any tags instead of `<pre><code>` to mark up your code. If
+you don't use a container that preserve line breaks you will need to
+configure highlight.js to use the `<br>` tag:
 
 ```javascript
 hljs.configure({useBR: true});
@@ -63,39 +66,85 @@ $('div.code').each(function(i, block) {
 });
 ```
 
-For other options refer to the documentation for [`configure`][3].
+For other options refer to the documentation for [`configure`][4].
+
+
+## Web Workers
+
+You can run highlighting inside a web worker to avoid freezing the browser
+window while dealing with very big chunks of code.
+
+In your main script:
+
+```javascript
+addEventListener('load', function() {
+  var code = document.querySelector('#code');
+  var worker = new Worker('worker.js');
+  worker.onmessage = function(event) { code.innerHTML = event.data; }
+  worker.postMessage(code.textContent);
+})
+```
+
+In worker.js:
+
+```javascript
+onmessage = function(event) {
+  importScripts('<path>/highlight.pack.js');
+  var result = self.hljs.highlightAuto(event.data);
+  postMessage(result.value);
+}
+```
 
 
 ## Getting the Library
 
-You can get highlight.js as a hosted or custom-build browser script or as a
-server module. Head over to the [download page][4] for all the options.
+You can get highlight.js as a hosted, or custom-build, browser script or
+as a server module. Right out of the box the browser script supports
+both AMD and CommonJS, so if you wish you can use RequireJS or
+Browserify without having to build from source. The server module also
+works perfectly fine with Browserify, but there is the option to use a
+build specific to browsers rather than something meant for a server.
+Head over to the [download page][5] for all the options.
 
-**Note:** the library is not supposed to work straight from the source on
-GitHub; it requires building. If none of the pre-packaged options work for you
-refer to the [building documentation][5].
+**Don't link to GitHub directly.** The library is not supposed to work straight
+from the source, it requires building. If none of the pre-packaged options
+work for you refer to the [building documentation][6].
 
+**The CDN-hosted package doesn't have all the languages.** Otherwise it'd be
+too big. If you don't see the language you need in the ["Common" section][5],
+it can be added manually:
 
-## License
+```html
+<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.4.0/languages/go.min.js"></script>
+```
+
+**On Almond.** You need to use the optimizer to give the module a name. For
+example:
 
-Highlight.js is released under the BSD License. See [LICENSE][10] file for
-details.
+```
+r.js -o name=hljs paths.hljs=/path/to/highlight out=highlight.js
+```
+
+
+## License
 
+Highlight.js is released under the BSD License. See [LICENSE][7] file
+for details.
 
 ## Links
 
 The official site for the library is at <https://highlightjs.org/>.
 
 Further in-depth documentation for the API and other topics is at
-<http://highlightjs.readthedocs.org/>.
-
-Authors and contributors are listed in the [AUTHORS.en.txt][9] file.
-
-[1]: http://highlightjs.readthedocs.org/en/latest/api.html#inithighlightingonload
-[2]: http://highlightjs.readthedocs.org/en/latest/api.html#highlightblock-block
-[3]: http://highlightjs.readthedocs.org/en/latest/api.html#configure-options
-[4]: https://highlightjs.org/download/
-[5]: http://highlightjs.readthedocs.org/en/latest/building-testing.html
-[8]: http://highlightjs.readthedocs.org/en/latest/css-classes-reference.html
-[9]: https://github.com/isagalaev/highlight.js/blob/master/AUTHORS.en.txt
-[10]: https://github.com/isagalaev/highlight.js/blob/master/LICENSE
+<http://highlightjs.readthedocs.io/>.
+
+Authors and contributors are listed in the [AUTHORS.en.txt][8] file.
+
+[1]: http://highlightjs.readthedocs.io/en/latest/api.html#inithighlightingonload
+[2]: http://highlightjs.readthedocs.io/en/latest/css-classes-reference.html
+[3]: http://highlightjs.readthedocs.io/en/latest/api.html#highlightblock-block
+[4]: http://highlightjs.readthedocs.io/en/latest/api.html#configure-options
+[5]: https://highlightjs.org/download/
+[6]: http://highlightjs.readthedocs.io/en/latest/building-testing.html
+[7]: https://github.com/isagalaev/highlight.js/blob/master/LICENSE
+[8]: https://github.com/isagalaev/highlight.js/blob/master/AUTHORS.en.txt

themes/common/highlight/README.ru.md

@@ -1,6 +1,6 @@
 # Highlight.js
 
-Highlight.js — это подсветчик синтаксиса, написанный на JavaScript. Он работает
+Highlight.js — это инструмент для подсветки синтаксиса, написанный на JavaScript. Он работает
 и в браузере, и на сервере. Он работает с практически любой HTML разметкой, не
 зависит от каких-либо фреймворков и умеет автоматически определять язык.
 
@@ -24,8 +24,8 @@ Highlight.js — это подсветчик синтаксиса, написа
 <pre><code class="html">...</code></pre>
 ```
 
-Список поддерживаемых классов языков доступен в [справочнике по классам][8].
-Класс также можно предваоить префиксами `language-` или `lang-`.
+Список поддерживаемых классов языков доступен в [справочнике по классам][2].
+Класс также можно предварить префиксами `language-` или `lang-`.
 
 Чтобы отключить подсветку для какого-то блока, используйте класс `nohighlight`:
 
@@ -36,10 +36,10 @@ Highlight.js — это подсветчик синтаксиса, написа
 ## Инициализация вручную
 
 Чтобы иметь чуть больше контроля за инициализацией подсветки, вы можете
-использовать функции [`highlightBlock`][2] и [`configure`][3]. Таким образом
-можно управлять тем, *что* подсвечивать и *когда*.
+использовать функции [`highlightBlock`][3] и [`configure`][4]. Таким образом
+можно управлять тем, *что* и *когда* подсвечивать.
 
-Вот пример инициализация, эквивалентной вызову [`initHighlightingOnLoad`][1], но
+Вот пример инициализации, эквивалентной вызову [`initHighlightingOnLoad`][1], но
 с использованием jQuery:
 
 ```javascript
@@ -62,40 +62,81 @@ $('div.code').each(function(i, block) {
 });
 ```
 
-Другие опции можно найти в документации функции [`configure`][3].
+Другие опции можно найти в документации функции [`configure`][4].
+
+
+## Web Workers
+
+Подсветку можно запустить внутри web worker'а, чтобы окно
+браузера не подтормаживало при работе с большими кусками кода.
+
+В основном скрипте:
+
+```javascript
+addEventListener('load', function() {
+  var code = document.querySelector('#code');
+  var worker = new Worker('worker.js');
+  worker.onmessage = function(event) { code.innerHTML = event.data; }
+  worker.postMessage(code.textContent);
+})
+```
+
+В worker.js:
+
+```javascript
+onmessage = function(event) {
+  importScripts('<path>/highlight.pack.js');
+  var result = self.hljs.highlightAuto(event.data);
+  postMessage(result.value);
+}
+```
 
 
 ## Установка библиотеки
 
 Highlight.js можно использовать в браузере прямо с CDN хостинга или скачать
 индивидуальную сборку, а также установив модуль на сервере. На
-[страница загрузки][4] подробно описаны все варианты.
+[странице загрузки][5] подробно описаны все варианты.
+
+**Не подключайте GitHub напрямую.** Библиотека не предназначена для
+использования в виде исходного кода, а требует отдельной сборки. Если вам не
+подходит ни один из готовых вариантов, читайте [документацию по сборке][6].
+
+**Файл на CDN содержит не все языки.** Иначе он будет слишком большого размера.
+Если нужного вам языка нет в [категории "Common"][5], можно дообавить его
+вручную:
 
-Обратите внимание, что библиотека не предназначена для использования в виде
-исходного кода на GitHub, а требует отдельной сборки. Если вам не подходит ни
-один из готовых вариантов, читайте [документацию по сборке][5].
+```html
+<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.4.0/languages/go.min.js"></script>
+```
+
+**Про Almond.** Нужно задать имя модуля в оптимизаторе, например:
+
+```
+r.js -o name=hljs paths.hljs=/path/to/highlight out=highlight.js
+```
 
 
 ## Лицензия
 
 Highlight.js распространяется под лицензией BSD. Подробнее читайте файл
-[LICENSE][10].
+[LICENSE][7].
 
 
 ## Ссылки
 
 Официальный сайт билиотеки расположен по адресу <https://highlightjs.org/>.
 
 Более подробная документация по API и другим темам расположена на
-<http://highlightjs.readthedocs.org/>.
-
-Авторы и контрибьютора перечислена в файле [AUTHORS.ru.txt][9] file.
-
-[1]: http://highlightjs.readthedocs.org/en/latest/api.html#inithighlightingonload
-[2]: http://highlightjs.readthedocs.org/en/latest/api.html#highlightblock-block
-[3]: http://highlightjs.readthedocs.org/en/latest/api.html#configure-options
-[4]: https://highlightjs.org/download/
-[5]: http://highlightjs.readthedocs.org/en/latest/building-testing.html
-[8]: http://highlightjs.readthedocs.org/en/latest/css-classes-reference.html
-[9]: https://github.com/isagalaev/highlight.js/blob/master/AUTHORS.ru.txt
-[10]: https://github.com/isagalaev/highlight.js/blob/master/LICENSE
+<http://highlightjs.readthedocs.io/>.
+
+Авторы и контрибьюторы перечислены в файле [AUTHORS.ru.txt][8] file.
+
+[1]: http://highlightjs.readthedocs.io/en/latest/api.html#inithighlightingonload
+[2]: http://highlightjs.readthedocs.io/en/latest/css-classes-reference.html
+[3]: http://highlightjs.readthedocs.io/en/latest/api.html#highlightblock-block
+[4]: http://highlightjs.readthedocs.io/en/latest/api.html#configure-options
+[5]: https://highlightjs.org/download/
+[6]: http://highlightjs.readthedocs.io/en/latest/building-testing.html
+[7]: https://github.com/isagalaev/highlight.js/blob/master/LICENSE
+[8]: https://github.com/isagalaev/highlight.js/blob/master/AUTHORS.ru.txt