<NME> style_guide.rst
<BEF> ADDFILE
<MSG> Add docs from wiki

<DFF> @@ -0,0 +1,106 @@
+Style guide
+===========
+
+Overview
+--------
+
+Highlighted code is a single ``<code>`` element containing ``<span>``'s with pre-defined classes.
+Its appearance is controlled by a normal CSS file that can use all the features of CSS.
+
+There are however a couple of specific requirements for highlight.js styles:
+
+* Simplicity
+* Consistency
+* Portability
+
+
+Simplicity
+----------
+
+Overall style of highlight.js is minimalist, usable and generally not very bright.
+It's discouraged to use individual styling for small elements such as parentheses, commas, quotes etc.
+The ultimate goal of styling is to help people to actually read the code.
+
+
+Consistency
+-----------
+
+Highlight.js uses consistent class names across all the supported languages:
+strings are always "string", comments are always "comment", numbers are always "number".
+This allows to define a style that will work for all languages, not just one.
+This means that language names in style definition should be avoided:
+
+::
+
+  /* wrong! */
+  .html .tag {
+    font-weight: bold;
+  }
+  
+  /* right, works for tags in HTML and XML */ 
+  .tag {
+    font-weight: bold;
+  }
+
+There are also unique syntax elements that languages don't share with each other:
+"javadoc" in Java, "attr_selector" in CSS, "doctype" in XML etc.
+The best way to style them is by "packing" them into a group of selectors for a single CSS group of rules:
+
+::
+
+  .javadoc,
+  .decorator,
+  .filter .argument,
+  .localvars,
+  .array,
+  .attr_selector,
+  .pi,
+  .doctype {
+    color: #88F;
+  }
+
+This pattern helps keeping the number of different style rules to a minimum.
+It's also easier to maintain: when a programmer adds definition of a new language it's easier
+to stack its unique elements to existing groups instead of trying to define its style from scratch
+(something that programmers are known to be not very good at).
+
+The only case where you *should* include a language class name is when its commonly named element should not adhere to general rules.
+For example a class ``title`` serves in most languages as a title of a function or class definition and has a unique color.
+If we want it in, say, HTML to be black as the general text we should specify a language for this rule:
+
+::
+
+  .html .tag. .title {
+    color: black;
+  }
+
+
+Portability
+-----------
+
+CSS for syntax highlighting should not interfere with the main site styling.
+To achieve this all style rules are defined within ``pre`` element:
+
+::
+
+  pre .string {
+    color: red;
+  }
+  
+  pre .number {
+    color: green;
+  }
+
+
+CSS file header
+---------------
+
+A good idea is to include a comment at the top of your contributed CSS file that properly attributes your work:
+
+::
+
+  /*
+  
+  Mean-and-clean style (c) John Smith <email@domain.com>
+  
+  */

{'commit': 'diff --git a/docs/api.rst b/docs/api.rst\nnew file mode 100644\nindex 00000000..f013af98\n--- /dev/null\n+++ b/docs/api.rst\n@@ -0,0 +1,70 @@\n+Library API\n+===========\n+\n+Highilght.js exports a few functions as methods of the ``hljs`` object.\n+\n+\n+``highlight(language_name, value)``\n+-----------------------------------\n+\n+Core highlighting function.\n+Accepts a language name and a string with the code to highlight.\n+Returns an object with the following properties:\n+\n+* ``language``: language name, same as the one passed into a function, returned for consistency with ``highlightAuto``\n+* ``relevance``: integer value\n+* ``keyword_count``: integer value\n+* ``value``: HTML string with highlighting markup\n+\n+\n+``highlightAuto(value)``\n+------------------------\n+\n+Highlighting with language detection.\n+Accepts a string with the code to highlight.\n+Returns an object with the following properties:\n+\n+* ``language``: detected language\n+* ``relevance``: integer value\n+* ``keyword_count``: integer value\n+* ``value``: HTML string with highlighting markup\n+* ``second_best``: object with the same structure for second-best heuristically detected language, may be absent\n+\n+\n+``fixMarkup(value, tabReplace, usBR)``\n+--------------------------------------\n+\n+Post-processing of the highlighted markup.\n+Accepts a string with the highlighted markup and two optional values:\n+\n+* ``tabReplace``: arbitrary string (may contain HTML) to replace TAB characters with\n+* ``useBR``: a boolean flag to replace real line-breaks with ``<br>`` which is useful for non-``<pre>`` containers\n+\n+\n+``highlightBlock(block, tabReplace, useBR)``\n+--------------------------------------------\n+\n+Applies highlighting to a DOM node containing code.\n+Accepts a DOM node and two optional parameters for ``fixMarkup``.\n+\n+This function is the one to use to apply highlighting dynamically after page load\n+or within initialization code of third-party Javascript frameworks.\n+\n+\n+``initHighlighting()``\n+----------------------\n+\n+Applies highlighting to all ``<pre><code>..</code></pre>`` blocks on a page.\n+\n+To control tab replacement  use global flags on ``hljs`` object before initialization:\n+\n+::\n+\n+  hljs.tabReplace = \'    \'; //4 spaces\n+  hljs.initHighlighting();\n+\n+\n+``initHighlightingOnLoad()``\n+----------------------------\n+\n+Attaches highlighting to the page load event.\ndiff --git a/docs/building_testing.rst b/docs/building_testing.rst\nnew file mode 100644\nindex 00000000..9d027f60\n--- /dev/null\n+++ b/docs/building_testing.rst\n@@ -0,0 +1,49 @@\n+Building and testing\n+====================\n+\n+To actually run highlight.js it is necessary to build it for the environment where you\'re going to run it: a browser, the node.js server, etc.\n+\n+\n+Building\n+--------\n+\n+The build tool is written in Python (for both 2.x and 3.x variants).\n+It also can use YUICompressor for the in-browser builds so make sure you have Java installed for that too.\n+\n+The tool is located in ``tools/build.py`` (``tools/build3.py`` for Python 3).\n+A few useful examples:\n+\n+* Build for a browser using only common languages (they will be listed as it works):\n+\n+::\n+\n+  python tools/build.py :common\n+\n+* Build for node.js including all available languages:\n+\n+::\n+\n+  python tools/build.py -t node\n+\n+* Build two specific languages for debugging, skipping compression in this case:\n+\n+::\n+\n+  python tools/build.py -n python ruby\n+\n+The full option reference is available with the usual ``--help`` option.\n+\n+The build result will be in the ``build/`` directory.\n+\n+\n+Testing\n+-------\n+\n+Testing is done in a browser using the provided ``src/test.html`` file that contains snippets for all the supported languages.\n+You can use browser builds with all or only some of the languages, with or without compression.\n+\n+The usual approach to debugging and testing a language is first building highlight.js\n+with only the language you\'re working on without compression (to have readable code in browser error messages).\n+After this you have to build the entire package with all the languages and see if anything is broken.\n+If your language breaks auto-detection it should be fixed by :ref:`improving relevance <relevance>` and is a black art in and of itself.\n+When in doubt, please refer to the discussion group!\ndiff --git a/docs/contributor_checklist.rst b/docs/contributor_checklist.rst\nnew file mode 100644\nindex 00000000..c790328b\n--- /dev/null\n+++ b/docs/contributor_checklist.rst\n@@ -0,0 +1,78 @@\n+Language contributor checklist\n+==============================\n+\n+1. Put language definition into a .js file\n+------------------------------------------\n+\n+The file defines a function accepting a reference to the library and returning a language object.\n+The library parameter is useful to access common modes and regexps. You should not immediately call this function,\n+this is done during the build process and details differ for different build targets.\n+\n+::\n+\n+  function(hljs) {\n+    return {\n+      defaultMode: {\n+        contains: [ ..., hljs.NUMBER_MODE, ... ]\n+      }\n+    }\n+  }\n+  \n+The name of the file is used as a a short language identifier and should be usable as a class name in HTML and CSS.\n+  \n+\n+2. Provide meta data\n+--------------------\n+\n+At the top of the file there is a specially formatted comment with meta data processed by a build system.\n+Meta data format is simply key-value pairs each occupying its own line:\n+\n+::\n+\n+  /*\n+  Language: Superlanguage\n+  Requires: java.js, sql.js\n+  Author: John Smith <email@domain.com>\n+  Contributors: Mike Johnson <...@...>, Matt Wilson <...@...>\n+  Description: Some cool language definition\n+  */\n+\n+``Language`` — the only required header giving a human-readable language name.\n+\n+``Requires`` — a list of other language files required for this language to work.\n+This make it possible to describe languages that extend definitions of other ones.\n+Required files aren\'t processed in any special way.\n+The build system just make sure that they will be in the final package in ``LANGUAGES`` object.\n+\n+Meaning of other headers is pretty obvious.\n+\n+\n+3. Create a test fragment\n+-------------------------\n+\n+The fragment should include various language features. This is used both as an example and a test case.\n+It\'s usually better to create a synthetic fragment instead of just take a snippet of an existing code\n+because real-world code rarely contains all language features in one place.\n+This fragment is also absolutely *not* required to actually work or make sense :-).\n+Good example are C++ and HTML fragments in ``test.html``.\n+\n+Then put the fragment into the ``test.html`` similar to other languages\n+and test if it\'s properly detected and doesn\'t break detection of other languages.\n+\n+\n+4. Write class reference\n+------------------------\n+\n+Class reference lives in the file ``classref.txt``. Describe shortly names of all meaningful modes used in your language definition.\n+\n+\n+5. Add yourself to AUTHORS.*.txt\n+--------------------------------\n+\n+If you\'re a new contributor add yourself to the authors list. Feel free to use either English and/or Russian version.\n+\n+\n+6. Create a pull request\n+------------------------\n+\n+Send your contribution as a pull request on GitHub.\ndiff --git a/docs/define_language.rst b/docs/define_language.rst\nnew file mode 100644\nindex 00000000..9874cf3f\n--- /dev/null\n+++ b/docs/define_language.rst\n@@ -0,0 +1,245 @@\n+Language definition guide\n+=========================\n+\n+Highlighting overview\n+---------------------\n+\n+Programming language code consists of parts with different rules of parsing: keywords like ``for`` or ``if``\n+don\'t make sense inside strings, strings may contain backslash-escaped symbols like ``\\"``\n+and comments usually don\'t contain anything interesting except the end of the comment.\n+\n+In highlight.js such parts are called "modes".\n+\n+Each mode consists of:\n+\n+* starting condition\n+* ending condition\n+* list of contained sub-modes\n+* lexing rules and keywords\n+* …exotic stuff like another language inside a language\n+\n+The parser\'s work is to look for modes and their keywords.\n+Upon finding it wraps them into the markup ``<span class="...">...</span>``\n+and puts the name of the mode ("string", "comment", "number")\n+or a keyword group name ("keyword", "literal", "built-in") as the span\'s class name.\n+\n+\n+General syntax\n+--------------\n+\n+A language definition is a JavaScript object describing the default parsing mode for the language.\n+This default mode contain sub-modes which in turn contain other sub-modes effectively making the language definition a tree of modes.\n+\n+Here\'s an example:\n+\n+::\n+\n+  {\n+    case_insensitive: true, // language is case-insensitive\n+    keywords: \'for if while\',\n+    contains: [\n+      {\n+        className: \'string\',\n+        begin: \'"\', end: \'"\'\n+      },\n+      {\n+        className: \'comment\',\n+        begin: \'/*\', end: \'*/\',\n+        contains: [\n+          {\n+            className: \'doc\', begin: \'@\\\\w+\'\n+          }\n+        ]\n+      }\n+    ]\n+  }\n+\n+Usually the default mode accounts for the majority of the code and describes all language keywords.\n+A notable exception here is XML in which a default mode is just a user text that doesn\'t contain any keywords,\n+and most interesting parsing happens inside tags.\n+\n+\n+Keywords\n+--------\n+\n+In the simple case language keywords are defined in a string, separated by space:\n+\n+::\n+\n+  {\n+    keywords: \'else for if while\' \n+  }\n+\n+Some languages have different kinds of "keywords" that might not be called as such by the language spec\n+but are very close to them from the point of view of a syntax highlighter. These are all sorts of "literals", "built-ins", "symbols" and such.\n+To define such keyword groups the attribute ``keywords`` becomes an object each property of which defines its own group of keywords:\n+\n+::\n+\n+  {\n+    keywords: {\n+      \'keyword\': \'else for if while\',\n+      \'literal\': \'false true null\'\n+    }\n+  }\n+\n+The group name becomes then a class name in a generated markup enabling different styling for different kinds of keywords.\n+\n+To detect keywords highlight.js breaks the processed chunk of code into separate words — a process called lexing.\n+The "word" here is defined by the regexp ``[a-zA-Z][a-zA-Z0-9_]*`` that works for keywords in most languages.\n+Different lexing rules can be defines by the ``lexems`` attribute:\n+\n+::\n+\n+  {\n+    lexems: \'-[a-z]+\',\n+    keywords: \'-import -export\'\n+  }\n+\n+\n+Sub-modes\n+---------\n+\n+Sub-modes are listed in the ``contains`` attribute:\n+\n+::\n+\n+  {\n+    keywords: \'...\',\n+    contains: [\n+      hljs.QUOTE_STRING_MODE, \n+      hljs.C_LINE_COMMENT,\n+      { ... custom mode definition ... }\n+    ]\n+  }\n+\n+A mode can reference itself in the ``contains`` array by using a special keyword ``\'self``\'.\n+This is commonly used to define nested modes:\n+\n+::\n+\n+  {\n+    className: \'object\',\n+    begin: \'{\', end: \'}\',\n+    contains: [hljs.QUOTE_STRING_MODE, \'self\']\n+  }\n+\n+\n+Markup generation\n+-----------------\n+\n+Modes usually generate actual highlighting markup — ``<span>`` elements with specific class names that are defined by the ``className`` attribute:\n+\n+::\n+\n+  {\n+    contains: [\n+      {\n+        className: \'string\', \n+        // ... other attributes\n+      },\n+      {\n+        className: \'number\',\n+        // ...\n+      }\n+    ]\n+  }\n+\n+Names are not required to be unique, it\'s quite common to have several definitions with the same name.\n+For example, many languages have various syntaxes for strings, comments, etc…\n+\n+Sometimes modes are defined only to support specific parsing rules and aren\'t needed in the final markup.\n+A classic example is an escaping sequence inside strings allowing them to contain an ending quote.\n+\n+::\n+\n+  {\n+    className: \'string\',\n+    begin: \'"\', end: \'"\',\n+    contains: [{begin: \'\\\\\\\\.\'}],\n+  }\n+\n+For such modes ``className`` attribute should be omitted so they won\'t generate excessive markup.\n+\n+\n+Mode attributes\n+---------------\n+\n+Other useful attributes are defined in the :doc:`mode reference </mode_reference>`.\n+\n+\n+.. _relevance:\n+\n+Relevance\n+---------\n+\n+Highlight.js tries to automatically detect the language of a code fragment.\n+The heuristics is essentially simple: it tries to highlight a fragment with all the language definitions\n+and the one that yields most specific modes and keywords wins. The job of a language definition\n+is to help this heuristics by hinting relative relevance (or irrelevance) of modes.\n+\n+This is best illustrated by example. Python has special kinds of strings defined by prefix letters before the quotes:\n+``r"..."``, ``u"..."``. If a code fragment contains such strings there is a good chance that it\'s in Python.\n+So these string modes are given high relevance:\n+\n+::\n+\n+  {\n+    className: \'string\',\n+    begin: \'r"\', end: \'"\',\n+    relevance: 10\n+  }\n+\n+On the other hand, conventional strings in plain single or double quotes aren\'t specific to any language\n+and it makes sense to bring their relevance to zero to lessen statistical noise:\n+\n+::\n+\n+  {\n+    className: \'string\',\n+    begin: \'"\', end: \'"\',\n+    relevance: 0\n+  }\n+\n+The default value for relevance is 1. When setting an explicit value it\'s recommended to use either 10 or 0.\n+\n+Keywords also influence relevance. Each of them usually has a relevance of 1, but there are some unique names\n+that aren\'t likely to be found outside of their languages, even in the form of variable names.\n+For example just having ``reinterpret_cast`` somewhere in the code is a good indicator that we\'re looking at C++.\n+It\'s worth to set relevance of such keywords a bit higher. This is done with a pipe:\n+\n+::\n+\n+  {\n+    keywords: \'for if reinterpret_cast|10\'\n+  }\n+\n+\n+Illegal symbols\n+---------------\n+\n+Another way to improve language detection is to define illegal symbols for a mode.\n+For example in Python first line of class definition (``class MyClass(object):``) cannot contain symbol "{" or a newline.\n+Presence of these symbols clearly shows that the language is not Python and the parser can drop this attempt early.\n+\n+Illegal symbols are defined as a a single regular expression:\n+\n+::\n+\n+  {\n+    className: \'class\',\n+    illegal: \'[${]\'\n+  }\n+\n+\n+Pre-defined modes and regular expressions\n+-----------------------------------------\n+\n+Many languages share common modes and regular expressions. Such expressions are defined in core highlight.js code\n+at the end under "Common regexps" and "Common modes" titles. Use them when possible.\n+\n+\n+Contributing\n+------------\n+\n+Follow :doc:`contributor checklist </contributor_checklist>`.\ndiff --git a/docs/index.rst b/docs/index.rst\nindex 627610d4..5e0c21ac 100644\n--- a/docs/index.rst\n+++ b/docs/index.rst\n@@ -3,14 +3,21 @@\n    You can adapt this file completely to your liking, but it should at least\n    contain the root `toctree` directive.\n \n-Welcome to highlight.js\'s documentation!\n-========================================\n+``highlight.js`` documentation\n+==========================================\n \n Contents:\n \n .. toctree::\n    :maxdepth: 2\n \n+   api\n+   define_language\n+   mode_reference\n+   style_guide\n+   contributor_checklist\n+   building_testing\n+\n \n \n Indices and tables\ndiff --git a/docs/mode_reference.rst b/docs/mode_reference.rst\nnew file mode 100644\nindex 00000000..fa2ee82d\n--- /dev/null\n+++ b/docs/mode_reference.rst\n@@ -0,0 +1,218 @@\n+Mode reference\n+==============\n+\n+Types\n+-----\n+\n+Types of attributes values in this reference:\n+\n++------------+-------------------------------------------------------------------------------------+\n+| identifier | String suitable to be used as a Javascript variable and CSS class name              |\n+|            | (i.e. mostly ``/[A-Za-z0-9_]+/``)                                                   |\n++------------+-------------------------------------------------------------------------------------+\n+| regexp     | String representing a Javascript regexp.                                            |\n+|            | Note that since it\'s not a literal regexp all back-slashes should be repeated twice |\n++------------+-------------------------------------------------------------------------------------+\n+| boolean    | Javascript boolean: ``true`` or ``false``                                           |\n++------------+-------------------------------------------------------------------------------------+\n+| number     | Javascript number                                                                   |\n++------------+-------------------------------------------------------------------------------------+\n+| object     | Javascript object: ``{ ... }``                                                      |\n++------------+-------------------------------------------------------------------------------------+\n+| array      | Javascript array: ``[ ... ]``                                                       |\n++------------+-------------------------------------------------------------------------------------+\n+\n+\n+Attributes\n+----------\n+\n+className\n+^^^^^^^^^\n+\n+**type**: identifier\n+\n+The name of the mode. It is used as a class name in HTML markup.\n+\n+Multiple modes can have the same name. This is useful when a language has multiple variants of syntax\n+for one thing like string in single or double quotes.\n+\n+\n+begin\n+^^^^^\n+\n+**type**: regexp\n+\n+Regular expression starting a mode. For example a single quote for strings or two forward slashes for C-style comments.\n+If absent, ``begin`` defaults to ``hljs.IMMEDIATE_RE`` that matches anything.\n+\n+\n+end\n+^^^\n+\n+**type**: regexp\n+\n+Regular expression ending a mode. For example a single quote for strings or "$" (end of line) for one-line comments.\n+\n+It\'s often the case that a beginning regular expression defines the entire mode and doesn\'t need any special ending.\n+For example a number can be defined with ``begin: "\\\\b\\\\d+"`` which spans all the digits.\n+\n+If absent, ``end`` defaults to ``hljs.IMMEDIATE_RE`` that matches anything.\n+\n+Sometimes a mode can end not by itself but implicitly with its containing (parent) mode.\n+This is achieved with :ref:`endsWithParent <endsWithParent>` attribute.\n+\n+\n+beginWithKeyword\n+^^^^^^^^^^^^^^^^\n+\n+**type**: boolean\n+\n+Used instead of ``begin`` for modes starting with keywords to avoid needless repetition:\n+\n+::\n+\n+  {\n+    begin: \'\\\\b(extends|implements) \',\n+    keywords: \'extends implements\'\n+  }\n+  \n+… becomes:\n+\n+::\n+\n+  {\n+    beginWithKeywords: true, keywords: \'extends implements\'\n+  }\n+\n+\n+.. _endsWithParent:\n+\n+endsWithParent\n+^^^^^^^^^^^^^^\n+\n+**type**: boolean\n+\n+A flag showing that a mode ends when its parent ends.\n+\n+This is best demonstrated by example. In CSS syntax a selector has a set of rules contained within symbols "{" and "}".\n+Individual rules separated by ";" but the last one in a set can omit the terminating semicolon:\n+\n+::\n+\n+  p {\n+    width: 100%; color: red\n+  }\n+\n+This is when ``endsWithParent`` comes into play:\n+\n+::\n+\n+  {\n+    className: \'rules\', begin: \'{\', end: \'}\',\n+    contains: [\n+      {className: \'rule\', /* ... */ end: \';\', endsWithParent: true}\n+    ]\n+  }\n+\n+\n+.. _lexems:\n+\n+lexems\n+^^^^^^\n+\n+**type**: regexp\n+\n+A regular expression extracting individual lexems from language text to find ``[[#keywords]]`` among them.\n+Default value is ``hljs.IDENT_RE`` which works for most languages.\n+\n+\n+.. _keywords:\n+\n+keywords\n+^^^^^^^^\n+\n+**type**: object\n+\n+Keyword definition comes in two forms:\n+\n+* ``\'for while if else weird_voodoo|10 ... \'`` -- a string of space-separated keywords with an optional relevance over a pipe\n+* ``{\'keyword\': \' ... \', \'literal\': \' ... \'}`` -- an object whose keys are names of different kinds of keywords and values\n+                                                  are keyword definition strings in the first form\n+\n+For detailed explanation see [[Language]] definition guide.\n+\n+\n+illegal\n+^^^^^^^\n+\n+**type**: regexp\n+\n+A regular expression defining symbols illegal for the mode.\n+When the parser finds a match for illegal expression it immediately drops parsing the whole language altogether.\n+\n+\n+excludeBegin, excludeEnd\n+^^^^^^^^^^^^^^^^^^^^^^^^\n+ \n+**type**: boolean\n+\n+Exclude beginning or ending lexems out of mode\'s generated markup. For example in CSS syntax a rule ends with a semicolon.\n+However visually it\'s better not to color it as the rule contents. Having ``excludeEnd: true`` forces a ``<span>`` element for the rule to close before the semicolon.\n+\n+\n+returnBegin\n+^^^^^^^^^^^\n+\n+**type**: boolean\n+\n+Returns just found beginning lexem back into parser. This is used when beginning of a sub-mode is a complex expression\n+that should not only be found within a parent mode but also parsed according to the rules of a sub-mode.\n+\n+Since the parser is effectively goes back it\'s quite possible to create a infinite loop here so use with caution!\n+\n+\n+returnEnd\n+^^^^^^^^^\n+\n+**type**: boolean\n+\n+Returns just found ending lexem back into parser. This is used for example to parse Javascript embedded into HTML.\n+A Javascript block ends with the HTML closing tag ``</script>`` that cannot be parsed with Javascript rules.\n+So it is returned back into its parent HTML mode that knows what to do with it.\n+\n+Since the parser is effectively goes back it\'s quite possible to create a infinite loop here so use with caution!\n+\n+\n+contains\n+^^^^^^^^\n+\n+**type**: array\n+\n+The list of sub-modes that can be found inside the mode. For detailed explanation see [[Language]] definition guide.\n+\n+\n+starts\n+^^^^^^\n+\n+**type**: identifier\n+\n+The name of the mode that will start right after the current mode ends. The new mode won\'t be contained within the current one.\n+\n+Currently this attribute is used to highlight Javascript and CSS contained within HTML.\n+Tags ``<script>`` and ``<style>`` start sub-modes that use another language definition to parse their contents (see :ref:`subLanguage`).\n+\n+\n+.. _subLanguage:\n+\n+subLanguage\n+^^^^^^^^^^^\n+\n+**type**: identifier\n+\n+The name of another language used to parse the contents of the mode.\n+When using this attribute there\'s not point to define internal parsing rules like :ref:`lexems` or :ref:`keywords`.\n+Also it is recommended to skip ``className`` attribute since the sublanguage will wrap the text in its own ``<span class="language-name">``\n+\n+If the attribute is set to an empty string highlight.js will highlight the mode contents with language detection.\n+\n+Note that for this to work the language should be included in package (obviously).\ndiff --git a/docs/style_guide.rst b/docs/style_guide.rst\nnew file mode 100644\nindex 00000000..fede67be\n--- /dev/null\n+++ b/docs/style_guide.rst\n@@ -0,0 +1,106 @@\n+Style guide\n+===========\n+\n+Overview\n+--------\n+\n+Highlighted code is a single ``<code>`` element containing ``<span>``\'s with pre-defined classes.\n+Its appearance is controlled by a normal CSS file that can use all the features of CSS.\n+\n+There are however a couple of specific requirements for highlight.js styles:\n+\n+* Simplicity\n+* Consistency\n+* Portability\n+\n+\n+Simplicity\n+----------\n+\n+Overall style of highlight.js is minimalist, usable and generally not very bright.\n+It\'s discouraged to use individual styling for small elements such as parentheses, commas, quotes etc.\n+The ultimate goal of styling is to help people to actually read the code.\n+\n+\n+Consistency\n+-----------\n+\n+Highlight.js uses consistent class names across all the supported languages:\n+strings are always "string", comments are always "comment", numbers are always "number".\n+This allows to define a style that will work for all languages, not just one.\n+This means that language names in style definition should be avoided:\n+\n+::\n+\n+  /* wrong! */\n+  .html .tag {\n+    font-weight: bold;\n+  }\n+  \n+  /* right, works for tags in HTML and XML */ \n+  .tag {\n+    font-weight: bold;\n+  }\n+\n+There are also unique syntax elements that languages don\'t share with each other:\n+"javadoc" in Java, "attr_selector" in CSS, "doctype" in XML etc.\n+The best way to style them is by "packing" them into a group of selectors for a single CSS group of rules:\n+\n+::\n+\n+  .javadoc,\n+  .decorator,\n+  .filter .argument,\n+  .localvars,\n+  .array,\n+  .attr_selector,\n+  .pi,\n+  .doctype {\n+    color: #88F;\n+  }\n+\n+This pattern helps keeping the number of different style rules to a minimum.\n+It\'s also easier to maintain: when a programmer adds definition of a new language it\'s easier\n+to stack its unique elements to existing groups instead of trying to define its style from scratch\n+(something that programmers are known to be not very good at).\n+\n+The only case where you *should* include a language class name is when its commonly named element should not adhere to general rules.\n+For example a class ``title`` serves in most languages as a title of a function or class definition and has a unique color.\n+If we want it in, say, HTML to be black as the general text we should specify a language for this rule:\n+\n+::\n+\n+  .html .tag. .title {\n+    color: black;\n+  }\n+\n+\n+Portability\n+-----------\n+\n+CSS for syntax highlighting should not interfere with the main site styling.\n+To achieve this all style rules are defined within ``pre`` element:\n+\n+::\n+\n+  pre .string {\n+    color: red;\n+  }\n+  \n+  pre .number {\n+    color: green;\n+  }\n+\n+\n+CSS file header\n+---------------\n+\n+A good idea is to include a comment at the top of your contributed CSS file that properly attributes your work:\n+\n+::\n+\n+  /*\n+  \n+  Mean-and-clean style (c) John Smith <email@domain.com>\n+  \n+  */\n', 'commit_subject': 'Add docs from wiki', 'repo_name': 'highlightjs/highlight.js', 'committer': {'name': 'Oleg Efimov', 'email': 'dd0c50212436c06e06ec7ae1f80089c598111731@gmail.com', 'time_sec': '1347731669', 'tz_offset': '240', 'date': {'seconds': '1347731669'}}, 'commit_tree': 'c9d94b278b773a91a38a9c9673957a65ef9233cb', 'commit_message': 'Add docs from wiki\n', 'language_name': 'HTML', 'license': 'bsd-3-clause', 'hunks': '@@ -0,0 +1,106 @@\n+Style guide\n+===========\n+\n+Overview\n+--------\n+\n+Highlighted code is a single ``<code>`` element containing ``<span>``\'s with pre-defined classes.\n+Its appearance is controlled by a normal CSS file that can use all the features of CSS.\n+\n+There are however a couple of specific requirements for highlight.js styles:\n+\n+* Simplicity\n+* Consistency\n+* Portability\n+\n+\n+Simplicity\n+----------\n+\n+Overall style of highlight.js is minimalist, usable and generally not very bright.\n+It\'s discouraged to use individual styling for small elements such as parentheses, commas, quotes etc.\n+The ultimate goal of styling is to help people to actually read the code.\n+\n+\n+Consistency\n+-----------\n+\n+Highlight.js uses consistent class names across all the supported languages:\n+strings are always "string", comments are always "comment", numbers are always "number".\n+This allows to define a style that will work for all languages, not just one.\n+This means that language names in style definition should be avoided:\n+\n+::\n+\n+  /* wrong! */\n+  .html .tag {\n+    font-weight: bold;\n+  }\n+  \n+  /* right, works for tags in HTML and XML */ \n+  .tag {\n+    font-weight: bold;\n+  }\n+\n+There are also unique syntax elements that languages don\'t share with each other:\n+"javadoc" in Java, "attr_selector" in CSS, "doctype" in XML etc.\n+The best way to style them is by "packing" them into a group of selectors for a single CSS group of rules:\n+\n+::\n+\n+  .javadoc,\n+  .decorator,\n+  .filter .argument,\n+  .localvars,\n+  .array,\n+  .attr_selector,\n+  .pi,\n+  .doctype {\n+    color: #88F;\n+  }\n+\n+This pattern helps keeping the number of different style rules to a minimum.\n+It\'s also easier to maintain: when a programmer adds definition of a new language it\'s easier\n+to stack its unique elements to existing groups instead of trying to define its style from scratch\n+(something that programmers are known to be not very good at).\n+\n+The only case where you *should* include a language class name is when its commonly named element should not adhere to general rules.\n+For example a class ``title`` serves in most languages as a title of a function or class definition and has a unique color.\n+If we want it in, say, HTML to be black as the general text we should specify a language for this rule:\n+\n+::\n+\n+  .html .tag. .title {\n+    color: black;\n+  }\n+\n+\n+Portability\n+-----------\n+\n+CSS for syntax highlighting should not interfere with the main site styling.\n+To achieve this all style rules are defined within ``pre`` element:\n+\n+::\n+\n+  pre .string {\n+    color: red;\n+  }\n+  \n+  pre .number {\n+    color: green;\n+  }\n+\n+\n+CSS file header\n+---------------\n+\n+A good idea is to include a comment at the top of your contributed CSS file that properly attributes your work:\n+\n+::\n+\n+  /*\n+  \n+  Mean-and-clean style (c) John Smith <email@domain.com>\n+  \n+  */\n', 'addition_count': 106, 'deletion_count': 0, 'src_file': '/dev/null', 'tgt_file': 'b/docs/style_guide.rst', 'file_extension': '.rst', 'before_file': 'ADDFILE', 'message': 'Add docs from wiki\n', 'author_name': 'Oleg Efimov', 'lang': 'rst'}