correspondence-markup 0.3.1 → 0.3.2

data/lib/correspondence-markup.rb

@@ -5,18 +5,18 @@ require 'correspondence-markup/bracketed-grammar'
 
 module CorrespondenceMarkup
   
-  # Compiler than parses and compiles correspondence markup source code 
+  # Compiler that parses and compiles correspondence markup source code 
   # into an array of StructureGroup objects (from which HTML can be
-  # generated in the format required by correspondence.js)
+  # generated in the format required by correspondence.js).
   class CorrespondenceMarkupCompiler
     
-    # initialize by creating the CorrespondenceMarkupLanguageParser (defined by the Treetop source)
+    # Initialize by creating the CorrespondenceMarkupLanguageParser (defined by the Treetop source).
     def initialize
       @parser = CorrespondenceMarkupLanguageParser.new
     end
     
-    # compile source code into an array of StructureGroups, 
-    # throwing an exception if there is a parse error
+    # Compile source code into an array of StructureGroup objects, 
+    # throwing an exception if there is a parse error.
     def compile_structure_groups(markup)
       syntax_tree = @parser.parse(markup, root: :structure_groups)
       if(syntax_tree.nil?)

data/lib/correspondence-markup/bracketed-grammar.treetop

@@ -1,9 +1,9 @@
 require "correspondence-markup/types"
 
-# Grammar for a markup language which can be compiled into HTML format
+# Grammar for a markup language which can be compiled into the HTML format
 # required by correspondence.js
 
-# General note on bracketing of sequences - different components are enclosed
+# General note on bracketing of sequences: different components are enclosed
 # by different types of bracket, in particular:
 #
 # * item: "[]"
@@ -15,23 +15,30 @@ require "correspondence-markup/types"
 # at which to edit components of particular content, the parsing of brackets
 # is handled by the parent component, e.g. the "{}" bracketing of structures
 # is specified in the grammar rule for structure_group.
-# For example, if a user is editing a structure definition in a UI text area, 
+# The motivation for this is: if a user is editing a structure definition in a UI text area, 
 # there should be no necessity for the user to enter the enclosing "{}" brackets, 
 # because the UI text area implicitly encloses the definition that the user is editing.
+# So the software would want to parse the definition of a structure without the {}.
+# (And if the user was editing each item group in a separate text field, then
+# similarly the user would not want to include the outer "[]" brackets in each
+# item group definition.)
 
 grammar CorrespondenceMarkupLanguage
 
   # Include the Module containing Ruby classes representing the AST nodes
   include CorrespondenceMarkup
 
-  # This rule defines a sequence of structure groups.
+  # This rule defines a sequence of structure groups (intended to be displayed on one web page).
   # Individual structure groups are independent of each other
-  # (although typically they will be a sequence of structure groups
-  # where each structure group has structures in the same sequence of languages).
+  # (although typically a sequence of structure groups
+  # where each structure group has structures with the same sequence of languages, 
+  # e.g. three structure groups of two structures each with languages 
+  # spanish/english, spanish/english, spanish/english, representing the
+  # translations of three verses of a song).
   rule structure_groups
     s groups:("(" structure_group ")" s)*
     {
-      # Return an array of StructureGroup object
+      # Return an array of StructureGroup's
       def value
         groups.elements.map {|e| e.structure_group.value}
       end
@@ -60,10 +67,10 @@ grammar CorrespondenceMarkupLanguage
 
   # A structure is one of two or more structures in a structure group
   # (although the grammar does not impose any count restriction, in anticipation
-  # of application user's editing and saving incomplete content).
+  # of application users editing and saving incomplete content).
   # A structure has a "type" (short language description intended to map to a CSS class), 
-  # a "description" (longer but still concise language description for display to the reader)
-  # and a sequence of "item groups".
+  # a "description" (longer but still concise language description for display to the reader), 
+  # and contains a sequence of "item groups".
   rule structure
     structure_annotation s itemGroups:("[" item_group "]" s)*
     { 
@@ -119,8 +126,8 @@ grammar CorrespondenceMarkupLanguage
   # A "non-item" is textual content in an item group that is not part of an actual item.
   # In effect this is text which is either not translatable to content in other structures
   # in the same structure group, or, it is considered unimportant to identify its translation.
-  # For example, in the second case, punctuation in sentences, where translation is reasonably obvious, and we
-  # wish to highlight the translations of the actual words.
+  # For example, in the second case, punctuation in sentences, where the translation is reasonably 
+  # obvious, and we wish to highlight only the translations of the actual words.
   rule non_item
     text:text
     { 
@@ -137,7 +144,7 @@ grammar CorrespondenceMarkupLanguage
   # Typically, items with the same ID in the same structure are considered to be part of the
   # "same item", and items with the same ID in different structures are considered to be
   # translations of each other.
-  # Item IDs consists of an upper-case alphabetic prefix followed by a numeric ID.
+  # An item ID consists of an upper-case alphabetic prefix followed by a numeric ID.
   # Any item ID that lacks an alphabetic prefix will have the item group ID of the containing
   # item group added as a prefix to its ID.
   # (This reflects the assumption that an item usually relates to items in item groups in other
@@ -168,7 +175,7 @@ grammar CorrespondenceMarkupLanguage
     }
   end
   
-  # Items can actually have multiple IDs, in which case they are separated by commas
+  # Items can have multiple IDs, in which case they are separated by commas
   # (and no whitespace). If there are multiple IDs, the convention of applying the
   # item group ID as a default prefix is applied individually to each ID.
   # So, for example, "2,A2,3" in item group B would be expanded to "B2,A2,B3".

data/lib/correspondence-markup/types.rb

@@ -14,18 +14,21 @@ module CorrespondenceMarkup
     # Either 1: a tag enclosed in "<" & ">", possibly missing the ">", or, 2: text outside a tag
     TAGS_AND_TEXT_REGEX = /([<][^>]*[>]?)|([^<]+)/
     
-    # Split some HTML source into tags and plain text not in tags
-    # (so that the two can be processed differently, e.g. applying a transformation to text content
-    # where you don't want the transformation to apply to the internals of a directly-coded HTML tag)
+    # Split some HTML source into tags and plain text not in tags.
+    # (For example, so that the two can be processed differently, e.g. applying a transformation to text content
+    # where you don't want the transformation to apply to the internals of directly-coded HTML tags.)
     def self.split_tags_and_text(html)
       html.scan(TAGS_AND_TEXT_REGEX).to_a
     end
     
     # Convert text content into HTML according to various true/false options.
     # Note: the text may contain HTML tags
-    # * escaped: if true, HTML-escape the text
-    # * br: if true, convert end-of-line characters to <br/> tags
-    # * nbsp: if true, convert all spaces in the text that is not in tags into &nbsp;
+    # * :escaped - if true, HTML-escape the text
+    # * :br - if true, convert end-of-line characters to <br/> tags
+    # * :nbsp - if true, convert all spaces in the text that is not in tags into &nbsp;
+    # Of these options, *:escaped* only makes sense if you _don't_ want to include additional HTML
+    # markup in the content; *:br* and *:nbsp* make sense for programming languages but not for 
+    # natural languages.
     def text_to_html(text, options)
       html = text
       if options[:escaped]
@@ -44,22 +47,29 @@ module CorrespondenceMarkup
     end
   end
   
-  # An item is text in a structure with an associated id
+  # An Item is text in a structure with an associated ID.
   # Typically if would be a word in a sentence. Items are to 
   # be related to other items in other structures in the same
-  # structure group that have the same ID (also to other items
-  # in the same structure with the same ID).
+  # structure group that have the same ID.
+  # When two or more items in the same structure have the same ID, 
+  # they are considered to be parts of the same item.
+  # (For example, in "I let it go", we might want to identify "let" and "go" as a single item, 
+  # because they are part of an English phrasal verb "let go", 
+  # and its meaning is not quite the sum of the meanings of those two component words.)
   class Item
     
     include Helpers
     
-    # The ID, which identifies the item (possibly not uniquely) within a given structure
+    # The ID, which identifies the item (possibly not uniquely) within a given structure.
+    # An ID can be a comma-separated string of multiple IDs (this is relevant for partial
+    # matching, and should only be used when there are more than two structures in a group
+    # and one of the structures has less granularity than other structures in that group).
     attr_reader :id
     
-    # The text of the item
+    # The text of the item.
     attr_reader :text
 
-    # Initialize from ID and text
+    # Initialize from ID and text.
     def initialize(id, text)
       @id = id
       @text = text
@@ -71,6 +81,7 @@ module CorrespondenceMarkup
     end
     
     # An item is equal to another item with the same ID and text
+    # (equality is only used for testing)
     def ==(otherItem)
       otherItem.class == Item && otherItem.id == @id && otherItem.text == @text
     end
@@ -102,6 +113,7 @@ module CorrespondenceMarkup
     end
     
     # A non-item is equal to another non-item with the same text
+    # (equality is only used for testing)
     def ==(otherNonItem)
       otherNonItem.class == NonItem && otherNonItem.text == @text
     end
@@ -112,14 +124,15 @@ module CorrespondenceMarkup
     end
   end
   
-  # A group of items & non-items that will form part of a structure
-  # Typically an item group is one line of items (words), or maybe
+  # A group of items & non-items that will form part of a structure.
+  # Typically an item group is one line of items (i.e. words) and non-items, or maybe
   # two or three lines which naturally group together within the
-  # overall structure.
+  # overall structure (and which cannot be separated because they
+  # translate to a single line in one of the other structures in the
+  # same structure group).
   # Item groups with the same ID in different structures in the same
-  # structure group related to each other, and may be shown next
+  # structure group are related to each other, and may be shown next
   # to each other in the UI when the "Interleave" option is chosen.
-  # (An "item group" could also be regarded as a "sub-structure".)
   class ItemGroup
     
     # The ID which is unique in the structure. It identifies the 
@@ -137,6 +150,7 @@ module CorrespondenceMarkup
     end
 
     # An item group is equal to another item group with the same IDs and the same content
+    # (equality is only used for testing)
     def ==(otherItemGroup)
       otherItemGroup.class == ItemGroup && otherItemGroup.id == @id && otherItemGroup.content == @content
     end
@@ -174,6 +188,7 @@ module CorrespondenceMarkup
     end
 
     # A structure is equal to another structure with the same type, description and item groups
+    # (equality is only used for testing)
     def ==(otherStructure)
       otherStructure.class == Structure && otherStructure.type == @type  &&
         otherStructure.description == description &&
@@ -206,10 +221,10 @@ module CorrespondenceMarkup
   end
 
   # A structure group is a group of structures. Different structures in one structure group
-  # all represent the same information, but in different "languages". Items different
+  # all represent the same information, but in different "languages". Items in different
   # structures with the same item ID are shown in the UI as being translations of each other.
-  # (Items with the same ID in the same structure are also show as related, and are presumed
-  # to be separated components of a single virtual item.)
+  # (Items with the same ID in the same structure are also shown as related, and are presumed
+  # to be different parts of a single virtual item.)
   class StructureGroup
     
     # The array of structures
@@ -221,6 +236,7 @@ module CorrespondenceMarkup
     end
 
     # A structure group is equal to another structure group that has the same structures
+    # (equality is only used for testing)
     def ==(otherStructureGroup)
       otherStructureGroup.class == StructureGroup && otherStructureGroup.structures == @structures
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: correspondence-markup
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
   prerelease: 
 platform: ruby
 authors:
@@ -38,7 +38,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1042658257
+      hash: 617305043
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: