Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Update README.md and README.ru.md

  • Loading branch information...
commit 2ca9f04b5550380724e6b885b643b5493365bc6f 1 parent 3f6a77a
Sergey Belov arikon authored
Showing with 41 additions and 2,510 deletions.
  1. +17 −1,235 README.md
  2. +20 −1,271 README.ru.md
  3. +3 −3 docs/index/index.en.md
  4. +1 −1  docs/index/index.ru.md
1,252 README.md
View
@@ -1,1240 +1,22 @@
-# BEM Tools [![Build Status](https://secure.travis-ci.org/bem/bem-tools.png?branch=nodejs)](http://travis-ci.org/bem/bem-tools)
-Toolkit to work with files based on [BEM methodology](http://bem.github.com/bem-method/pages/beginning/beginning.en.html).
+# BEM Tools
+[![Build Status](https://secure.travis-ci.org/bem/bem-tools.png?branch=master)](http://travis-ci.org/bem/bem-tools)
-## Installation
-You need [NodeJS 0.6+](http://nodejs.org/) or later and [npm 1.x](http://npmjs.org/).
-After this it suffices `npm -g install bem`.
+BEM tools is a toolkit to work with files based on [BEM methodology](http://bem.info/method/).
- * Install [nodejs](http://nodejs.org)
+It allows you:
- https://github.com/joyent/node/wiki/Installation
+* creating entities;
+* building final runtime;
+* working with build declarations: merge, subtract and intersect them;
+* building the whole project using bem make command;
+* launching development server on the projects source tree using bem server command.
- * Install [npm](http://npmjs.org)
+See also:
- curl http://npmjs.org/install.sh | sudo sh
-
- * After installation configure `NODE_PATH`:
-
- echo 'export NODE_PATH="'$(npm root -g)'"'>> ~/.bashrc && . ~/.bashrc
-
- or
-
- echo 'export NODE_PATH="'$(npm root -g)'"'>> ~/.zshrc && . ~/.zshrc
-
- * Install [bem-tools](https://github.com/bem/bem-tools)
-
- sudo npm -g install bem
-
- * Use this command [bem-tools](https://github.com/bem/bem-tools) to install the development version
-
- sudo npm -g install bem@unstable
-
-### bem-bl
-
-If you are going to use `bem` with
-[bem-bl](https://github.com/bem/bem-bl) block library, you should also install
-[XJST](https://github.com/veged/xjst) and [OmetaJS](https://github.com/veged/ometa-js).
-
- sudo npm -g install xjst ometajs
-
-## Usage
-Get the list of commands with `bem --help`.
-To read about commands and subcommands use `bem COMMAND --help` or `bem COMMAND SUBCOMMAND --help`.
-
-### Shell completion
-
-#### bash
-
-To make completions for bem-tools available in your bash, run following
-command (ensure that you have bash-completion installed, first). Run this
-
- bem completion > /path/to/etc/bash_completion.d/bem
-
-and restart bash.
-
-If you aren't using `bash-completion`, you can add `bem completion` to your `.bashrc` and reload:
-
- bem completion >> ~/.bashrc
- source ~/.bashrc
-
-#### zsh
-
-If you use `zsh`, you can add `bem completion` to your `.zshrc` and reload:
-
- bem completion >> ~/.zshrc
- source ~/.zshrc
-
-### Commands
-#### bem create
-
-You can create following entities using `bem create`:
-
- * levels of defenition
- * blocks
- * elements
- * modifiers
-
-##### Level of defenition
-
-Level of defenition is a directory that holds blocks and an utility directiry `.bem`.
-
-A `.bem` directory holds configuration of a current level:
-
- * naming convention
- * links to the technologies
-
-An example of technologies' links (this is `blocks-desktop` level of
-`bem-bl` block library):
-
- https://github.com/bem/bem-bl/blob/master/blocks-common/.bem/level.js
-
-###### Create new level of defenition named `blocks` under current directory:
-
- bem create level blocks
-
-###### Create a level for pages
-
-In `bem-tools` terms pages are blocks as well and a directory which holds pages is a level of
-defenition itself. To create such a directory run this:
-
- bem create level pages
-
-###### Create a level based on an existing one
-
-`bem create level` allows to use an existing level as a prototype for a level it creates.
-
- bem create level --level bem-bl/blocks-desktop blocks
-
-##### Block
-
-Block is a bunch of files in different technologies that hold block's implementation.
-
-###### Create a new block
-
- bem create block b-my-block
-
-By default, a block has several techs: (`bemhtml`, `css`, `js`).
-
-###### Create a new block using concrete tech
-
-Flags -t (-T) are to create files of technologies you need:
-
- bem create block -t deps.js b-my-block
- // Creates a block implementation in deps.js technology, ecxept of default techs.
-
- bem create block -T css b-my-block
- // Creates only CSS technology for a block
-
- bem create block -T bem-bl/blocks-desktop/i-bem/bem/techs/bemhtml.js b-my-block
- // -T flag is useful when you need to add a new tech to the block existed
-
-The value of this flag may be either tech's name (e.g `css`) or a path to tech module.
-
-Tech names may be listed in `.bem/level.js` file of a level.
-E.g., https://github.com/bem/bem-bl/blob/master/blocks-common/.bem/level.js
-
-You can find the examples of tech modules in the repo:
-
- https://github.com/bem/bem-tools/tree/master/lib/techs
-
-###### Create element
-
-Create element named `elem` for block `b-my-block`
-
- bem create elem -b b-my-block elem
-
-###### Create modifier of block or element
-
-Create modifier named `mod` for block `b-my-block`
-
- bem create mod -b b-my-block mod
-
-Create modifier named `mod` having value `val` for block `b-my-block`
-
- bem create mod -b b-my-block mod -v val
-
-Create modifier named `mod` for element `elem` of block `b-my-block`
-
- bem create mod -b b-my-block -e elem mod
-
-Create modifier named `mod` having value `val` for element `elem` of block `b-my-block`
-
- bem create mod -b b-my-block -e elem mod -v val
-
-###### Create any BEM entity using `bem create` command only
-
-You can create any BEM entities or bunches of them using `bem create` command.
-
-Create blocks named `b-block1` and `b-block2`
-
- bem create -b b-block1 -b b-block2
-
-Create elements named `elem1` and `elem2` for block `b-block`
-
- bem create -b b-block -e elem1 -e elem2
-
-Create modifier names `mod` of block `b-block`
-
- bem create -b b-block -m mod
-
-Create modifier named `mod` of block `b-block` having values `val1` and `val2`
-
- bem create -b b-block -m mod -v val1 -v val2
-
-Create modifier named `mod` for element `elem` of block `b-block`
-
- bem create -b b-block -e elem -m mod
-
-Create modifier named `mod` having values `val1` and `val2` for element `elem` of block `b-block`
-
- bem create -b b-block -e elem -m mod -v val1 -v val2
-
-#### bem build
-
-`bem build` command builds page files in different techs, according to a page declaration.
-
-##### Create bemdecl.js file from page's bemjson
-
- bem build \
- -l bem-bl/blocks-common -l bem-bl/blocks-desktop \
- -l blocks -l pages/index/blocks \
- -d pages/index/index.bemjson.js -t bemdecl.js \
- -o pages/index -n index
-
-You can use either tech's name or a path to its module as a value of -t flag. This
-module says how to build a final file from a declaration.
-
-E.g., this is a module for `deps.js`: https://github.com/bem/bem-tools/blob/master/lib/techs/deps.js.js
-
-##### Create deps.js file from bemdecl.js
-
- bem build \
- -l bem-bl/blocks-common -l bem-bl/blocks-desktop \
- -l blocks -l pages/index/blocks \
- -d pages/index/index.bemdecl.js -t deps.js \
- -o pages/index -n index
-
-###### Create js and css files for a page from deps.js
-
- bem build \
- -l bem-bl/blocks-common -l bem-bl/blocks-desktop \
- -l blocks -l pages/index/blocks \
- -d pages/index/index.deps.js -t css \
- -o pages/index -n index
-
- bem build \
- -l bem-bl/blocks-common -l bem-bl/blocks-desktop \
- -l blocks -l pages/index/blocks \
- -d pages/index/index.deps.js -t js \
- -o pages/index -n index
-
-###### Create bemhtml.js template for a page from deps.js
-
- bem build \
- -l bem-bl/blocks-common -l bem-bl/blocks-desktop \
- -l blocks -l pages/index/blocks \
- -d pages/index/index.bemhtml.js \
- -t bem-bl/blocks-desktop/i-bem/bem/techs/bemhtml.js \
- -o pages/index -n index
-
-There is an example how pages are built using `bem build` in our test project that uses
-`bem-bl` block library: https://github.com/toivonen/bem-bl-test/blob/master/GNUmakefile
-
-#### bem decl
-
-`bem decl` is to work with declaration files. Thus,
-
- * to merge two or more decls into one
- * «subtract» decls
-
-All subcommands of `bem decl` can take either bemdecl.js or deps.js as input declaration formats.
-as input declaration (via `-d` flag).
-
-Ouput data (`-o` flag) is always in `deps.js` format.
-
-##### bem decl merge
-
-`bem decl merge` is to merge two or more decls into one. It is useful if you need, for example, to build
-one file for several pages.
-
-###### Create a decl for all the pages
-
- bem decl merge \
- -d pages/index/index.deps.js \
- -d pages/about/about.deps.js \
- -d pages/search/search.deps.js \
- -o pages/common/common.deps.js
-
-##### bem decl subtract
-
-`bem decl subtract` is to «subtract» all next decls from the first one.
-You may use it to create a bundle that you request by application.
-
-###### Create a decl for a "heavy" block requested by application
-
- bem decl subtract \
- -d bundles/heavy-block/heavy-block.deps.js \
- -d pages/common/common.deps.js \
- -o bundles/heavy-block/heavy-block.bundle.js
-
-##### bem make
-`make` command implements the build process of the BEM projects. You don't have to write your own scripts or makefiles (for GNU make or other build system) to build your BEM project.
-
-During the build `bem make`
-
- * fetches the block libraries
- * builds the levels content
- * builds the bundles
- * generates the templates (`bemhtml`)
- * generates `html` from `bemjson.js`
- * generates the static content files (`js`, `css`)
- * expands the `@import` derectives in `css` files (`borschik`)
- * expands the `borschik:link:include` directives in `js` files (`borschik`)
- * optimizes `css` files using `csso`
- * optimizes `js` files using `uglifyjs`
-
-##### bem server
-
-`bem server` command runs a development server. It makes the project files being accessible via the http protocol.
-This includes the files which are generated during the build process. So the server can be useful when you develop the
-static pages using the bem method. You just edit the files, refresh the browser and get updated page. All the files
-which are affected by your changes will be rebuilt automatically.
-In the case your project has no static pages you can configure your backend server and production environment to retrieve
-the stylesheets and scripts from the bem server. bem server accepts connections via normal TCP socket and via UNIX domain socket.
-
-By default the current directory is considered as the project root. You can change it using the --project (-r) option.
-
-Default TCP port is 8080. You can change it using the --port (-p) option.
-
-When requested URL is mapped to a directory, the server will check if there is an index.html file or it's possible to build it.
-In the case one of these is true the content of the file will be returned to browser. The directory content listing will be returned
-otherwise.
-
-#### Build configuration
-
-There is a default build behavior programmed in the build system. The configuration files allow to adjust it a little or change it completely.
-To make `bem make` work you should have `.bem/level.js` file within your levels. It should contain the `getTechs()` function,
-which returns object with the tech definitions used on the level.
-And it should have function `getConfig()`:
-
-```js
-var extend = require('bem/lib/util').extend;
-
-exports.getTechs = function() {
- return {
- 'bemjson.js': '',
- 'js': 'js-i',
- 'bemhtml': '../../bem-bl/blocks-common/i-bem/bem/techs/bemhtml.js',
- 'priv.js': '../../.bem/techs/priv.js',
- 'html': '../../bem-bl/blocks-common/i-bem/bem/techs/html'
- };
-};
-
-exports.getConfig = function() {
-
- return extend({}, this.__base() || {}, {
-
- bundleBuildLevels: this.resolvePaths([
- '../../bem-bl/blocks-common',
- '../../bem-bl/blocks-desktop',
- '../../blocks'
- ])
-
- });
-
-};
-```
-
-`getTechs()` returns an object with used techs. Object properties (for example `'bemjson.js'`, `'js'`, `'bemhtml'`) define the
-tech names, object values specify the paths to the appropriate tech files (`''`, `'js-i'`, `'../../bem-bl/blocks-common/i-bem/bem/techs/bemhtml.js'`).
-A path can be relative or absolute, it can be empty, or it can specify just a file name. When the latter case is used the
-tech will be considered being standard (bundled with bem-tools) and the file will be looked up in the `[bem]/lib/techs` folder.
-
-`getConfig()` function returns an object with the `bundleBuildLevels` property, containing the array of the used block levels.
-
-Another (optional) configuration file is `.bem/make.js` located in the project root. Core of the build system is a graph
-of nodes, each of which executes own part of the whole build process. `make.js` allows you to adjust nodes behavior and change build graph.
-There are several standard node types:
- * `Node` - base node, implements basic functionality. All other nodes are inherited from this one
- * `LibraryNode` - retrieves external libraries
- * `LevelNode` - inspects the contents of a level and constructs graph branch accordingly to build the level
- * `BundlesLevelNode` - inherits from `LevelNode` and builds the bundles levels
- * `BundleNode` - constructs graph branch for a bundle
- * `MergedBundleNode` - builds merged bundle (aka common bundle)
- * `BorschikNode` - processes files with the `borschik` utility, `csso` and `uglifyjs`
- * `Arch` - builds initial graph, which by default consists of `LibraryNode`, `BundlesLevelNode` and `LevelNode` nodes
-
-To alter build system behavior for your project you need to alter behavior of the nodes. This can be achieved by adding `MAKE.decl()` calls in the `.bem/make` file. `MAKE.decl()` is a helper
-function which accepts two arguments. First one is the node name which we want to change, second - an object with overriding methods.
-
-```js
-MAKE.decl('BundleNode', {
-
-});
-```
-
-Node classes have some fundamental methods, which take care about the build process:
- * `isValid()` - validates the node - indicates is there a need to rebuild it or not. If node artifacts were built during
- previous build and dependency nodes were not rebuilt after that, the node is considered being valid. In other words
- if you changed a file after first build then only the nodes which depend on this file will be rebuilt during the
- consequent build.
- * `make()` - implements the build logic for the node.
- * `run()` - node entry point. In the default implementation it executes isValid method and in case it returns false the make method will be executed next.
- * `clean()` - removes the build artifacts for the node.
-
-##### Sample configuration files for some typical tasks
-
-###### Build of static html, css, js, bemhtml templates on the level `pages`. Bemjson file is used as a source file. Also using blocks level `blocks`, and also `blocks-common` and `blocks-desktop` from bem-bl.
-
-`pages/.bem/level.js`
-```js
-var extend = require('bem/lib/util').extend;
-
-exports.getTechs = function() {
-
- return {
- 'bemjson.js': '',
- 'bemdecl.js': 'bemdecl.js',
- 'deps.js': 'deps.js',
- 'js': 'js-i',
- 'css': 'css',
- 'bemhtml': '../../bem-bl/blocks-common/i-bem/bem/techs/bemhtml.js',
- 'html': '../../bem-bl/blocks-common/i-bem/bem/techs/html.js'
- };
-
-};
-
-exports.getConfig = function() {
-
- return extend({}, this.__base() || {}, {
-
- bundleBuildLevels: this.resolvePaths([
- '../../bem-bl/blocks-common',
- '../../bem-bl/blocks-desktop',
- '../../blocks'
- ])
-
- });
-
-};
-```
-
-`.bem/make.js`
-```js
-MAKE.decl('Arch', {
-
- getLibraries: function() {
-
- return {
- 'bem-bl': {
- type: 'git',
- url: 'git://github.com/bem/bem-bl.git'
- }
- };
-
- }
-
-});
-
-MAKE.decl('BundleNode', {
-
- getTechs: function() {
-
- return [
- 'bemjson.js',
- 'bemdecl.js',
- 'deps.js',
- 'bemhtml',
- 'css',
- 'js',
- 'html'
- ];
- }
-
-});
-```
-
-
-###### Build of css, js, bemhtml tamples on the level `pages`. `bemdecl` declaration file is used as a source file. Also using blocks level `blocks`, and also `blocks-common` and `blocks-desktop` from bem-bl.
-
-`pages/.bem/level.js`
-```js
-var extend = require('bem/lib/util').extend;
-
-exports.getTechs = function() {
-
- return {
- 'bemdecl.js': 'bemdecl.js',
- 'deps.js': 'deps.js',
- 'js': 'js-i',
- 'css': 'css',
- 'bemhtml': '../../bem-bl/blocks-common/i-bem/bem/techs/bemhtml.js'
- };
-
-};
-
-exports.getConfig = function() {
-
- return extend({}, this.__base() || {}, {
-
- bundleBuildLevels: this.resolvePaths([
- '../../bem-bl/blocks-common',
- '../../bem-bl/blocks-desktop',
- '../../blocks'
- ])
-
- });
-
-};
-```
-
-`.bem/make.js`
-```js
-MAKE.decl('Arch', {
-
- getLibraries: function() {
-
- return {
- 'bem-bl': {
- type: 'git',
- url: 'git://github.com/bem/bem-bl.git'
- }
- };
-
- }
-
-});
-
-MAKE.decl('BundleNode', {
-
- getTechs: function() {
-
- return [
- 'bemdecl.js',
- 'deps.js',
- 'bemhtml',
- 'css',
- 'js'
- ];
- }
-
-});
-```
-
-###### The block libraries
-
-The block libraries are not used by default. To use a library add the following code to `.bem/make.js`:
-
-```js
-MAKE.decl('Arch', {
- getLibraries: function() {
-
- return {
- 'bem-bl': {
- type: 'git',
- url: 'git://github.com/bem/bem-bl.git'
- }
- };
- }
-});
-```
-
-
-Where:
- * `'Arch'` - node class name which we want to override. Arch builds initial build graph.
- * `getLibraries` - a method of the Arch class, which returns the associative array of the used block libraries.
- * `'bem-bl'` — the name of the library and the folder where it will be copied to.
- * `type` - the type of the library source. We use git in the example, so the library will be checked out of a git repository.
- Possible values are: `'git'`, `'svn'`, `'symlink'`. `svn` works the same as `git`, but with svn repositories. `symlink` -
- creates a symbolic link in the project folder to the library folder. The library path is specified by the `relative` property.
- * `url` - URL to the svn/git repository
-
-Also you can use shorter code:
-
-```js
-MAKE.decl('Arch', {
- libraries: {
- 'bem-bl': {
- type: 'git',
- url: 'git://github.com/bem/bem-bl.git'
- }
- }
-});
-```
-
-###### Block levels
-
-The folders in the project root matching the `blocks*` mask are considered being the blocks level. You can change this using the following code:
-
-```js
-MAKE.decl('Arch', {
- blocksLevelsRegexp: /regular expression/,
-});
-```
-
-The regular expression will be used to match the folders in the project root. A folder which does match will be used as the blocks level.
-
-If you need some logic for the levels selection you can achieve that by overriding the `createBlocksLevelsNodes()` method:
-
-```js
-MAKE.decl('Arch', {
- createBlocksLevelsNodes: function(parent, children) {
- // Create the LevelNode instance
- var node1 = new LevelNode(...);
- // Add it into the graph
- this.arch.setNode(node1, parent, children);
-
- var node2 = new LevelNode(...);
- this.arch.setNode(node2, parent, children);
-
- // return an array with the Ids of the created nodes
- return [node1.getId(), node2.getId()];
- }
-});
-```
-
-###### The bundles and the pages
-
-The folders in the project root matching the `pages*` abd `bundles*` masks are considered being bundle level. You can change this using the following code:
-
-```js
-MAKE.decl('Arch', {
- bundlesLevelsRegexp: /regular expression/,
-});
-```
-
-And for more precise control:
-
-```js
-MAKE.decl('Arch', {
-
- getBundlesLevels: function() {
- return [
- 'pages-desktop',
- 'pages-touch',
- 'bundles/common'
- ];
- }
-
-});
-```
-
-
-For every bundle the following target files are built by default:
-
- * `.bemhtml.js`
- * `.html`
- * `.css`
- * `.ie.css`
- * `.js`
- * `_*.css`
- * `_*.ie.css`
- * `_*.js`
-
-and the intermediate:
-
- * `.bemdecl.js`
- * `.deps.js`
- * `.deps.js.deps.js`
- * `.bemhtml.js.meta.js`
- * `.js.meta.js`
- * `.css.meta.js`
- * `.ie.css.meta.js`
-
-`.bemjson.js` file is considered as a source file. If it does not exist, `.bemdecl.js` is used then. If `.bemdecl.js`
- does not exist too, `.deps.js` will be used. For the cases when `.bemjson.js` does not exist static html will not be built.
-
-To change the list of the file techs to use, add the following code into `.bem/make.js`:
-
-```js
-MAKE.decl('BundleNode', {
-
- getTechs: function() {
- return [
- 'bemdecl.js',
- 'deps.js',
- 'bemhtml',
- 'css',
- 'js',
- 'priv.js'
- ];
- }
-});
-```
-
-**IMPORTANT:** Techs in the list should be in the order of dependency on each other. Tech B, which depends on A, should go **bellow** A. The source file tech should also be in the list, for example `bemjson.js`.
-
-###### The merged bundles
-The merged bundle — a bundle which includes the declarations of all bundles on the level. So for example css in a merged bundle will contain the styles from all of the bundles.
-
-The following code will enable the build of the merged bundles for all levels:
-
-```js
-MAKE.decl('BundlesLevelNode', {
- buildMergedBundle: function() {
- return true;
- }
-});
-```
-
-If you need a merged bundle for the selected levels only (for `pages-desktop` level in the example):
-
-```js
-var PATH = require('path');
-
-MAKE.decl('BundlesLevelNode', {
- buildMergedBundle: function() {
- if (this.getLevelPath() === 'pages-desktop') return true;
-
- return false;
- }
-});
-```
-
-The `getLevelPath()` method returns the relative path for the level. We can use it to decide should we enable some special logic for current level or not.
-
-To change the merged bundle name use the code:
-```js
-MAKE.decl('BundlesLevelNode', {
-
- mergedBundleName: function() {
- return 'mymergedbundle';
- }
-
-});
-```
-
-##### Production and Development builds
-By changing the `YENV` environment variable value, you can switch between the production and development builds.
-In production mode static files are processed with the `borschik` utility. It expands the include directives and puts the
-result content in the file with the `_` prefix. For example, `index.css` has the directives to include `blocks/block1.css`
-and `blocks/block2.css`. `_index.css` will be created with the content of both `block1.css` and `block2.css`. Also the
-`css` files are optimized with the `csso` utility, the `js` files are optimized with `uglifyjs`. In development mode
-`borschik` is used only, no optimizations take the place.
-
-The default mode is development. To use the production mode set `YENV` to `production`.
-
-Environment variables can be set in `.bem/make.js`, for example
-
-```js
-process.env.YENV = 'production';
-```
-
-### Configuration files
-#### Level (.bem/level.js)
-
-A level should have `.bem/level.js` configuration file which contains the meta information about the level:
-
-- the mapping rules between the BEM entities and the file system
-- the thech modules defined on the level
-- the meta information for the build system
-
-When the `bem create level` command is used to create a level the empty `.bem/level.js` file will be also created.
-Which means that this level is «standard» one. The logic for standard level is defined in the `Level` class within
-[lib/level.js](https://github.com/bem/bem-tools/blob/master/lib/level.js).
-
-As the `.bem/level.js` file is a CommonJS module it's easy to override the level's behavior. `bem-tools` creates a new
-class inherited from the standard `Level` class using export of this module as a class extention (under the hood the
-[inherit](https://github.com/dfilatov/node-inherit) module is used).
-
-In the example bellow the `getTechs()` method is overriden.
-
-```js
-exports.getTechs = function() {
-
- return {
- 'bemjson.js': ''
- 'css': 'path/to/my/css-tech-module.js'
- }
-
-};
-```
-
-##### The levels inheritance
-
-To avoid the copy and paste of the same code among several levels you can put the common parts into the independant
-modules and inherit them. This way you can build up the levels hierarchy.
-
-To specify the base level you should export it in the `baseLevelPath` property. For example
-
-```js
-exports.baseLevelPath = require.resolve('path/to/base/level.js');
-```
-
-It's also possible to create the inherited levels using the command
-
- bem create level <your-level-name> --level path/to/base/level.js
-
-##### The mapping rules between BEM entities and the file system
-
-By default the following mapping scheme is used (this example is about the `css` tech):
-
-```
-level/
- block/
- __elem/
- _mod/
- block__elem_mod_val.css
- block__elem.css
- _mod/
- block_mod_val.css
- block.css
-```
-
-If you want to use a custom scheme override the appropriate `match*()` and `get*()` methods in the `.bem/level.js` file.
-
-##### Tech modules defined on the level
-
-To define a list of the tech modules used on the level export the `getTechs()` function. It should return an object
-the keys of which contain the tech names and the values contain on of the following:
-
-- the absolute tech path;
-- a short tech name — a tech module with such name bundled with `bem-tools` will be used;
-- an empty string — the default tech implementation will be used.
-
-By deault there is no any techs defined explicitly on a level. In the case some techs are used within such a level
-by a short name (for example `css`, `js`, etc) then the appropriate tech modules bundled with `bem-tools` are loaded.
-If such do exist of course. The full list of such techs can be found there [lib/techs](https://github.com/bem/bem-tools/tree/master/lib/techs).
-
-If you try to use a tech which was not defined explicitly and which is not bundled with `bem-tools` - the default tech
-will be used (see [lib/tech.js](https://github.com/bem/bem-tools/blob/master/lib/tech.js)).
-
-The techs defined on the level are used:
-
-- by the `bem create` command
-- by the `bem build` command
-- by the file system introspection (see the `getLevelByIntrospection()` of the `Level` class)
-- during the project build with the `bem make` and `bem build` commands
-
-It's recommended to define explicitly the used techs.
-
-##### The build system meta information
-
-To let the build system know which levels should be used to build one bundle or another set the `bundleBuildLevels`
-property within an object returned by the `getConfig()` function to an array of these levels.
-
-```js
-exports.getConfig = function() {
-
- return extend({}, this.__base() || {}, {
-
- bundleBuildLevels: this.resolvePaths([
- // your levels here
- ])
-
- });
-
-};
-```
-
-### Tech modules
-
-#### API
-
-Look for the documentation in the source code [lib/tech.js](https://github.com/bem/bem-tools/blob/master/lib/tech.js).
-
-#### Creating tech module
-
-There are many ways to write a tech module.
-
-Whatever manner you choose you can refer to the tech object from methods using `this`.
-Any base method is available using `this.__base(...)` call. Tech class can be referenced
-using `this.__class`. Thanks to [inherit](https://github.com/dfilatov/node-inherit) module
-that helps us to organize inheritance here.
-
-##### Trivial way
-
-You only need to declare regular CommonJS module and export some of its
-functions to redefine them. By default your tech will derive from base `Tech` class
-defined in module [lib/tech.js](https://github.com/bem/bem-tools/blob/master/lib/tech.js).
-
-```js
-exports.getCreateResult = function(...) {
- // your code goes here
-};
-```
-
-You can also group all methods in `techMixin` object. This is a recommended way.
-
-```js
-exports.techMixin = {
-
- getCreateResult: function(...) {
- // your code goes here
- }
-
-};
-```
-
-##### Simple way
-
-Besides function, you can also export `baseTechPath` variable to define an
-absolute path to a tech module you are extending. Or you can
-
-```js
-var BEM = require('bem');
-
-exports.baseTechPath = BEM.require.resolve('./techs/css');
-```
-
-You can also derive from tech module by its name using `baseTechName` variable.
-Base class will be chosen in the context of level where tech module will be used.
-
-```js
-exports.baseTechName = 'css';
-```
-
-In this example new tech will derive from `css` tech declared on level in file
-`.bem/level.js`.
-
-##### Hardcore way
-
-If you need a total control, you can create a module that exports
-the whole `Tech` class.
-
-```js
-var INHERIT = require('inherit'),
- BaseTech = require('bem/lib/tech').Tech;
-
-exports.Tech = INHERIT(BaseTech, {
-
- create: function(prefix, vars, force) {
- // do some creation work
- },
-
- build: function(prefixes, outputDir, outputName) {
- // organize own build process
- }
-
-});
-```
-
-If you need to base your tech on an existing one written in a simple way use
-`getTechClass()` function to get its class. We recommend to use `getTechClass()`
-function all the time to not depend on tech implementation.
-
-```js
-var INHERIT = require('inherit'),
- BEM = require('bem'),
- BaseTech = BEM.getTechClass(require.resolve('path/to/tech/module'));
-
-exports.Tech = INHERIT(BaseTech, {
-
- // your overrides go here
-
-});
-```
-
-##### Examples of tech modules
-
- * [bem-tools/lib/techs/](https://github.com/bem/bem-tools/tree/nodejs/lib/techs)
- * [bem-bl/blocks-common/i-bem/bem/techs/](https://github.com/bem/bem-bl/tree/master/blocks-common/i-bem/bem/techs)
-
-### API usage
-
-Starting from 0.2.0 version it is possible to use `bem-tools` from API.
-
-`bem` module exports the object of a command that has an `api` property.
-It is to use in this way:
-
-```js
-var Q = require('q'),
- BEM = require('bem').api,
-
- techs = ['css', 'js'],
- blocks = ['b-block1', 'b-block2'];
-
-Q.when(BEM.create.block({ forceTech: techs }, { names: blocks }), function() {
- console.log('Create blocks: %s', blocks.join(', '));
-});
-```
-
-The example above shows that you can use all the commands (including subcommands).
-
-A command accepts two args:
-
- * **Object** `opts` command options
- * **Object** `args` command arguments
-
-It returns an object of `Q.promise` type.
-
-#### BEM.create
-
-Commands to create BEM entities.
-
-##### BEM.create.level()
-
-Creates a level of defenition.
-
-###### Options
-
- * **String** `outputDir` a directory of output (current directory by default)
- * **String** `level` a «prototype» of the level
- * **Boolean** `force` key to force level's creating if it already exists
-
-###### Arguments
-
- * **Array** `names` Namef of levels you are creating
-
-###### Example
-
-```js
-var PATH = require('path'),
- Q = require('q'),
- BEM = require('bem').api,
-
- outputDir = PATH.join(__dirname, 'levels'),
- levels = ['blocks-common', 'blocks-desktop'];
-
-Q.when(BEM.create.level({ outputDir: outputDir }, { names: levels }), function() {
- console.log('Create levels %s at %s', levels.join(', '), outputDir);
-});
-```
-
-##### BEM.create()
-
-Creates BEM entities: blocks, elems, modifiers and their values.
-
-###### Options
-
- * **String** `level` Level directory (current directory by default)
- * **Array** `block` Block name (required)
- * **Array** `elem` Element name
- * **Array** `mod` Modifier name
- * **Array** `val` Modifier value
- * **Array** `addTech` Add the techs listed
- * **Array** `forceTech` Use only the techs listed
- * **Array** `noTech` Exclude the techs listed
- * **Boolean** `force` Force creating BEM entities files (rewrite)
-
-###### Example
-
-```js
-var Q = require('q'),
- BEM = require('bem').api,
-
- forceTechs = ['css'],
- block = 'b-header',
- elem = 'logo',
- mods = ['lang'],
- vals = ['ru', 'en'];
-
-Q.when(BEM.create({ forceTechs: forceTechs, block: block, mod: mods, val: vals }), function() {
- console.log('Create mod %s of block %s with vals %s', mods.join(', '), block, vals.join(', '));
-});
-
-Q.when(BEM.create({ forceTechs: forceTechs, block: block, elem: elem, mod: mods, val: vals }), function() {
- console.log('Create mod %s of elem %s of block %s with vals %s', mods.join(', '), elem, block, vals.join(', '));
-});
-```
-
-##### BEM.create.block()
-
-Creates a block.
-
-###### Options
-
- * **String** `level` A directory of block's level. (Current directory by default)
- * **Array** `addTech` Add the techs listed
- * **Array** `forceTech` Use these techs only
- * **Array** `noTech` Exclude these techs
- * **Boolean** `force` Force files creating
-
-###### Arguments
-
- * **Array** `names` List of block names
-
-###### Example
-
-```js
-var Q = require('q'),
- BEM = require('bem').api,
-
- addTechs = ['bemhtml'],
- blocks = ['b-header'];
-
-Q.when(BEM.create.block({ addTech: addTechs }, { names: blocks }), function() {
- console.log('Create blocks: %s', blocks.join(', '));
-});
-```
-
-##### BEM.create.elem()
-
-Creating an element.
-
-###### Options
-
- * **String** `level` A directory of level. (Current directory by default)
- * **String** `blockName` A name of element's block (required)
- * **Array** `addTech` Add the techs listed
- * **Array** `forceTech` Use only the techs listed
- * **Array** `noTech` Exclude the techs listed
- * **Boolean** `force` Force creating element's files (to rewrite them)
-
-###### Arguments
-
- * **Array** `names` List of element names
-
-###### Example
-
-```js
-var Q = require('q'),
- BEM = require('bem').api,
-
- addTechs = ['bemhtml', 'title.txt'],
- block = 'b-header',
- elems = ['logo'];
-
-Q.when(BEM.create.elem({ addTech: addTechs, blockName: block }, { names: elems }), function() {
- console.log('Create elems %s of block %s', elems.join(', '), block);
-});
-```
-
-##### BEM.create.mod()
-
-Creating a modifier for a block or an element.
-
-###### Options
-
- * **String** `level` Level directory (current directory by default)
- * **String** `blockName` Block name of this modifier (required)
- * **String** `elemName` Element name
- * **Array** `modVal` Modifier value
- * **Array** `addTech` Add the techs listed
- * **Array** `forceTech` Use only the techs listed
- * **Array** `noTech` Exclude the techs listed
- * **Boolean** `force` Force creating modifier files (rewrite)
-
-###### Arguments
-
- * **Array** `names` List of modifier
-
-###### Example
-
-```js
-var Q = require('q'),
- BEM = require('bem').api,
-
- forceTechs = ['css'],
- block = 'b-header',
- elem = 'logo',
- mods = ['lang'],
- vals = ['ru', 'en'];
-
-Q.when(BEM.create.mod({ forceTechs: forceTechs, blockName: block, modVal: vals }, { names: mods }), function() {
- console.log('Create mod %s of block %s with vals %s', mods.join(', '), block, vals.join(', '));
-});
-
-Q.when(BEM.create.mod({ forceTechs: forceTechs, blockName: block, elemName: elem, modVal: vals }, { names: mods }), function() {
- console.log('Create mod %s of elem %s of block %s with vals %s', mods.join(', '), elem, block, vals.join(', '));
-});
-```
-
-#### BEM.build()
-
-Build files from blocks.
-
-###### Options
-
- * **String** `outputDir` An output directory (current directory by default)
- * **String** `outputName` A filename (its prefix) for output
- * **Level** `outputLevel` Output level for BEM entity to create
- * **String** `block` Block name
- * **String** `elem` Element name
- * **String** `mod` Modifier name
- * **String** `val` Modifier name
- * **String** `declaration` A filename of input declaration (required)
- * **Array** `level` List of levels to use
- * **Array** `tech` List of techs to build
-
-You should use one of the following to specify output prefix:
-
- * `outputName` to specify full path-prefix
- * `outputDir` plus `outputName` to specify directory path and file prefix (they will be joined for you)
- * `outputLevel` plus properties describing BEM entity: `block`, `elem`, `mod` and `val` (path-prefix will
- be constructed for you using level file mapping scheme)
-
-###### Example
-
-```js
-var Q = require('q'),
- B = require('bem'),
- BEM = B.api,
-
- decl = 'page.deps.js',
- outputDir = 'build',
- outputName = 'page',
- levels = ['blocks-common', 'blocks-desktop'],
- techs = ['css', 'js'];
-
-// use outputDir and outputName options
-Q.when(
- BEM.build({
- outputDir: outputDir,
- outputName: outputName,
- declaration: decl,
- level: levels,
- tech: techs
- }),
- function() {
- console.log('Finished build of techs %s for levels %s. Result in %s/%s.* files.',
- techs.join(', '), levels.join(', '), outputDir, outputName);
- }
-);
-
-// use outputLevel option
-var level = B.createLevel('path/to/level'),
- block = 'page';
-Q.when(
- BEM.build({
- outputLevel: level,
- block: block
- }),
- function() {
- console.log('Finished build of techs %s for levels %s. Result in %s.* files.',
- techs.join(', '), levels.join(', '), level.getRelByObj({ block: block }));
- }
-);
-```
-
-#### BEM.decl
-
-Commands to work with declarations.
-
-##### BEM.decl.merge()
-
-Merging two or more declarations into one.
-
-###### Options
-
- * **String** `output` A file for output result. By default output is in STDOUT
- * **Array** `declaration` List of filenames for declarations (required)
-
-##### BEM.decl.subtract()
-
-Subtracting the next declarations from the first one.
-
-###### Options
-
- * **String** `output` A file for output result. By default output is in STDOUT
- * **Array** `declaration` List of filenames for declarations (required)
-
-## Contribute to development
-
-### Executing autotests
-
-To verify that your changes do not break existing functionality we recommend to run autotests and check that all of them pass. You can do that by executing the following command in the root of the project:
-
- mocha
-
-### Running autotests with test coverage report
-
-You can check the level of the code coverage by tests using the command:
-
- make test-cover
-
-Then open coverage.html file in a browser. Code lines which have not been executed during the tests run will be marked red.
-
-<!-- Yandex.Metrika counter -->
-<img src="//mc.yandex.ru/watch/12831025" style="position:absolute; left:-9999px;" alt="" />
-<!-- /Yandex.Metrika counter -->
+* [Installation](http://bem.info/tools/bem/installation/)
+* [Commands](http://bem.info/tools/bem/commands/)
+* [Levels](http://bem.info/tools/bem/levels/)
+* [Build customization](http://bem.info/tools/bem/customization/)
+* [Tech modules](http://bem.info/tools/bem/tech-modules/)
+* [API](http://bem.info/tools/bem/api/)
+* [How to contribute](http://bem.info/tools/bem/contribute/)
1,291 README.ru.md
View
@@ -1,1271 +1,20 @@
-# БЭМ-инструменты
-Работа с файлами, написанными по [БЭМ-методу](http://bem.github.com/bem-method/pages/beginning/beginning.en.html).
-
-## Установка
-Вам потребуется [NodeJS 0.6+](http://nodejs.org/) или выше и [npm 1.x](http://npmjs.org/).
-После этого достаточно `npm -g install bem`.
-
- * Установить [nodejs](http://nodejs.org)
-
- https://github.com/joyent/node/wiki/Installation
-
- * Установить [npm](http://npmjs.org)
-
- curl http://npmjs.org/install.sh | sudo sh
-
- * После установки сконфигурируйте `NODE_PATH`:
-
- echo 'export NODE_PATH="'$(npm root -g)'"'>> ~/.bashrc && . ~/.bashrc
-
- или
-
- echo 'export NODE_PATH="'$(npm root -g)'"'>> ~/.zshrc && . ~/.zshrc
-
- * Установить [bem-tools](https://github.com/bem/bem-tools)
-
- sudo npm -g install bem
-
- * Для установки самой последней версии [bem-tools](https://github.com/bem/bem-tools) воспользуйтесь командой
-
- sudo npm -g install bem@unstable
-
-### bem-bl
-
-Если вы планируете использовать `bem` вместе с библиотекой блоков
-[bem-bl](https://github.com/bem/bem-bl), установите так же
-[xjst](https://github.com/veged/xjst) и [ometajs](https://github.com/veged/ometa-js).
-
- sudo npm -g install xjst ometajs
-
-## Использование
-Всю информацию о параметрах использования можно получить с помощью `bem --help`.
-Для информации о конкретной команде и подкомманде: `bem COMMAND --help` и `bem COMMAND SUBCOMMAND --help`.
-
-### Shell completion
-
-#### bash
-
-Если вы используете `bash` и у вас установлен пакет `bash-completion`, выполните следующую команду и перелогиньтесь:
-
- bem completion > /path/to/etc/bash_completion.d/bem
-
-Если вы не используете `bash-completion`, можете добавить вывод `bem completion` себе в `.bashrc`, а затем перезагрузить:
-
- bem completion >> ~/.bashrc
- source ~/.bashrc
-
-#### zsh
-
-Если вы используете `zsh`, можете добавить вывод `bem completion` себе в `.zshrc` и перезагрузите его:
-
- bem completion >> ~/.zshrc
- source ~/.zshrc
-
-### Консольные команды
-#### bem create
-
-С помощью `bem create` можно создавать сущности:
-
- * уровни переопределения
- * блоки
- * элементы
- * модификаторы
-
-##### Уровень переопределения
-
-Уровень переопределения -- это директория, в которой хранятся реализации
-блоков и служебная директория `.bem`.
-
`.bem` хранятся настройки этого уровня переопределения:
-
- * соглашения об именовании
- * ссылки на модули технологий
-
-Пример настройки ссылок на модули технологий (уровень `blocks-desktop`
-библиотеки блоков `bem-bl`):
-
- https://github.com/bem/bem-bl/blob/master/blocks-desktop/.bem/level.js
-
-###### Создание уровня переопределения blocks в текущей директории:
-
- bem create level blocks
-
-###### Создание уровня для страниц
-
-В терминах `bem-tools` страницы тоже блоки, директория со страницами
-является уровнем переопределения. Создать такую директорию можно так:
-
- bem create level pages
-
-###### Создание уровня переопределения на основе существующего
-
-Команда `bem create level` позволяет использовать существующий уровень переопределения
-в качестве прототипа для создаваемого уровня.
-
- bem create level --level bem-bl/blocks-desktop blocks
-
-##### Блок
-
-Блок -- это набор файлов -- реализаций блока в различных технологиях.
-
-###### Создание блока
-
- bem create block b-my-block
-
-По умолчанию блок создаётся с набором файлов для всех технологий по-умолчанию (`bemhtml`, `css`, `js`).
-
-###### Создание блока в определённой технологии
-
-Использование флагов -t (-T) позволяет создавать файлы блока нужных технологий:
-
- bem create block -t deps.js b-my-block
- // Создаст реализацию в технологии deps.js помимо дефолтных
-
- bem create block -T css b-my-block
- // Создаст только технологию CSS для блока
-
- bem create block -T bem-bl/blocks-desktop/i-bem/bem/techs/bemhtml.js b-my-block
- // Флаг -T удобно использовать, если нужно добавить новую технологию для уже существующего блока
-
-В качестве значения флага может быть указано название технологии (например, `css`)
-или путь до модуля технологии.
-
-Названия технологий могут быть указаны в файле `.bem/level.js` уровня переопределения.
-Например, https://github.com/bem/bem-bl/blob/master/blocks-desktop/.bem/level.js
-
-Примеры реализации модулей технологий можно увидеть в репозитории:
-
- https://github.com/bem/bem-tools/tree/master/lib/techs
-
-###### Создание элемента блока
-
-Создание элемента `elem` для блока `b-my-block`
-
- bem create elem -b b-my-block elem
-
-###### Создание модификатора блока или элемента
-
-Создание модификатора `mod` для блока `b-my-block`
-
- bem create mod -b b-my-block mod
-
-Создание модификатора `mod` в значении `val` для блока `b-my-block`
-
- bem create mod -b b-my-block mod -v val
-
-Создание модификатора `mod` для элемента `elem` блока `b-my-block`
-
- bem create mod -b b-my-block -e elem mod
-
-Создание модификатора `mod` в значении `val` для элемента `elem` блока `b-my-block`
-
- bem create mod -b b-my-block -e elem mod -v val
-
-###### Создание произвольной БЭМ сущности используя только команду `bem create`
-
-При момощи команды `bem create` можно создавать произвольные БЭМ сущности или даже наборы сущностей.
-
-Создание блоков `b-block1` и `b-block2`
-
- bem create -b b-block1 -b b-block2
-
-Создание элементов `elem1` и `elem2` для блока `b-block`
-
- bem create -b b-block -e elem1 -e elem2
-
-Создание модификатора `mod` блока `b-block`
-
- bem create -b b-block -m mod
-
-Создание модификатор `mod` блока `b-block` в значениях `val1` и `val2`
-
- bem create -b b-block -m mod -v val1 -v val2
-
-Создание модификатора `mod` элемента `elem` блока `b-block`
-
- bem create -b b-block -e elem -m mod
-
-Создание модификатора `mod` в значениях `val1` и `val2` для элемента `elem` блока `b-block`
-
- bem create -b b-block -e elem -m mod -v val1 -v val2
-
-#### bem build
-
-С помощью команды `bem build` можно собирать файлы страниц для различных технологий,
-основываясь на декларации страницы.
-
-##### Создание файла bemdecl.js по bemjson-декларации страницы
-
- bem build \
- -l bem-bl/blocks-common -l bem-bl/blocks-desktop \
- -l blocks -l pages/index/blocks \
- -d pages/index/index.bemjson.js -t bemdecl.js \
- -o pages/index -n index
-
-Значением флага -t может быть как название технологии, так и полный путь до модуля
-технологии. В этом модуле указано, как именно по декларации собирается конечный файл.
-
-Например, модуль для `deps.js`: https://github.com/bem/bem-tools/blob/master/lib/techs/deps.js.js
-
-##### Создание файла deps.js по bemdecl.js
-
- bem build \
- -l bem-bl/blocks-common -l bem-bl/blocks-desktop \
- -l blocks -l pages/index/blocks \
- -d pages/index/index.bemdecl.js -t deps.js \
- -o pages/index -n index
-
-###### Создание js и css файлов страниц по deps.js
-
- bem build \
- -l bem-bl/blocks-common -l bem-bl/blocks-desktop \
- -l blocks -l pages/index/blocks \
- -d pages/index/index.deps.js -t css \
- -o pages/index -n index
-
- bem build \
- -l bem-bl/blocks-common -l bem-bl/blocks-desktop \
- -l blocks -l pages/index/blocks \
- -d pages/index/index.deps.js -t js \
- -o pages/index -n index
-
-###### Создание сборки с шаблонами bemhtml.js по файлу deps.js
-
- bem build \
- -l bem-bl/blocks-common -l bem-bl/blocks-desktop \
- -l blocks -l pages/index/blocks \
- -d pages/index/index.bemhtml.js \
- -t bem-bl/blocks-desktop/i-bem/bem/techs/bemhtml.js \
- -o pages/index -n index
-
-Пример построения страниц при помощи `bem build` есть в демонстрационном
-проекте на блоках `bem-bl`: https://github.com/toivonen/bem-bl-test/blob/master/GNUmakefile
-
-#### bem decl
-
-`bem decl` позволяет работать с файлами деклараций, а именно:
-
- * объединять несколько деклараций в одну
- * «вычитать» декларации, то есть получать разницу между ними
-
-Для всех подкоманд `bem decl` в качестве входных деклараций (ключ `-d`) могут выступать
-файлы как в формате `bemdecl.json`, так и файлы в формате `deps.js`.
-
-На выходе (ключ `-o`) всегда получается файл в формате `deps.js`.
-
-##### bem decl merge
-
-`bem decl merge` объединяет несколько деклараций в одну. Она бывает полезна в ситуациях,
-когда, например, вам нужно собрать общую сборку для нескольких страниц.
-
-###### Создание декларации для всех страниц
-
- bem decl merge \
- -d pages/index/index.deps.js \
- -d pages/about/about.deps.js \
- -d pages/search/search.deps.js \
- -o pages/common/common.deps.js
-
-##### bem decl subtract
-
-`bem decl subtract` «вычитает» из первой указанной декларации все остальные. Она полезна
-в ситуациях, когда, например, вам нужно сделать бандл, которые будет догружатся на страницу
-по требованию.
-
-###### Создание декларации для подгружаемого по требованию «тяжёлого» блока
-
- bem decl subtract \
- -d bundles/heavy-block/heavy-block.deps.js \
- -d pages/common/common.deps.js \
- -o bundles/heavy-block/heavy-block.bundle.js
-
-##### bem make
-В команде `make` реализована сборка БЭМ проектов. Узнать больше о системах сборки можно из доклада Сергея Белова http://clubs.ya.ru/yasubbotnik/replies.xml?item_no=406.
-
-`bem make` собирает проект
-
- * подключает библиотеки блоков
- * выполняет сборку в уровнях переопределения
- * выполняет сборку бандлов
- * собирает шаблоны (`bemhtml`)
- * собирает `html` из `bemjson.js`
- * собирает статические файлы (`js`, `css`)
- * раскрывает `@import` в `css` файлах (`borschik`)
- * раскрывает `borschik:link:include` в `js` файлах (`borschik`)
- * сжимает `css` файлы при помощи `csso`
- * сжимает `js` файлы при помощи `uglifyjs`
-
-##### bem server
-
-`bem server` веб-сервер разработчика, который делает доступными по http протоколу файлы, собранные на лету bem make. bem server может быть вам полезен для разработки статических страниц по bem методу. Вы просто вносите изменения в файлы проекта, обновляете страницу в браузере и видите новый результат — файлы, которые затронули ваши изменения, будут автоматически пересобраны. Если же в вашем проекте нет статических страниц, вы можете настроить бэкенд и окружение таким образом, чтобы он обращался к bem server за файлами стилей и скриптов. bem server позволяет общаться с ним через привычный TCP socket или через UNIX domain socket.
-
-По умолчанию корневым каталогом веб-сервера считается текущая директория. Вы можете указать нужный каталог с помощью
-ключа --project (-r). Таким образом, если в корне есть файл pages/about/main.css, то он будет доступен из браузера
-по адресу http://localhost:8080/pages/about/main.css.
-
-TCP порт по умолчанию, который слушает сервер - 8080. Вы можете указать другой порт, используя ключ --port (-p).
-
-Когда запрашиваемый URL соответствует директории, сервер проверит, возможно ли собрать для запрошенной директории файл
-`index.html`. Если это так, то страница будет собрана и отдана браузеру. Иначе браузер получит листинг файлов в директории.
-
-#### Конфигурирование сборки
-
-В системе сборки предусмотрено некоторое поведение по умолчанию. С помощью файлов конфигурации можно как немного изменить
-его, так и кардинально переделать. Необходимым минимумом для работы bem make являются конфиги `.bem/level.js` на уровнях
-переопределения с функцией `getTechs()`, возвращающей массив технологий, задействованных на уровне. И функцией `getConfig()`:
-
-```js
-var extend = require('bem/lib/util').extend;
-
-exports.getTechs = function() {
- return {
- 'bemjson.js': '',
- 'js': 'js-i',
- 'bemhtml': '../../bem-bl/blocks-common/i-bem/bem/techs/bemhtml.js',
- 'priv.js': '../../.bem/techs/priv.js',
- 'html': '../../bem-bl/blocks-common/i-bem/bem/techs/html'
- };
-};
-
-exports.getConfig = function() {
-
- return extend({}, this.__base() || {}, {
-
- bundleBuildLevels: this.resolvePaths([
- '../../bem-bl/blocks-common',
- '../../bem-bl/blocks-desktop',
- '../../blocks'
- ])
-
- });
-
-};
-```
-
-`getTechs()` возвращает массив подключаемых технологий: ключ (например `'bemjson.js'`, `'js'`, `'bemhtml'`) указывает
-имя, под котором технологию можно будет использовать, значение (`''`, `'js-i'`, `'../../bem-bl/blocks-common/i-bem/bem/techs/bemhtml.js'`) -
-где взять сам файл технологии. В качестве этого значения может быть указан абсолютный или относительный путь к файлу,
-пустая строка или просто имя файла. В последнем случае подразумевается, что технология стандартная (входит в состав
-bem-tools) и ее поиск будет произведен в директории `[bem]/lib/techs`.
-
-Функция `getConfig()` возвращает объект со свойстовом `bundleBuildLevels`, содержащим массив подключаемых уровней блоков.
-
-Второй (опциональный) компонент конфигурации - это файл `.bem/make.js` в корне проекта. Основой сборки является граф
-узлов, каждый из которых отвечает за выполнение своей части всего процесса. В `make.js` можно изменять поведение узлов
-и построение дерева. Существует несколько типов стандартных узлов:
- * `Node` - базовый узел, от которого наследуются все остальные
- * `LibraryNode` - отвечает за подключение внешних библиотек
- * `LevelNode` - анализирует содержимое уровня переопределения и достраивает дерево для сборки этого уровня
- * `BundlesLevelNode` - доопределяет `LevelNode` для сборки уровней бандлов
- * `BundleNode` - достраивает дерево для сборки бандла
- * `MergedBundleNode` - отвечает за сборку merged бандла (называемого так же common)
- * `BorschikNode` - прогоняет файлы через утилиту `borschik`, которая разворачивает инклюды
- * `Arch` - строит исходное дерево, состоящее главным образом из узлов `LibraryNode`, `BundlesLevelNode`, `LevelNode`
-
-Чтобы сконфигурировать сборку своего проекта, необходимо переопределить поведение тех или иных узлов. Это делается в
-конфигурационном файле `.bem/make.js` в корне проекта с помощью хелпера `MAKE.decl()`. Первым аргументом ему передается
-название узла, который будет переопределен. Вторым - объект с переопределяющими методами.
-
-```js
-MAKE.decl('BundleNode', {
-
-});
-```
-
-У узлов есть несколько основных методов, отвечающих за процесс сборки:
- * `isValid()` - проверяет, есть ли необходимость в запуске сборки данного узла. Если артефакты сборки узла уже были получены ранее и узлы, от которых зависит данный, не пересобирались в текущей сборке - то будет считаться, что узел не нужно пересобирать. Иными словами, если после первой сборки вы поменяли один файл, то при последующей сборке будут пересобраны только зависящие от этого файла узлы. Для остальных isValid вернет true и они не будут пересобираться.
- * `make()` - осуществляет непосредственно сборку узла.
- * `run()` - точка входа в узел. В реализации по умолчанию выполняет метод `isValid()` и в случае если он возвращает `false`, запускает `make()`.
- * `clean()` - удаляет артефакты сборки данного узла.
-
-##### Примеры конфигурационных файлов для типовых задач
-
-###### Сборка статического html, css, js, bemhtml шаблонов из bemjson для уровня страниц pages. Подключаются уровень переопределения блоков blocks, а так же blocks-common и blocks-desktop из bem-bl
-
-`pages/.bem/level.js`
-```js
-var extend = require('bem/lib/util').extend;
-
-exports.getTechs = function() {
-
- return {
- 'bemjson.js': '',
- 'bemdecl.js': 'bemdecl.js',
- 'deps.js': 'deps.js',
- 'js': 'js-i',
- 'css': 'css',
- 'bemhtml': '../../bem-bl/blocks-common/i-bem/bem/techs/bemhtml.js',
- 'html': '../../bem-bl/blocks-common/i-bem/bem/techs/html.js'
- };
-
-};
-
-exports.getConfig = function() {
-
- return extend({}, this.__base() || {}, {
-
- bundleBuildLevels: this.resolvePaths([
- '../../bem-bl/blocks-common',
- '../../bem-bl/blocks-desktop',
- '../../blocks'
- ])
-
- });
-
-};
-```
-
-`.bem/make.js`
-```js
-MAKE.decl('Arch', {
-
- getLibraries: function() {
-
- return {
- 'bem-bl': {
- type: 'git',
- url: 'git://github.com/bem/bem-bl.git'
- }
- };
-
- }
-
-});
-
-MAKE.decl('BundleNode', {
-
- getTechs: function() {
-
- return [
- 'bemjson.js',
- 'bemdecl.js',
- 'deps.js',
- 'bemhtml',
- 'css',
- 'js',
- 'html'
- ];
- }
-
-});
-```
-
-
-###### Сборка css, js, bemhtml шаблонов из файлов декларации (bemdecl) для уровня страниц pages. Подключаются уровень переопределения блоков blocks, а также blocks-common и blocks-desktop из bem-bl
-
-`pages/.bem/level.js`
-```js
-var extend = require('bem/lib/util').extend;
-
-exports.getTechs = function() {
-
- return {
- 'bemdecl.js': 'bemdecl.js',
- 'deps.js': 'deps.js',
- 'js': 'js-i',
- 'css': 'css',
- 'bemhtml': '../../bem-bl/blocks-common/i-bem/bem/techs/bemhtml.js'
- };
-
-};
-
-exports.getConfig = function() {
-
- return extend({}, this.__base() || {}, {
-
- bundleBuildLevels: this.resolvePaths([
- '../../bem-bl/blocks-common',
- '../../bem-bl/blocks-desktop',
- '../../blocks'
- ])
-
- });
-
-};
-```
-
-`.bem/make.js`
-```js
-MAKE.decl('Arch', {
-
- getLibraries: function() {
-
- return {
- 'bem-bl': {
- type: 'git',
- url: 'git://github.com/bem/bem-bl.git'
- }
- };
-
- }
-
-});
-
-MAKE.decl('BundleNode', {
-
- getTechs: function() {
-
- return [
- 'bemdecl.js',
- 'deps.js',
- 'bemhtml',
- 'css',
- 'js'
- ];
- }
-
-});
-```
-
-###### Библиотеки блоков
-
-TODO: По умолчанию библиотеки блоков не подключаются. Чтобы подключить нужные библиотеки блоков, добавьте
`.bem/make.js` следующий код:
-
-```js
-MAKE.decl('Arch', {
- getLibraries: function() {
-
- return {
- 'bem-bl': {
- type: 'git',
- url: 'git://github.com/bem/bem-bl.git'
- }
- };
- }
-});
-```
-
-
-Здесь:
- * `MAKE.decl()` - метод-хелпер, который позволяет переопределять стандартные классы bem tools, тем самым меняя функциональность.
- * `'Arch'` - имя класса, который мы хотим переопределить. `Arch` отвечает за построение начального дерева сборки.
- * `getLibraries` - метод класса Arch, который возвращает ассоциативный массив подключаемых библиотек.
- * `'bem-bl'` — название библиотеки и директории, в которой она будет лежать. Допустимы имена вида 'mylibraries/bem-bl' -
-тогда чекаут библиотеки произойдет в директорию `[корень проекта]/mylibraries/bem-bl`.
- * `type` - указывает способ подключения. В примере используется значение `git`, означающее, что библиотеку нужно взять
-из git репозитория. Возможные значение: `'git'`, `'svn'`, `'symlink'`. `svn` работает аналогично `git`, но с `svn` репозиторием.
-`symlink` - создает символическую ссылку в собираемом проекте на директорию с контентом библиотеки на файловой системе.
-Путь к библиотеке указывается через свойство `relative`.
- * `url` - URL к svn/git репозиторию
-
-Или можно воспользоваться шоткатом:
-
-```js
-MAKE.decl('Arch', {
- libraries: {
- 'bem-bl': {
- type: 'git',
- url: 'git://github.com/bem/bem-bl.git'
- }
- }
-});
-```
-
-###### Уровни переопределения
-
-По умолчанию уровнями переопределения считаются все директории `blocks*` в корне проекта. Чтобы это изменить,
-добавьте в `.bem/make.js` следующий код:
-
-```js
-MAKE.decl('Arch', {
- blocksLevelsRegexp: /регулярное выражение/,
-});
-```
-
-Регулярное выражение используется для фильтрации директорий в корне проекта. Директории, которые попадают под выражение,
-будут считаться уровнями переопределения и для них будут созданы соответствующие узлы.
-
-Если изменения маски для выбора уровней не достаточно и нужна более сложная логика, нужно переопределить метод
-`createBlocksLevelsNodes()`:
-
-```js
-MAKE.decl('Arch', {
- createBlocksLevelsNodes: function(parent, children) {
- // Создаем экземпляр LevelNode
- var node1 = new LevelNode(...);
- // Добавляем созданный узел в дерево
- this.arch.setNode(node1, parent, children);
-
- var node2 = new LevelNode(...);
- this.arch.setNode(node2, parent, children);
-
- // Возвращаем массив из идентификаторов созданных узлов
- return [node1.getId(), node2.getId()];
- }
-});
-```
-
-###### Бандлы и страницы
-
-По умолчанию уровнями бандлов считаются все директории `pages*` и `bundles*` в корне проекта. Изменить это можно по
-аналогии с конфигурацией уровней переопределения.
-
-```js
-MAKE.decl('Arch', {
- bundlesLevelsRegexp: /регулярное выражение/,
-});
-```
-
-И для большего контроля:
-
-```js
-MAKE.decl('Arch', {
-
- getBundlesLevels: function() {
- return [
- 'pages-desktop',
- 'pages-touch',
- 'bundles/common'
- ];
- }
-
-});
-```
-
-
-Для каждого бандла по умолчанию собираются следующие конечные файлы:
-
- * `.bemhtml.js`
- * `.html`
- * `.css`
- * `.ie.css`
- * `.js`
- * `_*.css`
- * `_*.ie.css`
- * `_*.js`
-
-и промежуточные:
-
- * `.bemdecl.js`
- * `.deps.js`
- * `.deps.js.deps.js`
- * `.bemhtml.js.meta.js`
- * `.js.meta.js`
- * `.css.meta.js`
- * `.ie.css.meta.js`
-
-По умолчанию исходным файлом считается файл `.bemjson.js`. Если его нет на диске, исходным станет `.bemdecl.js`. Если его
-тоже нет - `.deps.js`. В случаях, когда нет `.bemjson.js` статический html собран не будет.
-
-Чтобы изменить перечень собираемых файлов, добавьте в `.bem/make.js` следующий код:
-
-```js
-MAKE.decl('BundleNode', {
-
- getTechs: function() {
- return [
- 'bemdecl.js',
- 'deps.js',
- 'bemhtml',
- 'css',
- 'js',
- 'priv.js'
- ];
- }
-});
-```
-
-Если вы хотите дополнить стандартный набор своими:
-
-```js
-MAKE.decl('BundleNode', {
-
- getTechs: function() {
- return this.__base().concat(['priv.js', 'pub.js']);
- }
-});
-```
-
-`this.__base()` вызывает базовый метод, который вернет нам массив технологий по умолчанию. С помощью `concat()` мы добавляем
-в него технологии `priv.js` и `pub.js` и возвращаем его.
-
-Рекомендуется возвращать список явно, т.е. переопределять `getTechs()` как в первом примере, чтобы избежать побочных
-эффектов, если вдруг поменяется список технологий по умолчанию.
-
-**ВАЖНО:** Технологии в массиве должны идти в порядке зависимости друг от друга. То есть технология B, зависящая от
-технологии A, должна быть в списке **ниже** A. Также в этом списке должны быть все технологии, в том числе исходный файл,
-например `bemjson.js`.
-
-###### Сборка merged (раньше так же назывался common) бандла
-Merged бандл — это бандл, который объединяет в себе декларации всех бандлов уровня. Соответственно по такой объединенной
-декларации собираются и объединенные конечные файлы. Например, css будет включать в себе все стили, используемые всеми бандлами.
-
-Merged бандл может быть полезен, например, если вы хотите использовать общие файлы статики (js, css) для нескольких
-страниц проекта. Или при использовании технологии priv.js держать шаблоны страниц в одном файле.
-
-Следующий код включит сборку merged бандла для всех уровней:
-
-```js
-MAKE.decl('BundlesLevelNode', {
- buildMergedBundle: function() {
- return true;
- }
-});
-```
-
-Если merged бандл нужен только в выборочных уровнях, необходимо добавить условие (будем собирать merged только для уровня
-`pages-desktop`):
-
-```js
-var PATH = require('path');
-
-MAKE.decl('BundlesLevelNode', {
- buildMergedBundle: function() {
- if (this.getLevelPath() === 'pages-desktop') return true;
-
- return false;
- }
-});
-```
-
-Метод `getLevelPath()` (есть у узлов-уровней и узлов-бандлов) возвращает относительный путь данного уровня или путь
-уровня данного бандла. С его помощью мы можем определить, нужно производить какие-либо действия для уровня или нет.
-
-Изменить название merged банлда можно следующим образом:
-```js
-MAKE.decl('BundlesLevelNode', {
-
- mergedBundleName: function() {
- return 'mymergedbundle';
- }
-
-});
-```
-
-##### Production и Development сборка статики
-Переключая значение переменной окружения `YENV`, можно собирать production или development версии статических файлов.
-В production режиме файлы прогоняются через утилиту borschik, которая создаст файл с префиксом `_`, в который будет
-включено содержимое всех подключаемых файлов. Например, если собирается `index.css`, в котором подключаются `blocks/block1.css`
`blocks/block2.css`, то `borschik` создаст `_index.css` с контентом `block1.css` и `block2.css`. Кроме этого, `css`
-файлы оптимизируются утилитой `csso`, `js` файлы минимизируются через `uglifyjs`. В development режиме файлы прогоняются
-только через `borschik`, оптимизация не производится.
-
-Режимом по умолчанию является development. Установка `YENV` в значение production переключит его соответственно.
-
-Значения переменных окружения можно выставлять в `.bem/make.js`, например
-
-```js
-process.env.YENV = 'production';
-```
-
-### Файлы конфигурации
-
-#### Уровень переопределения (`.bem/level.js`)
-
-На уровне переопределения должен быть файл конфигурации `.bem/level.js`, который содержит в себе мета-информацию
-об устройстве уровня, а именно:
-
-- правила маппинга БЭМ-сущностей в файловую систему
-- технологии, определённые для уровня
-- мета-информация для системы сборки
-
-При создании уровня командой `bem create level` файл `.bem/level.js` создаётся пустым, что означает, что уровень —
-«стандартный». Поведение стандартного уровня описано в классе `Level` в файле
-[lib/level.js](https://github.com/bem/bem-tools/blob/master/lib/level.js).
-
-Перекрыть поведение уроня просто. Файл `.bem/level.js` (как и практически любой файл конфигурации) является CommonJS
-модулем. `bem-tools` при обнаружении такого файла создаёт класс-наследник стандартного класса `Level`, используя экспорт
-этого модуля в качестве расширения класса (внутри используется модуль [inherit](https://github.com/dfilatov/node-inherit)).
-
-В примере ниже перекрывается метод `getTechs()`.
-
-```js
-exports.getTechs = function() {
-
- return {
- 'bemjson.js': ''
- 'css': 'path/to/my/css-tech-module.js'
- }
-
-};
-```
-
-##### Наследование уровней
-
-Чтобы не копировать код из одного конфига уровней в другой, вы можете выносить общие части в самостоятельные модули
-и наследоваться от них. Таким образом можно выстаивать целые иерархии уровней.
-
-Для задания базового уровня нужно экспортировать из модуля свойство `baseLevelPath`, например
-
-```js
-exports.baseLevelPath = require.resolve('path/to/base/level.js');
-```
-
-Уровни-наследники также можно создавать командой
-
- bem create level <your-level-name> --level path/to/base/level.js
-
-##### Правила маппинга БЭМ-сущностей в файловую систему
-
-По умолчанию на уровне переопределения используется следующая схема маппинга (на примере технологии `css`):
-
-```
-level/
- block/
- __elem/
- _mod/
- block__elem_mod_val.css
- block__elem.css
- _mod/
- block_mod_val.css
- block.css
-```
-
-Если вас не устраивает эта схема, вы можете задать свою. Для этого нужно перекрыть соответствующие `match*()` и `get*()`
-методы в файле `.bem/level.js`.
-
-##### Технологии, определённые для уровня
-
-Для уровня переопределения можно задекларировать список используемых технологий. Для этого нужно экспортировать
-функцию `getTechs()`, которая должна вернуть объект, в ключах которого лежат имена технологий, а в значениях:
-
-- абсолютный путь до технологии — будет использоваться модуль, находящийся по этому пути;
-- короткое имя технологии — будет использоваться реализация технологии с указанным именем из `bem-tools`;
-- пустая строка — будет использоваться реализация технологии по умолчанию.
-
-По умолчанию на уровне переопределения явно не определена ни одна из технологий. Если попытаться внутри таких уровней
-использовать техологии по короткому имени, например `css`, `js` и другие, то будут использованы модули технологии
-из состава `bem-tools`, если они существуют. Полный список таких технологий смотрите в [lib/techs](https://github.com/bem/bem-tools/tree/master/lib/techs).
-
-Если попытаться использовать технологии, которые явно не задекларированы, и которых при этом не существуют
`bem-tools` — будет использоваться реализация технологии по умолчанию
-(см. [lib/tech.js](https://github.com/bem/bem-tools/blob/master/lib/tech.js)).
-
-Технологии, задекларированные на уровне используются:
-
-- командой `bem create`
-- командой `bem build`
-- для интроспекции по файловой системе (см. метод `getLevelByIntrospection()` класса `Level`)
-- в процессе сборки командами `bem make` и `bem build`
-
-Мы рекомендуем явно декларировать все используемые технологии.
-
-##### Мета-информация для системы сборки
-
-Во время сборки проекта командами `bem make` и `bem server` для выполнения команды `bem build` нужно знание о том,
-из каких уровней переопределения нужно собирать тот или иной бандл. Это знания необходимо отобразить в свойсте
-`bundleBuildLevels` объекта, возвращаемого функцией `getConfig()`.
-
-```js
-exports.getConfig = function() {
-
- return extend({}, this.__base() || {}, {
-
- bundleBuildLevels: this.resolvePaths([
- // your levels here
- ])
-
- });
-
-};
-```
-
-### Модули технологий
-
-#### API
-
-Смотрите документацию в исходном файле [lib/tech.js](https://github.com/bem/bem-tools/blob/master/lib/tech.js).
-
-#### Создание модуля технологии
-
-Существует несколько способов написания модулей технологии.
-
-Во всех описанных ниже способах из методов можно обратиться к объекту технологии через `this`,
-а через `this.__base(...)` можно вызвать метод одного из базовых классов. К классу технологии
-можно обратиться через `this.__class`. Всё это является следствием использование модуля
-[inherit](https://github.com/dfilatov/node-inherit) для органиазации наследования.
-
-##### Очень простой способ
-
-Способ заключается в том, что вы создаёте обычный CommonJS модуль, из
-которого экспортируете несколько функций, которые перекроют методы базового
-класса `Tech` из модуля [lib/tech.js](https://github.com/bem/bem-tools/blob/master/lib/tech.js).
-
-```js
-exports.getCreateResult = function(...) {
- // ваш код
-};
-```
-
-Вы так же можете сгруппироать все методы в объекте `techMixin`. Это рекомендованный способ.
-
-```js
-exports.techMixin = {
-
- getCreateResult: function(...) {
- // ваш код
- }
-
-};
-```
-
-##### Простой способ
-
-В простом способе к экспортируемым функциям добавляется переменная `baseTechPath`, в которой
-содержится абсолютный путь до расширяемого модуля технологии.
-
-```js
-var BEM = require('bem');
-
-exports.baseTechPath = BEM.require.resolve('./techs/css');
-```
-
-Так же вы можете организовать контекстное наследование, использую переменную `baseTechName`.
-В этом случае базовый класс будет выбран в зависимости от уровня переопределения, на котором
-будет использован модуль технологии.
-
-```js
-exports.baseTechName = 'css';
-```
-
-В этом примере новая технология будет расширять технологию `css`, заданную на уровне переопределения
-в файле `.bem/level.js`.
-
-##### Для продвинутых
-
-Если вам нужен полный контроль, вы можете создать модуль, экспортирующий готовый класс технологии `Tech`.
-
-```js
-var INHERIT = require('inherit'),
- BaseTech = require('bem/lib/tech').Tech;
-
-exports.Tech = INHERIT(BaseTech, {
-
- create: function(prefix, vars, force) {
- // do some creation work
- },
-
- build: function(prefixes, outputDir, outputName) {
- // organize own build process
- }
-
-});
-```
-
-Если в качестве базовой технологии вы хотите использовать одну из существующих технологий,
-написанных в простом стиле, воспользуйтесь функцией `getTechClass()` для получения класса
-этой технологии. Мы рекомендуем всегда использовать `getTechClass()`, чтобы не зависеть
-от реализации базовой технологии.
-
-```js
-var INHERIT = require('inherit'),
- BEM = require('bem'),
- BaseTech = BEM.getTechClass(require.resolve('path/to/tech/module'));
-
-exports.Tech = INHERIT(BaseTech, {
-
- // ваш код
-
-});
-```
-
-##### Примеры модулей технологий
-
- * [bem-tools/lib/techs/](https://github.com/bem/bem-tools/tree/nodejs/lib/techs)
- * [bem-bl/blocks-common/i-bem/bem/techs/](https://github.com/bem/bem-bl/tree/master/blocks-common/i-bem/bem/techs)
-
-### Использование через API
-
-В версии 0.2.0 появилась возможность использовать команды `bem-tools` через API.
-
-Модуль `bem` экспортирует объект основной команды, у которого есть свойство `api`.
-Использовать его можно так:
-
-```js
-var Q = require('q'),
- BEM = require('bem').api,
-
- techs = ['css', 'js'],
- blocks = ['b-block1', 'b-block2'];
-
-Q.when(BEM.create.block({ forceTech: techs }, { names: blocks }), function() {
- console.log('Create blocks: %s', blocks.join(', '));
-});
-```
-
-Как видно из примера, можно обращаться ко всем командам `bem-tools`, в том числе вложенным.
-
-Команды принимают два аргумента:
-
- * **Object** `opts` опции команды
- * **Object** `args` аргументы команды
-
-Возвращают объект типа `Q.promise`.
-
-#### BEM.create
-
-Команды для создания БЭМ-сущностей.
-
-##### BEM.create.level()
-
-Создание уровня переопределения.
-
-###### Опции
-
- * **String** `outputDir` директория для записи результата, по умолчанию текущая
- * **String** `level` «прототип» уровня переопределения
- * **Boolean** `force` принудительно создать уровень, даже если он существует
-
-###### Аргументы
-
- * **Array** `names` имена создаваемых уровней переопределения
-
-###### Пример использования
-
-```js
-var PATH = require('path'),
- Q = require('q'),
- BEM = require('bem').api,
-
- outputDir = PATH.join(__dirname, 'levels'),
- levels = ['blocks-common', 'blocks-desktop'];
-
-Q.when(BEM.create.level({ outputDir: outputDir }, { names: levels }), function() {
- console.log('Create levels %s at %s', levels.join(', '), outputDir);
-});
-```
-
-##### BEM.create()
-
-Создание БЭМ сущностей: блоков, элементов, модификаторов или их значений.
-
-###### Опции
-
- * **String** `level` директория уровня переопределения, по умолчанию текущая
- * **Array** `block` имя блока (обязательный параметр)
- * **Array** `elem` имя элемента
- * **Array** `mod` имя модификатора
- * **Array** `val` значение модификатора
- * **Array** `addTech` добавить перечисленные технологии к технологиям для уровня по умолчанию
- * **Array** `forceTech` использовать только указанные технологии
- * **Array** `noTech` исключить указанные технологии из использования
- * **Boolean** `force` принудительно создавать файлы модификатора
-
-###### Пример использования
-
-```js
-var Q = require('q'),
- BEM = require('bem').api,
-
- forceTechs = ['css'],
- block = 'b-header',
- elem = 'logo',
- mods = ['lang'],
- vals = ['ru', 'en'];
-
-Q.when(BEM.create({ forceTechs: forceTechs, block: block, mod: mods, val: vals }), function() {
- console.log('Create mod %s of block %s with vals %s', mods.join(', '), block, vals.join(', '));
-});
-
-Q.when(BEM.create({ forceTechs: forceTechs, block: block, elem: elem, mod: mods, val: vals }), function() {
- console.log('Create mod %s of elem %s of block %s with vals %s', mods.join(', '), elem, block, vals.join(', '));
-});
-```
-
-##### BEM.create.block()
-
-Создание блока.
-
-###### Опции
-
- * **String** `level` директория уровня переопределения, по умолчанию текущая
- * **Array** `addTech` добавить перечисленные технологии к технологиям для уровня по умолчанию
- * **Array** `forceTech` использовать только указанные технологии
- * **Array** `noTech` исключить указанные технологии из использования
- * **Boolean** `force` принудительно создавать файлы блока
-
-###### Аргументы
-
- * **Array** `names` имена создаваемых блоков
-
-###### Пример использования
-
-```js
-var Q = require('q'),
- BEM = require('bem').api,
-
- addTechs = ['bemhtml'],
- blocks = ['b-header'];
-
-Q.when(BEM.create.block({ addTech: addTechs }, { names: blocks }), function() {
- console.log('Create blocks: %s', blocks.join(', '));
-});
-```
-
-##### BEM.create.elem()
-
-Создание элемента.
-
-###### Опции
-
- * **String** `level` директория уровня переопределения, по умолчанию текущая
- * **String** `blockName` имя блока (обязательный параметр)
- * **Array** `addTech` добавить перечисленные технологии к технологиям для уровня по умолчанию
- * **Array** `forceTech` использовать только указанные технологии
- * **Array** `noTech` исключить указанные технологии из использования
- * **Boolean** `force` принудительно создавать файлы элемента
-
-###### Аргументы
-
- * **Array** `names` имена создаваемых элементов
-
-###### Пример использования
-
-```js
-var Q = require('q'),
- BEM = require('bem').api,
-
- addTechs = ['bemhtml', 'title.txt'],
- block = 'b-header',
- elems = ['logo'];
-
-Q.when(BEM.create.elem({ addTech: addTechs, blockName: block }, { names: elems }), function() {
- console.log('Create elems %s of block %s', elems.join(', '), block);
-});
-```
-
-##### BEM.create.mod()
-
-Создание модификатора блока или модификатора элемента.
-
-###### Опции
-
- * **String** `level` директория уровня переопределения, по умолчанию текущая
- * **String** `blockName` имя блока (обязательный параметр)
- * **String** `elemName` имя элемента
- * **Array** `modVal` значения модификатора
- * **Array** `addTech` добавить перечисленные технологии к технологиям для уровня по умолчанию
- * **Array** `forceTech` использовать только указанные технологии
- * **Array** `noTech` исключить указанные технологии из использования
- * **Boolean** `force` принудительно создавать файлы модификатора
-
-###### Аргументы
-
- * **Array** `names` имена создаваемых модификаторов
-
-###### Пример использования
-
-```js
-var Q = require('q'),
- BEM = require('bem').api,
-
- forceTechs = ['css'],
- block = 'b-header',
- elem = 'logo',
- mods = ['lang'],
- vals = ['ru', 'en'];
-
-Q.when(BEM.create.mod({ forceTechs: forceTechs, blockName: block, modVal: vals }, { names: mods }), function() {
- console.log('Create mod %s of block %s with vals %s', elems.join(', '), block, vals.join(', '));
-});
-
-Q.when(BEM.create.mod({ forceTechs: forceTechs, blockName: block, elemName: elem, modVal: vals }, { names: elems }), function() {
- console.log('Create mod %s of elem %s of block %s with vals %s', elems.join(', '), elem, block, vals.join(', '));
-});
-```
-
-#### BEM.build()
-
-Сборка файлов.
-
-###### Опции
-
- * **String** `outputDir` директория для записи результата, по умолчанию текущая
- * **String** `outputName` имя (префикс имени файла) для записи результата
- * **Level** `outputLevel` объект уровня переопределения, на котором нужно создать файлы БЭМ сущности
- * **String** `block` название блока
- * **String** `elem` название элемента
- * **String** `mod` название модификатора
- * **String** `val` значение модификатора
- * **String** `declaration` имя файла декларации использования (обязательный параметр)
- * **Array** `level` уровень переопределения
- * **Array** `tech` собирать файлы указанных технологий
-
-Вы можете использовать один из следующих вариантов для задания префикса для сохранения результата сборки:
-
- * `outputName` для задания полного пути-префикса
- * `outputDir` плюс `outputName` для задания пути для директории и префикса файлов (они будут склеены автоматически)
- * `outputLevel` плюс свойста, описывающие БЭМ сущность: `block`, `elem`, `mod` и `val` (путь-префикс будет построен
- автоматически на базе правил маппинга сущностей в файлы, заданных для уровня)
-
-###### Пример использования
-
-```js
-var Q = require('q'),
- B = require('bem'),
- BEM = B.api,
-
- decl = 'page.deps.js',
- outputDir = 'build',
- outputName = 'page',
- levels = ['blocks-common', 'blocks-desktop'],
- techs = ['css', 'js'];
-
-// используем outputDir и outputName
-Q.when(
- BEM.build({
- outputDir: outputDir,
- outputName: outputName,
- declaration: decl,
- level: levels,
- tech: techs
- }),
- function() {
- console.log('Finished build of techs %s for levels %s. Result in %s/%s.* files.',
- techs.join(', '), levels.join(', '), outputDir, outputName);
- }
-);
-
-// используем outputLevel
-var level = B.createLevel('path/to/level'),
- block = 'page';
-Q.when(
- BEM.build({
- outputLevel: level,
- block: block
- }),
- function() {
- console.log('Finished build of techs %s for levels %s. Result in %s.* files.',
- techs.join(', '), levels.join(', '), level.getRelByObj({ block: block }));
- }
-);
-```
-
-#### BEM.decl
-
-Команды для работы с декларациями использования.
-
-##### BEM.decl.merge()
-
-Объединение деклараций.
-
-###### Опции
-
- * **String** `output` файл для записи результата, по умолчанию STDOUT
- * **Array** `declaration` имя файла декларации использования (обязательный параметр)
-
-##### BEM.decl.subtract()
-
-Вычитание деклараций.
-
-###### Опции
-
- * **String** `output` файл для записи результата, по умолчанию STDOUT
- * **Array** `declaration` имя файла декларации использования (обязательный параметр)
-
-## Участие в разработке
-
-### Запуск автотестов
-
-Для того, чтобы проверить правильность внесённых изменений, рекомендуем выполнить следующую команду в корневой директории и убедиться, что все тесты выполнились без ошибок:
-
- mocha
-
-### Запуск автотестов с отчётом о покрытии кода автотестами
-
-Для того, чтобы узнать о степени покрытия исходного кода автотестами, следует выполнить следующую команду:
-
- make test-cover
-
-После этого открыть в браузере файл coverage.html. Красным цветом в отчёте будут помечены строки, которые ни разу не выполнялись во время работы тестов.
+# BEM tools
+BEM tools — это набор инструментов для работы с файлами по [БЭМ методологии](http://ru.bem.info/method/).
+
+Он позволяет:
+
+* создавать сущности;
+* собирать финальный рантайм;
+* работать с build-декларациями: объединять, вычитать и получать пересение;
+* собирать весь проект, используя команду bem make;
+* запускать разработческий сервер на деревом исходников проекта, используя bem server.
+
+See also:
+
+* [Установка](http://ru.bem.info/tools/bem/installation/)
+* [Команды](http://ru.bem.info/tools/bem/commands/)
+* [Уровни переопределения](http://ru.bem.info/tools/bem/levels/)
+* [Кастомизация сборки](http://ru.bem.info/tools/bem/customization/)
+* [Модули технологий](http://ru.bem.info/tools/bem/tech-modules/)
+* [API](http://ru.bem.info/tools/bem/api/)
+* [Участие в разработке](http://ru.bem.info/tools/bem/contribute/)
6 docs/index/index.en.md
View
@@ -13,7 +13,7 @@ See also:
* [Installation](installation/)
* [Commands](commands/)
* [Levels](levels/)
-* [Customization](customization/)
-* [Techs](tech-modules/)
+* [Build customization](customization/)
+* [Tech modules](tech-modules/)
* [API](api/)
-* [Contribute](contribute/)
+* [How to contribute](contribute/)
2  docs/index/index.ru.md
View
@@ -16,4 +16,4 @@ See also:
* [Кастомизация сборки](customization/)
* [Модули технологий](tech-modules/)
* [API](api/)
-* [Участие в разработке](contribute/)
+* [Участие в разработке](contribute/)
Please sign in to comment.
Something went wrong with that request. Please try again.