Enhanced README

README.md

@@ -11,13 +11,54 @@ The tools used in the implementation of _jqt_ are:
 * [jq](https://stedolan.github.io/jq/), a lightweight and flexible command-line JSON processor.
 * [GPP](https://logological.org/gpp), a general-purpose preprocessor.
 * [Pandoc](http://pandoc.org/), a universal document converter.
-* [GNU Make](https://www.gnu.org/software/make/), the classical tool for managing projects.
 * [Bash](https://www.gnu.org/software/bash/), [sed](https://www.gnu.org/software/sed/) and other shell tools.
 
+If you are interested in _jq_ you can see also [JBOL](https://fadado.github.io/jbol/),
+a related project with a collection of modules for the _jq_ language.
+
 _jqt_ is developed under the _Fedora_ Linux distribution, and a lot of
 portability issues are expected at this stage of development. Please, use this
 GitHub repository features if you want to send any kind of questions.
 
+## Project management
+
+This project uses [GNU Make](https://www.gnu.org/software/make/) on several
+development activities, but `make` is not necessary to run `jqt`. This section explains
+the repository structure and how it is managed.
+
+### Makefile
+
+The file `Makefile` concentrates all the routine procedures, like running the tests
+or install last versions of scripts in the system directories. The main defined _targets_
+are:
+
+* `check`: run the _jqt_ tests. This is the default target.
+
+* `clean`: remove all files generated during tests execution.
+
+* `install`: install _jqt_ scripts and related files in the system directories.
+
+* `uninstall`: remove installed files from the system directories.
+
+* `help`:  list all targets defined in the Makefile.
+
+### Scripts
+
+The `bin` directory contains `jqt` and other related tools. The `jqt` script
+also needs some files located in the [`share`](./share/) directory.
+
+### Tests
+
+The execution of `make check` or simply `make` will run several tests located in the directory
+[`tests`](./tests/). Ensure that the tests are passed before start
+another `jqt` uses.
+
+### Documentation
+
+The directory [`docs`](./docs/) contains the documentation for _jqt_, and is in itself a subproject with his
+own makefile. Please see the directory [`docs`](./docs/) for all information on
+this subproject.
+
 <!--
 vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown
 -->

docs/blocks/menu-bar/style.css

@@ -25,7 +25,7 @@
 }
 
 &BEM{menu-bar}{item}{current} > a,
-&CHAIN{menu-bar}{item}{current} > a {
+&CHM{menu-bar}{item}{current} > a {
   text-decoration: underline;
 }
 

docs/blocks/panel/style.css

@@ -8,14 +8,14 @@
 }
 
 &BEM{#panel}{}{side-right},
-&CHAIN{#panel}{}{side-right} {
+&CHM{#panel}{}{side-right} {
   float: right;
   margin: 0 0 0 1rem;
 }
 
 /*
 &BEM{#panel}{}{side-left},
-&CHAIN{#panel}{}{side-left} {
+&CHM{#panel}{}{side-left} {
   float: left;
   margin: 0 1rem 0 0;
 }

docs/styles/bem.m

@@ -2,32 +2,48 @@
 // BEM macros
 ////////////////////////////////////////////////////////////////////////
 
-// Selector, escaped if necessary
-// .s .\s
+// Simple selector
+//
+// Prefix selector with the escape character \ if necessary. Do not change
+// selectors if they start with [A-Za-z_-].
+//
 &define{SEL}{.&if{$1 =~ [A-Za-z_-]*}$1&else\$1&endif}
 
 // Block, element, modifier
-// .B, .B_M, .B__E, .B__E_M
+//
+// Cases:
+//
+// &BEM{block}                      => .block
+// &BEM{block}{}{modifier}          => .block_modifier
+// &BEM{block}{element}             => .block__element
+// &BEM{block}{element}{modifier}   => .block__element_modifier
+//
 &define{BEM}{&SEL{$1}&ifneq{$2}{}__$2&endif&ifneq{$3}{}_$3&endif}
 
 // Chained modifier
-// .B.-M, .B__E.-M
-&define{CHAIN}{&SEL{$1}&ifneq{$2}{}__$2&endif.-$3}
+//
+// Cases:
+//
+// &CHM{block}{modifier}            => .block.-modifier
+// &CHM{block}{element}{modifier}   => .block__element.-modifier
+//
+&define{CHM}{&SEL{$1}&ifneq{$2}{}__$2&endif.-$3}
 
 // Hack
+// 
+// Prefix selector with underline character and protect name with the escape
+// character \ if necessary.
+// 
 // ._N
+//
 &define{HACK}{._&if{$1 =~ [A-Za-z_-]*}$1&else\$1&endif}
 
 // Naming conventions:
-//  component, block, module    &BEM &CHAIN
-//  #object, #layout            &BEM &CHAIN
+//  component, block, module    &BEM &CHM
+//  #object, #layout            &BEM &CHM
 //  %utility                    &SEL
 //  $scope                      &SEL
 //  ^theme                      &SEL
 //  _hack                       &HACK
 
-// ???
-//  ?is (state)                 &SEL
-//  !has (state)                &SEL
-
 // vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=cpp

docs/styles/main.css

@@ -22,7 +22,7 @@
   html {
     background-color: &ColorInitial;
   }
-  body&BEM{#container} {
+  body&SEL{#container} {
     max-width: 800px;
   }
 }

docs/styles/new/utility.css

@@ -10,7 +10,7 @@
 // Utility
 // ––––––––––––––––––––––––––––––––––––––––––––––––––
 
-// Clear a float with ._clearfix
+// Clear a float with .%clearfix
 // JJOR: prefixed
 &SEL{%clearfix}::after {
   clear: both;