From 7745a1600fdcc0fc2e68adefdf74deaea6020c08 Mon Sep 17 00:00:00 2001 From: Evgeniy Gavryushin Date: Sun, 17 Aug 2014 14:29:20 +0400 Subject: [PATCH] Update documentation --- README.md | 68 ++++++++++++++++++++++++++++++++++++++++++++------ README.ru.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 123 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 9782b425..19b0cf0a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,12 @@ # generator-bem-stub [![Build Status](https://travis-ci.org/bem/generator-bem-stub.svg)](https://travis-ci.org/bem/generator-bem-stub) [![Coverage Status](https://img.shields.io/coveralls/bem/generator-bem-stub.svg)](https://coveralls.io/r/bem/generator-bem-stub?branch=master) [![Dependency Status](https://david-dm.org/bem/generator-bem-stub.svg)](https://david-dm.org/bem/generator-bem-stub) [![devDependency Status](https://david-dm.org/bem/generator-bem-stub/dev-status.svg)](https://david-dm.org/bem/generator-bem-stub#info=devDependencies) -A generator of BEM-projects for [Yeoman](http://yeoman.io). +A generator of [BEM](http://bem.info/) projects for [Yeoman](http://yeoman.io). + +## Introduction + +There are several assemblers for [BEM](http://bem.info/) projects — [bem-tools](http://bem.info/tools/bem/bem-tools/) and [ENB](https://github.com/enb-make/enb). What does any developer do by starting a new [BEM](http://bem.info/) project? First and foremost, a developer creates a configuration file for an assembler which he is going to use. Unfortunately it is rather time-consuming and and prone to error process both for [bem-tools](http://bem.info/tools/bem/bem-tools/) and [ENB](https://github.com/enb-make/enb). + +In order to save time and decrease barrier to entry into the tools for assembly, we decided to create a generator of configuration files which allows a developer to configure the assembly without immersion into tools' **API**. This generator provides you the ability to get the base of [BEM](http://bem.info/) project in few minutes by answering the simple questions. ## Install @@ -16,19 +22,67 @@ Run: $ yo bem-stub ``` -## Installation of dependencies +### What does generator-bem-stub support? -```generator-bem-stub``` will install all dependencies after generation of the project. +* Assemblers: + * [bem-tools](http://bem.info/tools/bem/bem-tools/) + * [ENB](https://github.com/enb-make/enb) +* Libraries: + * [bem-core](http://bem.info/libs/bem-core/current/) + * [bem-components](http://bem.info/libs/bem-components/current/) + design and autoprefixer +* Platforms: + * desktop + * touch-pad + * touch-phone +* CSS preprocessors: + * [Stylus](https://github.com/LearnBoost/stylus) + * [Roole](https://github.com/curvedmark/roole) + * [Less](https://github.com/less/less.js) +* [Autoprefixer](https://github.com/postcss/autoprefixer) +* Technologies: + * [BEMJSON](http://bem.info/technology/bemjson/current/bemjson/) + * ie.css + * ie6.css + * ie7.css + * ie8.css + * ie9.css + * [BEMTREE](http://bem.info/technology/bemtree/current/bemtree/) + * node.js + * browser.js (only in [ENB](https://github.com/enb-make/enb)) + * browser.js+bemhtml (only in [bem-tools](http://bem.info/tools/bem/bem-tools/)) +* Template engines: + * [BEMHTML](http://bem.info/technology/bemhtml/current/intro/) + * [BH](https://github.com/enb-make/bh) (only in [ENB](https://github.com/enb-make/enb)) +* Building of HTML +* Minimization of separate files (only in [ENB](https://github.com/enb-make/enb)) -If you do not want to install dependencies, use the option ```--no-deps``` +### Installation of dependencies + +`generator-bem-stub` will install all dependencies and libraries after generation of the project. + +If you do not want to install dependencies and libraries, use the option `--skip-install`: ```bash -$ yo bem-stub --no-deps +$ yo bem-stub --skip-install ``` -## Versions +### Versions + +You can check in the file [app/templates/config.json](https://github.com/bem/generator-bem-stub/blob/master/app/templates/config.json#L2-L20) which versions of the dependencies and libraries `generator-bem-stub` uses. + +### Important to know + +Many questions in `generator-bem-stub` depend on the previous ones, for example: + +* If you have chosen library [bem-components](http://bem.info/libs/bem-components/current/), `generator-bem-stub` will choose [Autoprefixer](https://github.com/postcss/autoprefixer) CSS preprocessor [Stylus](https://github.com/LearnBoost/stylus) as default. + +* You can choose template engine [BH](https://github.com/enb-make/bh) only if you have chosen assembler [ENB](https://github.com/enb-make/enb). + +* If you have not chosen technology [BEMJSON](http://bem.info/technology/bemjson/current/bemjson/), bundles will be assembled from [BEMDECL](http://bem.info/technology/bemjson/current/bemjson/). + +* You can build HTML only if you have chosen technology [BEMJSON](http://bem.info/technology/bemjson/current/bemjson/) and template engine [BEMHTML](http://bem.info/technology/bemhtml/current/intro/) or [BH](https://github.com/enb-make/bh). -You can check in the file ```app/templates/config.json``` which versions of the libraries and dependencies ```generator-bem-stub``` uses or click [here](https://github.com/bem/generator-bem-stub/blob/master/app/templates/config.json#L2-L19). +* You will be able to choose which separate files to minimize only if you have chosen assembler [ENB](https://github.com/enb-make/enb) ([bem-tools](http://bem.info/tools/bem/bem-tools/) does not support configuration of minimization, all possible files are minimized by [borschik](http://bem.info/tools/optimizers/borschik/)). ## License diff --git a/README.ru.md b/README.ru.md index 07af2b58..a049b1ac 100644 --- a/README.ru.md +++ b/README.ru.md @@ -1,6 +1,12 @@ # generator-bem-stub [![Build Status](https://travis-ci.org/bem/generator-bem-stub.svg)](https://travis-ci.org/bem/generator-bem-stub) [![Coverage Status](https://img.shields.io/coveralls/bem/generator-bem-stub.svg)](https://coveralls.io/r/bem/generator-bem-stub?branch=master) [![Dependency Status](https://david-dm.org/bem/generator-bem-stub.svg)](https://david-dm.org/bem/generator-bem-stub) [![devDependency Status](https://david-dm.org/bem/generator-bem-stub/dev-status.svg)](https://david-dm.org/bem/generator-bem-stub#info=devDependencies) -Генератор БЭМ-проектов на [Yeoman](http://yeoman.io). +Генератор [БЭМ](http://ru.bem.info/)-проектов на [Yeoman](http://yeoman.io). + +## Введение + +Существует несколько сборщиков для [БЭМ](http://ru.bem.info/)-проектов — [bem-tools](http://ru.bem.info/tools/bem/bem-tools/) и [ENB](https://github.com/enb-make/enb). Что делает разработчик, начиная новый [БЭМ](http://ru.bem.info/)-проект? В первую очередь разработчик создает конфигурационный файл для сборщика, который он будет использовать. К сожалению, и для [bem-tools](http://ru.bem.info/tools/bem/bem-tools/), и для [ENB](https://github.com/enb-make/enb) — это довольно трудоемкий процесс, в ходе которого часто возникают ошибки. + +Для экономии времени и снижения порога вхождения в понимание инструментов для сборки, мы решили создать генератор конфигурационных файлов, который позволяет конфигурировать сборку без погружения в **API** инструментов. Этот генератор предоставляет вам возможность получить базу [БЭМ](http://ru.bem.info/)-проекта за считаные минуты, овтетив на простые вопросы. ## Установка @@ -16,20 +22,68 @@ $ npm install -g generator-bem-stub $ yo bem-stub ``` -## Установка зависимостей +### Что поддержиает generator-bem-stub? -```generator-bem-stub``` установит все зависимости после генерации проекта. +* Сборщики: + * [bem-tools](http://ru.bem.info/tools/bem/bem-tools/) + * [ENB](https://github.com/enb-make/enb) +* Библиотеки: + * [bem-core](http://ru.bem.info/libs/bem-core/current/) + * [bem-components](http://ru.bem.info/libs/bem-components/current/) + design and autoprefixer +* Платформы: + * desktop + * touch-pad + * touch-phone +* CSS-препроцессоры: + * [Stylus](https://github.com/LearnBoost/stylus) + * [Roole](https://github.com/curvedmark/roole) + * [Less](https://github.com/less/less.js) +* [Autoprefixer](https://github.com/postcss/autoprefixer) +* Технологии: + * [BEMJSON](http://ru.bem.info/technology/bemjson/current/bemjson/) + * ie.css + * ie6.css + * ie7.css + * ie8.css + * ie9.css + * [BEMTREE](http://ru.bem.info/technology/bemtree/current/bemtree/) + * node.js + * browser.js (доступна только в [ENB](https://github.com/enb-make/enb)) + * browser.js+bemhtml (доступна только в [bem-tools](http://ru.bem.info/tools/bem/bem-tools/)) +* Шаблонизаторы: + * [BEMHTML](http://ru.bem.info/technology/bemhtml/current/intro/) + * [BH](https://github.com/enb-make/bh) (доступен только в [ENB](https://github.com/enb-make/enb)) +* Сборка HTML +* Минимизиция отдельных файлов (доступна только в [ENB](https://github.com/enb-make/enb)) -Чтобы не устанавливать зависимости, используйте опцию ```--no-deps```: +### Установка зависимостей + +`generator-bem-stub` установит все зависимости и библиотеки после генерации проекта. + +Чтобы не устанавливать зависимости и библиотеки, используйте опцию `--skip-install`: ```bash -$ yo bem-stub --no-deps +$ yo bem-stub --skip-install ``` -## Версии +### Версии + +Вы можете посмотреть в файле [app/templates/config.json](https://github.com/bem/generator-bem-stub/blob/master/app/templates/config.json#L2-L20), какие версии зависимостей и библиотек использует `generator-bem-stub`. + +### Важно знать + +Многие вопросы в `generator-bem-stub` зависят друг от друга, например: + +* Если вы выбрали библиотеку [bem-components](http://ru.bem.info/libs/bem-components/current/), `generator-bem-stub` выберет [Autoprefixer](https://github.com/postcss/autoprefixer) и CSS-препроцессор [Stylus](https://github.com/LearnBoost/stylus) по умолчанию. + +* Возможность использования [BH](https://github.com/enb-make/bh)-шаблонизатора появляется только при выборе сборщика [ENB](https://github.com/enb-make/enb). + +* Бандлы будут собираться из [BEMDECL](http://ru.bem.info/technology/bemjson/current/bemjson/), если вы не выбрали технологию [BEMJSON](http://ru.bem.info/technology/bemjson/current/bemjson/). + +* Вы можете собирать HTML, только если выбрали технологию [BEMJSON](http://ru.bem.info/technology/bemjson/current/bemjson/) и шаблонизатор [BEMHTML](http://ru.bem.info/technology/bemhtml/current/intro/) или [BH](https://github.com/enb-make/bh). -Вы можете посмотреть в файле ```app/templates/config.json```, какие версии библиотек и зависимостей использует ```generator-bem-stub``` или перейдите по [ссылке](https://github.com/bem/generator-bem-stub/blob/master/app/templates/config.json#L2-L19). +* У вас будет возможность выбрать, какие конкретно файлы минимизировать, только если вы выбрали сборщик [ENB](https://github.com/enb-make/enb) ([bem-tools](http://ru.bem.info/tools/bem/bem-tools/) не представляет возможность конфигурировать минимизацию файлов, все возможные файлы минимизируются с помощью [borschik](http://ru.bem.info/tools/optimizers/borschik/)). ## Лицензия -[MIT License](http://en.wikipedia.org/wiki/MIT_License) +[Лицензия MIT](https://ru.wikipedia.org/wiki/Лицензия_MIT)