English version becomes primary

Author: eugeny.horoshilov

README.md

@@ -1,39 +1,40 @@
 # CSS-o-Gram (CSSG)
-> аккуратно, наглядно, быстро - как [SSG](http://en.wikipedia.org/wiki/Steyr_SSG_69), только мирно
+> rapid, intuitive, neat - like [SSG](http://en.wikipedia.org/wiki/Steyr_SSG_69), but peaceful
 
-## Общие сведения
+## Overview
 
-CSSG - это "диаграмма CSS", по своей сути - комментарий в CSS файле, описывающий структуру сущности, к которой применяются стили. Сущность может быть элементом, блоком или проектом, в зависимости от используемой (или _не_ используемой) методологии.
+CSSG stands for "CSS Diagram", in fact - a comment block in CSS file, which describes substance structure with CSS classes. Substance can be element, block or project, depending on methodology that you do (or _do not_) use.
 
-Это ваш верный спутник в большом проекте и помощник для ваших коллег, если вы работаете в команде.
+This is your trusted companion in large project and assistant for your colleages, if you work in team.
 
-Порог вхождения минимален - используется привычный синтаксис и несколько логичных правил.  
-Однако подразумевается, что вы знакомы с [БЭМ](http://ru.bem.info/method/), [SMACSS](http://smacss.com/), [MCSS](https://github.com/operatino/MCSS) и т.д. и возможно используете одну из этих методологий.  
-Если нет, вы наверняка слышали о [Bootstrap](http://twitter.github.io/bootstrap/) и прочих фрэймворках.  
-В любом случае рекомендуется ознакомиться с терминологией [OOCSS](http://oocss.org/) _до_ прочтения документации.
+Low entry barriers - use regular syntax and some logical rules.  
+However, it's implied that you familiar with [BEM](http://ru.bem.info/method/), [SMACSS](http://smacss.com/), [MCSS](https://github.com/operatino/MCSS) etc. and perhaps already use any of theese methodologies.  
+If not, you could possibly hear about [Bootstrap](http://twitter.github.io/bootstrap/) and other frameworks.  
+Either way it is recommended to get yourself acquainted with [OOCSS](http://oocss.org/) terminology _before_ further reading.
 
-## Для кого и для чего
+## For whom and for what
 
-* Лучшее структурирование кода и понимание чужих спецификаций
-* Инструмент общения с коллегами или разработчиками, далекими от фронтенда
-* Выявление потенциальных "узких мест" в верстке (уровень вложенности, количество классов и т.д.)
-* Упрощение дебаггинга и рефакторинга
-* Это просто красиво!
+* Better code structure and getting into new code
+* Conversation tool for colleages and developers, distant from front-end
+* Detecting potential "bottlenecks" in layout (excessive DOM nesting, classes amount etc.)
+* Easier debugging and refactoring
+* It's just pretty!
 
-## Как начать
+## Quick start
 
-Ознакомиться с первой частью спецификации CSSG - [basic.md](basic.md)  
-Если все просто - пробуйте и изучайте вторую часть - [advanced.md](advanced.md)  
-Памятка по синтаксису - [legend.md](legend.md)
+Get to know first part of CSSG documentation - [basic.md](basic.md)  
+Easy enough - try it and continue reading - [advanced.md](advanced.md)  
+Syntax legend - [legend.md](legend.md)
 
 -----
 
-## Планы на ближайшее будущее
+## CSSG generator
 
-* Создание генератора CSSG
+Of course it's far more handy to get into into CSSG using automatic generator.
+Check out [CSSG multipurpose converter](https://github.com/XOP/css-o-gram_tool)
 
 -----
 
-Вопросы можно задавать по [электронной почте](mailto:[email protected]).  
-Все материалы доступны для свободного распространения.  
-При копировании [ссылка на источник](https://github.com/XOP/css-o-gram) обязательна.
+Feel free to ask questions via [email](mailto:[email protected]).  
+All content is available for free distribution.  
+[Link to source](https://github.com/XOP/css-o-gram) is mandatory when copying materials.

advanced.md

@@ -1,21 +1,20 @@
-# Копаем глубже
+# Let's dig in
 
-## Множества
+## Multiplicity
 
-Для некоторых сущностей, например элементов списка или просто последовательности одинаковых блоков характерно множественное появление.  
+Multiplicity happens to be typical for some substances, e.g. list elements or some blocks sequence.
 
-В CSSG это будет выглядеть так:
+In CSSG it will look like this:
 
-
-    /*
+	/*
 
 	    post_cnt
 	    	post_cnt_ul
 	    		post_cnt_li +
 
 	*/
 
-или так
+or like that:
 
 	/*
 
@@ -24,35 +23,35 @@
 
 	*/
 
-Ключевое отличие '+' и '*' - в специфике множества.  
-'+' указывает, что элемент появится хотя бы один раз (характерно для элементов списка - \<li\>)  
-'*' указывает, что элемент появится 0 и более раз (относится как правило ко всем остальным элементам)  
+The main difference between '+' and '*' is in multiplicity specifics.  
+'+' says that element will appear at least 1 time (which is typical for list items - \<li\>)  
+'*' however says that element may appear more than 0 times (any other elements - you name it)
 
-> важно понимать разницу между опциональным появлением ([element]) и появлением 0 и более раз (element *)  
-> на первый взгляд отличие незначительное, но в контексте все встает на свои места
+> it's important to feel the distinction between optional elements ([element]) and appearing 0 and more times (element *)  
+> insignificant on the first sight, it appears to have contextual meaning
 
-## Модификаторы - больше и удобнее
+## Modificators - more and meaningful
 
-Как было указано в [basic.md](basic.md), модификаторы дополняют сущность и теоретически возможно их одновременное появление.  
-Необходимая логика описывается дополнительным синтаксисом.  
+As it was mentioned in [basic.md](basic.md), modificators complement substance and theoretically their simultaneous presence is possible.  
+Crucial logic described with the help of special syntax.
 
-Взаимоисключение выглядит следующим образом: 
+For example, alternative is illustrated this way:
 
 	/*
 		
 	    post                            ( __current | __regular ) __deleted
 
 	*/
 
-и даже так:
+and even like this:
 
 	/*
 
 	    post                            ( ( __current | __regular ) | __compact ) __deleted
 
 	*/
 
-Когда класс жестко связан с модификатором (бесполезен или не используется без него), это указывается через точку:
+Dot (.) illustrates robust connection between class and another class or modificator
 
 	/*
 
@@ -65,12 +64,12 @@
 
 	*/
 
-> отбивка по правому краю для привязанного класса не нужна
+> alignment on the right for connected class is not necessary
 
-## Наследование
+## Inheritance
 
-Сущность может быть прямым наследником другой сущности.  
-Чтобы обозначить это, указывает "родителя" через @.
+Substance can be direct descendant of other substance.  
+To point this out, define ancestor via "@" symbol.
 
 	/*
 
@@ -80,11 +79,11 @@
 
 	*/
 
-> не обязательно перечислять модификаторы, поскольку они наследуются по умолчанию  
-> однако если есть отличия, необходимо перечислить все возможные классы  
-> по умолчанию принятно, что указанные модификаторы будут являться единственно возможными
+> it's not necessary to list all modificators, because they inherited by default  
+> however, if there is any difference, we must list all possible classes  
+> it's accepted that these defined modificators will only be possible
 
-Например, в этом примере **post-advanced** будет иметь один возможный модификатор **__new**, несмотря на наличие модификаторов у **post**
+For instance, it is illustrated in the following code, that **post-advanced** will have one possible modificator **__new**, regardless the fact, that **post** has some modificators as well
 
 	/*
 
@@ -94,13 +93,13 @@
 
 	*/
 
-## Условная шаблонизация
+## Nominal templates
 
-Наследование напрямую связано с условной шаблонизацией.  
-Указывая в родительской сущности изменяемые части, мы упрощаем описание потомственной сущности и избегаем дублирования кода.  
-Это не обязательная, но удобная практика, если таких сущностей как минимум две.
+Inheritance is directly connected with nominal templates.  
+We simplify illustration of descendant substance and avoid code duplication by setting changeable parts in ancestor substance.  
+This is not mandatory, but turns out to be helpful if you have at least two such substances.
 
-Например, родительская сущность выглядит так:
+As an example, let's say ancestor substance looks like this:
 
 	/*
 
@@ -109,8 +108,8 @@
 	            % content %
 
 	*/
- 
-или так, если существует содержимое по умолчанию
+
+or like this, if there is any default content 
 
 	/*
 
@@ -121,7 +120,7 @@
 
 	*/
 
-потомственная сущность
+descendant substance
 
 	/*
 
@@ -133,10 +132,10 @@
 
 	*/
 
-> когда шаблон "раскрывается", второй символ % не пишем
+> when "filling" the template second % symbol is unnecessary
 
-В этом случае **post-advanced\_cnt** будет находится внутри **post\_cnt** и перепишет контент по умолчанию из второго примера.
-Если не использовать шаблонизацию, то же самое можно записать так:
+In this case **post-advanced\_cnt** will be inside **post\_cnt** and will override default content from second code piece.  
+Without nominal templates, CSSG may look like this:
 
 	/*
 
@@ -148,14 +147,14 @@
 
 	*/
 
-В данном случае разницы почти нет.  
-Но достаточно рассмотреть пример в контексте громоздкой структуры, чтобы ощутить все преимущества записи.
+There's almost no difference in this case.  
+However all notation potential can be seen in context of describing more complex structure
 
-> элемент **% content %** в разметке не имеет DOM-воплощения, это просто название шаблона
+> the **% content %** element has no DOM implementation, it is just a template name
 
-## Динамика
+## Dynamics
 
-Под динамикой понимается появление того или иного класса или элемента в процессе отработки скриптов и/или в результате действий пользователя.  
+By dynamics it's meant that some class or element may appear in layout due to scripts and user activity.
 
 	/*
 	 
@@ -166,7 +165,7 @@
 
 	*/	
 
-Для обозначения динамических блоков используется дополненный существующий синтаксис опциональных частей:
+To define dynamic blocks complemented syntax for optional parts is used:
 
 	/*
 	 
@@ -183,9 +182,9 @@
 
 ## It's <<omplicated
 
-Сложные решения в CSS тоже можно иллюстрировать с помощью CSSG.
+Complex CSS approach can be described with CSSG.
 
-Ситуация с взаимоисключающими блоками:
+Alternative (mutual exclusive) blocks example:
 
 	/*
 
@@ -202,7 +201,7 @@
 	 
 	*/
 
-Нужно указать наличие какого-либо ключевого класса где-то высоко в DOM:
+When it's necessary to illustrate some valueable class somewhere high in DOM tree:
 
 	/*
 		
@@ -216,7 +215,7 @@
 	 
 	*/
 
-CSSG _как правило_ само-демонстративен, но в особо сложных ситуациях не обойтись без комментариев:
+CSSG is self-explanatory _as a rule_, but some tough situations may require comments:
 
 	/*