Update docs

cssCheck · Apr 6, 2016 · 02484f7 · 02484f7
1 parent b3b4cc8
commit 02484f7
Show file tree

Hide file tree

Showing 4 changed files with 55 additions and 63 deletions.
diff --git a/README.md b/README.md
@@ -54,10 +54,7 @@ the project.
 
 ## API
 
-The autogenerated JSDoc API can be found on the separate branch [v2-jsdoc](https://github.com/bem/bem-core/tree/v2-jsdoc).
-
-Please note that "v2-jsdoc"'s content is updated automatically. Any fixes should go to the "v2" branch to the concrete
-block source code, as described in the [How to contribute](/CONTRIBUTING.md) guide.
+The autogenerated JSDoc API can be found on bem.info. E.g. JSDoc for `i-bem` is here https://en.bem.info/libs/bem-core/current/desktop/i-bem/jsdoc/
 
 ## Changelog
 

diff --git a/README.ru.md b/README.ru.md
@@ -55,10 +55,7 @@ This README is also available [in English](https://en.bem.info/libs/bem-core/).
 
 ## API
 
-Автосгенерированная документация на JavaScript API блоков (JSDoc) можно посмотреть в отдельной ветке [v2-jsdoc](https://github.com/bem/bem-core/tree/v2-jsdoc).
-
-Обратите внимание, содержимое ветки «v2-jsdoc» обновляется автоматически. Любые изменения необходимо отправлять
-в код соответствующих блоков в ветке «v2», как описано в [Руководстве по внесению изменений](/CONTRIBUTING.ru.md).
+Автосгенерированную документацию на JavaScript API блоков (JSDoc) можно посмотреть на bem.info. Например, для блока `i-bem` она доступна по ссылке https://ru.bem.info/libs/bem-core/current/desktop/i-bem/jsdoc/.
 
 ## История изменений
 
@@ -72,9 +69,9 @@ This README is also available [in English](https://en.bem.info/libs/bem-core/).
 
 ### Рабочая копия
 
-1. Получаем исходники нужной версии (например, `v1`):
+1. Получаем исходники нужной версии (например, `v2`):
    ```shell
-   $ git clone -b v1 git://github.com/bem/bem-core.git
+   $ git clone -b v2 git://github.com/bem/bem-core.git
    $ cd bem-core
    ```
 

diff --git a/common.docs/rationale/rationale.en.md b/common.docs/rationale/rationale.en.md
@@ -1,6 +1,6 @@
 # BEMHTML templating engine description and its benefits
 
-**BEMHTML** is a templating engine for thous who are using [BEM metodology](https://bem.info/method)
+**BEMHTML** is a templating engine for thous who are using [BEM metodology](https://en.bem.info/method)
 for web development.
 
 BEMHTML is:
@@ -123,22 +123,22 @@ If the `widgets` block has a JavaScript realization with usage of `i-bem.js` one
 to use the following template for passing JavaScript parameters into the block:
 
 ```js
-block widgets, js: { id: Math.random() * 1e4 }
+block('widgets').js()(function() {
+    return { id: Math.random() * 1e4 };
+});
 ```
 
 The resulting HTML:
 
 ```xml
-<div class="widgets i-bem" onclick="return { 'weather': { 'id': 4321 } }">
+<div class="widgets i-bem" data-bem='{ "weather": { "id": 4321 } }'>
   <div class="widgets__weather">4</div>
 </div>
 ```
 
 ### Syntax for data and templates description is based on JavaScript.
  - Declarative templates: the template consists of condition for usage (predicate)
  and data structure, that describes the resulting HTML (the template body).
- - JavaScript syntax is extend with a key-words (`block`, `elem`, `mods`, `elemMods`)
- for working with BEM entities.
  - For the templates an arbitrary JavaScript code can be used. There is no technical
  limitations placed by BEMHTML on operations in predicates or template. An efficiency
  and consistency of templates work is provided by developers agreements.
@@ -150,10 +150,10 @@ The resulting HTML:
 Definition of HTML tags in a declarative style:
 
 ```js
-block widgets {
-  tag: 'ul'
-  elem weather, tag: 'li'
-}
+block('widgets')(
+    tag()('ul'),
+    elem('weather').tag()('li')
+);
 ```
 
 The resulting HTML:
@@ -167,10 +167,10 @@ The resulting HTML:
 Arbitrary calculations performed in the template body:
 
 ```js
-block widgets, elem weather, content: {
-  var oldContent = applyNext()
-  return (oldContent > 0 ? '+' : '') + oldContent + ' °C'
-}
+block('widgets').elem('weather').content()(function() {
+    var oldContent = applyNext();
+    return (oldContent > 0 ? '+' : '') + oldContent + ' °C';
+});
 ```
 
 The resulting HTML:
@@ -211,15 +211,15 @@ The input-data:
 Templates defined in the library:
 
 ```js
-block header, tag: 'h1'
-block header, mod level 2, tag: 'h2'
+block('header').tag()('h1');
+block('header').mod('level', 2).tag()('h2');
 ```
 
 Templates defined in the project:
 
 ```js
-block header, tag: 'h2'
-block header, mod level 2, tag: 'h3'
+block('header').tag()('h2');
+block('header').mod('level', 2).tag()('h3');
 ```
 
 The result:
@@ -255,13 +255,13 @@ The input data is a name of Yandex user:
 The template selects the first letter of the name and wraps it into instantly generated element:
 
 ```js
-block ya-user, content: {
-  var oldContent = applyNext();
-  return [
-    { elem: 'first-letter', content: oldContent[0] },
-    oldContent.substring(1)
-  ]
-}
+block('ya-user').content()(function() {
+    var oldContent = applyNext();
+    return [
+        { elem: 'first-letter', content: oldContent[0] },
+        oldContent.substring(1)
+    ];
+});
 ```
 
 The resulting HTML:
@@ -473,7 +473,7 @@ their own templating engine because of the following reasons:
 ### A template of a project
 
 To start using BEHTML you need to clone [a project template](https://github.com/bem/project-stub).
-It has already: a prepared structure for a project, the blocks library [bem-bl](https://github.com/bem/bem-bl),
+It has already: a prepared structure for a project, the blocks library [bem-core](https://github.com/bem/bem-core),
 environment customized for the building process and the result viewing, and very simple static page.
 
 In fact, the template of this project is a startup for a HTML coder. It can be extended
@@ -483,6 +483,5 @@ with custom blocks, and any project can be based on it.
 
   * [Step-by-step BEMHTML guide](https://bem.info/technology/bemhtml/current/intro/)
   * [BEMHTML reference](https://bem.info/technology/bemhtml/current/reference/)
-  * [bem-tools reference](https://bem.info/tools/bem/bem-tools/)
-  * [The blocks bem-bl library documentation](https://bem.info/libs/bem-bl/)
+  * [The blocks bem-core library documentation](https://bem.info/libs/bem-core/)
 
diff --git a/common.docs/rationale/rationale.ru.md b/common.docs/rationale/rationale.ru.md
@@ -94,33 +94,34 @@ HTML-результат:
 Если блок `widgets` имеет JavaScript-реализацию с использованием `i-bem.js`, то для передачи JavaScript-параметров блоку можно использовать шаблон:
 
 ```js
-block widgets, js: { id: Math.random() * 1e4 }
+block('widgets').js()(function() {
+    return { id: Math.random() * 1e4 };
+});
 ```
 
 
 HTML-результат:
 
 ```xml
-<div class="widgets i-bem" onclick="return { 'weather': { 'id': 4321 } }">
+<div class="widgets i-bem" data-bem='{ "weather": { "id": 4321 } }'>
   <div class="widgets__weather">4</div>
 </div>
 ```
 
 
 ### Синтаксис описания данных и шаблонов основан на JavaScript
   - Декларативные шаблоны. Шаблон состоит из условий применения (предикат) и структуры данных, описывающей HTML-результат (тело шаблона).
-  - Для работы с БЭМ-сущностями синтаксис JavaScript расширен ключевыми словами (`block, elem, mods, elemMods`).
   - Возможность использовать произвольный JavaScript-код в шаблонах. BEMHTML не ставит технических ограничений на выполнение операций в предикате и теле шаблона. Эффективность и корректность работы шаблонов обеспечивается соглашениями, которым следуют разработчики.
   - Все BEMHTML-шаблоны компилируются в переносимый JavaScript, что позволяет выполнять шаблоны как на сервере, так и на клиенте.
 
 #### Примеры
 Объявление HTML-тегов для блоков в декларативном стиле:
 
 ```js
-block widgets {
-  tag: 'ul'
-  elem weather, tag: 'li'
-}
+block('widgets')(
+    tag()('ul'),
+    elem('weather').tag()('li')
+);
 ```
 
 
@@ -136,10 +137,10 @@ HTML-результат:
 Произвольные вычисления в теле шаблона:
 
 ```js
-block widgets, elem weather, content: {
-  var oldContent = applyNext()
-  return (oldContent > 0 ? '+' : '') + oldContent + ' °C'
-}
+block('widgets').elem('weather').content()(function() {
+    var oldContent = applyNext();
+    return (oldContent > 0 ? '+' : '') + oldContent + ' °C';
+});
 ```
 
 
@@ -180,16 +181,16 @@ HTML-результат:
 Шаблоны, определенные в библиотеке:
 
 ```js
-block header, tag: 'h1'
-block header, mod level 2, tag: 'h2'
+block('header').tag()('h1');
+block('header').mod('level', 2).tag()('h2');
 ```
 
 
 Шаблоны, определенные в проекте:
 
 ```js
-block header, tag: 'h2'
-block header, mod level 2, tag: 'h3'
+block('header').tag()('h2');
+block('header').mod('level', 2).tag()('h3');
 ```
 
 
@@ -225,13 +226,13 @@ block header, mod level 2, tag: 'h3'
 Шаблон — выделяет первую букву в имени пользователя и оборачивает ее в тут же сгенерированный элемент:
 
 ```js
-block ya-user, content: {
-  var oldContent = applyNext();
-  return [
-    { elem: 'first-letter', content: oldContent[0] },
-    oldContent.substring(1)
-  ]
-}
+block('ya-user').content()(function() {
+    var oldContent = applyNext();
+    return [
+        { elem: 'first-letter', content: oldContent[0] },
+        oldContent.substring(1)
+    ];
+});
 ```
 
 
@@ -418,14 +419,12 @@ plates.bind(html, data, map);
 
 Чтобы начать использовать BEMHTML, достаточно склонировать [шаблон проекта](https://github.com/bem/project-stub).
 
-Шаблон содержит подготовленную структуру проекта с подключенной библиотекой блоков [bem-bl](https://ru.bem.info/libs/bem-bl/), настроенным окружением для сборки и просмотра результата и примером очень простой статической страницы.
+Шаблон содержит подготовленную структуру проекта с подключенной библиотекой блоков [bem-core](https://ru.bem.info/libs/bem-core/), настроенным окружением для сборки и просмотра результата и примером простой статической страницы.
 
 Фактически шаблон проекта является готовым станком HTML-верстальщика. Его можно наполнять своими блоками и делать на его основе проекты любой сложности.
 
 ### Документация
 
   * [Вводное пошаговое руководство по BEMHTML](https://ru.bem.info/technology/bemhtml/current/intro/)
   * [Справочное руководство по BEMHTML](https://ru.bem.info/technology/bemhtml/current/reference/)
-  * [Руководство по bem-tools](https://ru.bem.info/tools/bem/bem-tools/)
-  * [Документация библиотеки блоков bem-bl](https://ru.bem.info/libs/bem-bl/)
-
+  * [Документация библиотеки блоков bem-core](https://ru.bem.info/libs/bem-core/)