Fix projectfluent#7. Introduce tags

Tags are binary values attached to messages.  They are language-specific and
can be used to describe grammatical characteristics of the message.

    brand-name = Firefox
        #masculine

    brand-name = Aurora
        #feminine
        #vowel

Tags can be used in select expressions by matching a hashtag name to the
message:

    has-updated = { brand-name ->
            [masculine] …
            [feminine] …
           *[other] …
        }

Tags can only be defined on messages which have a value and don't have any
attributes.

Author: stasm

guide/SUMMARY.md

@@ -6,6 +6,7 @@
 * [External Data](external.md)
 * [Selectors](selectors.md)
 * [Variants](variants.md)
+* [Tags](tags.md)
 * [Attributes](attributes.md)
 * [Sections](sections.md)
 * [Comments](comments.md)

guide/tags.md

@@ -0,0 +1,40 @@
+# Tags
+
+```
+brand-name = Aurora
+    #żeński
+
+has-updated = { brand-name ->
+        [męski] { brand-name} został zaktualizowany.
+        [żeński] { brand-name } została zaktualizowana.
+       *[inny] Program { brand-name } został zaktualizowany.
+    }
+```
+
+Sometimes translations might vary depending on some grammatical trait of
+another message.  In the example above the form of the past tense of _has been
+updated_ depends on the grammatical gender of `brand-name`.
+
+In such cases you can _tag_ messages with simple one-word _hashtags_ and then
+define different translations based on these tags.  You define them with `#`
+which must start on a new line under the message, indented.
+
+Hashtags are specific to your language's grammar and don't have to be in
+English. In the example above, _żeński_ means _feminine_, _męski_ is
+_masculine_ and _inny_ is _other_.
+
+Both tags and variants discussed in the previous chapter can be used to provide
+more information about a message that is specific to your language.  There
+a number of differences between them, however.
+
+  - Tags don't have a value; they _are_ the value.
+
+  - Tags can only be used for matching.  They cannot be inserted into another
+    translation.
+
+  - Tags describe grammatical traits; they should answer the question _Is this
+    message <tagname>_?  For instance, _Is this message feminine?_
+
+  - On the other hand, variants define different _facets_ of the message.  It's
+    the same value, just in slightly different forms to make it grammatically
+    correct when used inside of other messages.

spec/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## Unreleased
 
+  - Introduce tags for language-specific grammatical information.
+
+    Tags are binary values attached to messages.  They are language-specific and
+    can be used to describe grammatical characteristics of the message.
+
+        brand-name = Firefox
+            #masculine
+
+        brand-name = Aurora
+            #feminine
+            #vowel
+
+    Tags can be used in select expressions by matching a hashtag name to the
+    message:
+
+        has-updated = { brand-name ->
+                [masculine] …
+                [feminine] …
+               *[other] …
+            }
+
+    Tags can only be defined on messages which have a value and don't have any
+    attributes.
+
   - Require the message body to be indented.
 
     Quoted strings are now only valid in placeables and cannot contain other

spec/fluent.asdl

@@ -23,7 +23,7 @@ module Fluent
 {
     res = Resource(entry* body, comment? comment)
 
-    entry = Message(iden id, pat? value, attr* attributes, comment? comment)
+    entry = Message(iden id, pat? value, attr* attributes, tag* tags, comment? comment)
           | Section(symb name, comment? comment)
           | Comment(comment)
           | Junk(string content)
@@ -45,6 +45,9 @@ module Fluent
     -- Attributes of Message
     attr = Attribute(iden id, pat value)
 
+    -- Tags of Message
+    tag = Tag(symb name)
+
     -- Variants of SelectExpression
     var = Variant(varkey key, pat value, bool default)
     varkey = Number(number)

spec/fluent.ebnf

@@ -34,10 +34,13 @@ variant              ::= NL __ '[' _? variant-key _? ']' __ pattern
 default-variant      ::= NL __ '*[' _? variant-key _? ']' __ pattern
 variant-list         ::= variant* default-variant variant*
 
+tag                  ::= '#' word
+tag-list             ::= NL (__ tag)+
+
 attribute            ::= NL __ '.' identifier value
 attribute-list       ::= attribute+
 
-message              ::= identifier (value attribute-list? | attribute-list)
+message              ::= identifier ((value tag-list?) | (value? attribute-list))
 value                ::= _? '=' __? pattern
 pattern              ::= (text | placeable)+
 text                 ::= ((char - line-break) - special | break-indent | '\' special)+