Fix docs

bem · Feb 21, 2015 · 2aa5b83 · 2aa5b83
1 parent 8e609d7
commit 2aa5b83
Show file tree

Hide file tree

Showing 2 changed files with 102 additions and 41 deletions.
diff --git a/README.md b/README.md
@@ -29,6 +29,7 @@ Compares two HTML.
   * [Configuration file](#configuration-file)
 * [Masks](#masks)
   * [Syntax](#syntax)
+  * [Screening](#screening)
 
 <!-- TOC END -->
 
@@ -94,7 +95,7 @@ $ npm install html-differ
 
 ## API
 
-###HtmlDiffer###
+### HtmlDiffer
 
 ```js
 var HtmlDiffer = require('html-differ').HtmlDiffer,
@@ -103,9 +104,9 @@ var HtmlDiffer = require('html-differ').HtmlDiffer,
 
 where `options` is an object.
 
-####Options####
+#### Options
 
-#####ignoreAttributes: [Array]#####
+##### ignoreAttributes: [Array]
 
 Sets what kind of respective attributes' content will be ignored during the comparison (default: `[]`).
 
@@ -122,7 +123,7 @@ The following two code samples will be considered to be equivalent:
 <input id="sfsdfksdf">
 ```
 
-#####compareAttributesAsJSON: [Array]#####
+##### compareAttributesAsJSON: [Array]
 
 Sets what kind of respective attributes' content will be compared as JSON objects, but not as strings (default: `[]`).<br>
 In cases when the value of the attribute is an invalid JSON or can not be wrapped into a function, it will be compared as `undefined`.
@@ -150,7 +151,7 @@ The following two code samples will be considered to be equivalent:
 The first element of the array could be written in a short form as string:<br>
 `['data', { name: 'onclick', isFunction: true }]`.
 
-#####ignoreWhitespaces: Boolean#####
+##### ignoreWhitespaces: Boolean
 
 Makes **html-differ** ignore whitespaces (spaces, tabs, new lines etc.) during the comparison (default: `true`).
 
@@ -182,7 +183,7 @@ The following two code samples will be considered to be equivalent:
 
 ```
 
-#####ignoreComments: Boolean#####
+##### ignoreComments: Boolean
 
 Makes **html-differ** ignore HTML comments during the comparison (default: `true`).
 
@@ -231,7 +232,7 @@ Text
 </html>
 ```
 
-#####ignoreEndTags: Boolean#####
+##### ignoreEndTags: Boolean
 
 Makes **html-differ** ignore end tags during the comparison (default: `false`).
 
@@ -246,7 +247,7 @@ The following two code samples will be considered to be equivalent:
 <span>Text</spane>
 ```
 
-#####ignoreDuplicateAttributes: Boolean#####
+##### ignoreDuplicateAttributes: Boolean
 
 Makes **html-differ** ignore tags' duplicate attributes during the comparison.<br>
 From the list of the same tag's attributes, the attribute which goes the first will be taken for comparison, others will be ignored (default: `false`).
@@ -262,12 +263,12 @@ For example, the following two code samples will be considered to be equivalent:
 <span id="blah">Text</span>
 ```
 
-####Presets####
+#### Presets
 
 * [bem](https://github.com/bem/html-differ/blob/master/presets/bem.json) - sets predefined options for [BEM](http://bem.info/).
 
 
-#####Usage#####
+##### Usage
 
 Passing of a preset via the constructor:
 
@@ -283,36 +284,39 @@ var HtmlDiffer = require('html-differ').HtmlDiffer,
     htmlDiffer = new HtmlDiffer({ preset: 'bem', ignoreAttributes: [] });
 ```
 
-####Methods####
+#### Methods
+
+##### htmlDiffer.diffHtml
 
-#####htmlDiffer.diffHtml#####
 **@param** *{String}* - the 1-st HTML code<br>
 **@param** *{String}* - the 2-nd HTML code<br>
 **@returns** *{Array of objects}* - [array with diffs](https://github.com/kpdecker/jsdiff#change-objects) between HTML
 
-#####htmlDiffer.isEqual#####
+##### htmlDiffer.isEqual
+
 **@param** *{String}* - the 1-st HTML code<br>
 **@param** *{String}* - the 2-nd HTML code<br>
 **@returns** *{Boolean}*
 
 
-###Logger###
+### Logger
 
 ```js
 var logger = require('html-differ/lib/logger');
 ```
 
-####Methods####
+#### Methods
+
+##### logger.getDiffText
 
-#####logger.getDiffText#####
 **@param** *{Array of objects}* - the result of the work of the method [htmlDiffer.diffHtml](https://github.com/bem/html-differ/tree/master#htmldifferdiffhtml)<br>
 **@param** *{Object}* - options:<br>
 
 * **charsAroundDiff: Number** - the number of characters around the diff result between two HTML (default: `40`).
 
 **@returns** *{String}*
 
-#####logger.logDiffText#####
+##### logger.logDiffText
 **@param** *{Array of objects}* - the result of the work of the method [htmlDiffer.diffHtml](https://github.com/bem/html-differ/tree/master#htmldifferdiffhtml)<br>
 **@param** *{Object}* - options:<br>
 
@@ -323,7 +327,7 @@ var logger = require('html-differ/lib/logger');
 <img src='https://cloud.githubusercontent.com/assets/6376693/3648928/a6b9d48a-110d-11e4-8a07-d9b156145017.png'/>
 
 
-###Example###
+### Example
 
 ```js
 var fs = require('fs'),
@@ -351,7 +355,7 @@ var diff = htmlDiffer.diffHtml(html1, html2),
 logger.logDiffText(diff, { charsAroundDiff: 40 });
 ```
 
-##Usage as a program##
+## Usage as a program
 
 ```bash
 $ html-differ --help
@@ -373,7 +377,7 @@ Arguments:
   PATH2 : Path to the 2-nd HTML file (required)
 ```
 
-###Example###
+### Example
 
 ```bash
 $ html-differ path/to/html1 path/to/html2
@@ -383,7 +387,7 @@ $ html-differ --config=path/to/config --chars-around-diff=40 path/to/html1 path/
 $ html-differ --preset=bem path/to/html1 path/to/html2
 ```
 
-###Configuration file##
+### Configuration file
 
 Study the following file `config.json`:
 
@@ -427,3 +431,29 @@ where:
 * `RegExp` – regular expression for matching with the corresponding value in another HTML. The syntax is similar to regular expressions in JavaScript written in a literal notation.
 
 * `}}` – closing identifier of the _mask_.
+
+### Screening
+
+The rules of screening of symbols are similar to the rules which are used in regular expressions in JavaScript written in a literal notation.
+
+For example, the following two code samples will be considered to be equivalent:
+
+```html
+<div id="{{\d\.\d}}">
+```
+
+```html
+<div id="1.1">
+```
+
+If you want to use `{{` or `}}` inside a mask, you should screen both curly braces, i.e. `\{\}` or `\}\}`.
+
+For example, the following two code samples will be considered to be equivalent:
+
+```html
+<div class="{{a\{\{b\}\}c}}">
+```
+
+```html
+<div class="a{{b}}c">
+```
diff --git a/README.ru.md b/README.ru.md
@@ -29,6 +29,7 @@
   * [Конфигурационный файл](#Конфигурационный-файл)
 * [Маски](#Маски)
   * [Синтаксис](#Синтаксис)
+  * [Экранирование](#Экранирование)
 
 <!-- TOC END -->
 
@@ -103,9 +104,9 @@ var HtmlDiffer = require('html-differ').HtmlDiffer,
 
 где `options` – это объект.
 
-####Опции####
+#### Опции
 
-#####ignoreAttributes: [Array]#####
+##### ignoreAttributes: [Array]
 
 Устанавливает, значения каких атрибутов следует игнорировать при сравнении (по умолчанию: `[]`).
 
@@ -122,7 +123,7 @@ var HtmlDiffer = require('html-differ').HtmlDiffer,
 <input id="sfsdfksdf">
 ```
 
-#####compareAttributesAsJSON: [Array]#####
+##### compareAttributesAsJSON: [Array]
 
 Устанавливает, значения каких атрибутов следует сравнивать как JSON-объекты, а не как строки (по умолчанию: `[]`).<br>
 В тех случаях, когда в качестве значения атрибута выступает некорректный JSON или это значение нельзя обернуть в функцию, то оно будет сравниваться как `undefined`.
@@ -150,7 +151,7 @@ var HtmlDiffer = require('html-differ').HtmlDiffer,
 Первый элемент массива мог быть записан в короткой форме в качестве строки:<br>
 `['data', { name: 'onclick', isFunction: true }]`.
 
-#####ignoreWhitespaces: Boolean#####
+##### ignoreWhitespaces: Boolean
 
 **html-differ** будет игнорировать пробельные символы (пробелы, табуляция, переводы строк и т. д.) при сравнении (по умолчанию: `true`).
 
@@ -182,7 +183,7 @@ var HtmlDiffer = require('html-differ').HtmlDiffer,
 
 ```
 
-#####ignoreComments: Boolean#####
+##### ignoreComments: Boolean
 
 **html-differ** будет игнорировать HTML-комментарии при сравнении (по умолчанию: `true`).
 
@@ -230,7 +231,7 @@ Text
 </html>
 ```
 
-#####ignoreEndTags: Boolean#####
+##### ignoreEndTags: Boolean
 
 **html-differ** будет игнорировать закрывающие тэги при сравнении (по умолчанию: `false`).
 
@@ -245,7 +246,7 @@ Text
 <span>Text</spane>
 ```
 
-#####ignoreDuplicateAttributes: Boolean#####
+##### ignoreDuplicateAttributes: Boolean
 
 **html-differ** будет игнорировать повторяющиеся атрибуты.<br>
 Из списка одинаковых атрибутов тэга, для сравнения будет взят тот, который идет первым, остальные будут проигнорированы (по умолчанию: `false`).
@@ -261,12 +262,12 @@ Text
 <span id="blah">Text</span>
 ```
 
-####Пресеты####
+#### Пресеты
 
 * [bem](https://github.com/bem/html-differ/blob/master/presets/bem.json) - уставливает предопределенные опции для [БЭМ](http://ru.bem.info/).
 
 
-#####Использование#####
+##### Использование
 
 Передача пресета конструктору:
 
@@ -282,35 +283,39 @@ var HtmlDiffer = require('html-differ').HtmlDiffer,
     htmlDiffer = new HtmlDiffer({ preset: 'bem', ignoreAttributes: [] });
 ```
 
-####Методы####
+#### Методы
+
+##### htmlDiffer.diffHtml
 
-#####htmlDiffer.diffHtml#####
 **@param** *{String}* - 1-й HTML<br>
 **@param** *{String}* - 2-й HTML<br>
 **@returns** *{Array of objects}* - [массив с отличиями](https://github.com/kpdecker/jsdiff#change-objects) между HTML
 
-#####htmlDiffer.isEqual#####
+##### htmlDiffer.isEqual
+
 **@param** *{String}* - 1-й HTML<br>
 **@param** *{String}* - 2-й HTML<br>
 **@returns** *{Boolean}*
 
-###Logger###
+### Logger
 
 ```js
 var logger = require('html-differ/lib/logger');
 ```
 
-####Методы####
+#### Методы
+
+##### logger.getDiffText
 
-#####logger.getDiffText#####
 **@param** *{Array of objects}* - результат работы метода [htmlDiffer.diffHtml](https://github.com/bem/html-differ/blob/master/README.ru.md#htmldifferdiffhtml)<br>
 **@param** *{Object}* - опции:<br>
 
 * **charsAroundDiff: Number** - количество символов перед отличием между HTML и после него (по умолчанию: `40`)
 
 **@returns** *{String}*
 
-#####logger.logDiffText#####
+##### logger.logDiffText
+
 **@param** *{Array of objects}* - результат работы метода [htmlDiffer.diffHtml](https://github.com/bem/html-differ/blob/master/README.ru.md#htmldifferdiffhtml)<br>
 **@param** *{Object}* - опции:<br>
 
@@ -320,7 +325,7 @@ var logger = require('html-differ/lib/logger');
 
 <img src='https://cloud.githubusercontent.com/assets/6376693/3648928/a6b9d48a-110d-11e4-8a07-d9b156145017.png'/>
 
-###Пример###
+### Пример
 
 ```js
 var fs = require('fs'),
@@ -348,7 +353,7 @@ var diff = htmlDiffer.diffHtml(html1, html2),
 logger.logDiffText(diff, { charsAroundDiff: 40 });
 ```
 
-##Использование в качестве программы##
+## Использование в качестве программы
 
 ```bash
 $ html-differ --help
@@ -370,7 +375,7 @@ $ html-differ --help
   PATH2 : Путь ко 2-ому HTML-файлу (обязательный аргумент)
 ```
 
-###Пример###
+### Пример
 
 ```bash
 $ html-differ путь/к/html1 путь/к/html2
@@ -380,7 +385,7 @@ $ html-differ --config=путь/к/конфигу --chars-around-diff=40 пут
 $ html-differ --preset=bem путь/к/html1 путь/к/html2
 ```
 
-###Конфигурационный файл###
+### Конфигурационный файл
 
 Рассмотрите следующий файл `config.json`:
 
@@ -424,3 +429,29 @@ $ html-differ --preset=bem путь/к/html1 путь/к/html2
 * `RegExp` – регулярное выражение для сопоставления с соответствующим значением в сравниваемом HTML. Имеет такой же синтаксис как и регулярные выражения в JavaScript, записанные в _literal notation_.
 
 * `}}` – закрывающий идентификатор _маски_.
+
+### Экранирование
+
+Правила экранирования символов такие же как и при использовании регулярных выражений в JavaScript, записанных в _literal notation_.
+
+Например, следующие два HTML будут считаться эквивалентными:
+
+```html
+<div id="{{\d\.\d}}">
+```
+
+```html
+<div id="1.1">
+```
+
+Если вы хотите хотите использовать `{{` или `}}` внутри маски, вам необходимо экранировать обе фигурные скобки, то есть `\{\}` или `\}\}`
+
+Например, следующие два HTML будут считаться эквивалентными:
+
+```html
+<div class="{{a\{\{b\}\}c}}">
+```
+
+```html
+<div class="a{{b}}c">
+```