--- loncom/homework/structuretags.pm	2011/12/12 11:40:30	1.497.2.2
+++ loncom/homework/structuretags.pm	2011/12/12 12:07:45	1.497.2.3
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA 
 # definition of tags that give a structure to a document
 #
-# $Id: structuretags.pm,v 1.497.2.2 2011/12/12 11:40:30 foxr Exp $
+# $Id: structuretags.pm,v 1.497.2.3 2011/12/12 12:07:45 foxr Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -1657,7 +1657,7 @@ sub end_languageblock {
     }
     return $result;
 }
-
+#  languagblock specific tags:
 {
     # For chunks of a resource that has translations, this hash contains
     # the translations available indexed by language name.
@@ -1723,7 +1723,42 @@ sub end_languageblock {
 	return $result;
     }
 
-
+    # <lang [which='language-name'] [other='lang1,lang2...']>  
+    #  Specifies that the block contained within it is a translation 
+    #  for a specific language specified by the 'which' attribute. The
+    #   'other' attribute can be used by itself or in conjunction with
+    #   which to specify this tag _may_ be used as a translation for some
+    #   list of languages. e.g.:  <lang which='senisoUS' other='senisoCA,senisoAU,seniso'>
+    #   specifying that the block provides a translation for US (primary)
+    #   Canadian, Australian and UK Englush.
+    #   
+    # Comment: this seems a bit silly why not just support a list of languages
+    #           e.g. <lang which='l1,l2...'> and ditch the other attribute?
+    #
+    #  Effect:
+    #    The material within the <lang>..</lang> block is stored in the
+    #    specified set of $available_texts hash entries, the appropriate one
+    #    is selected at </translated> time.
+    #
+    #  Pathalogical case handling:
+    #    If a language occurs multiple times within a <translated> block,
+    #    only the last one is rendered e.g.:
+    #
+    #    <translated>
+    #       <lang which='senisoUS', other='senisoCA,senisoAU,seniso'>
+    #          Red green color blindness is quite common affecting about 7.8% of 
+    #          the male population, but onloy about .65% of the female population.
+    #       </lang>
+    #          Red green colour blindness is quite common affecting about 7.8% of 
+    #          the male population, but onloy about .65% of the female population.
+    #       <lang which='seniso', other='senisoCA,senisoAU'>
+    #     </translated>
+    #
+    #    renders the correct spelling of color (colour) for people who have specified
+    #    a preferred language that is one of the British Commonwealth languages
+    #    even though those are also listed as valid selections for the US english
+    #    <lang> block.
+    #
     sub start_lang {
 	my ($target,$token,$tagstack,$parstack,$parser,$safeeval,$style)=@_;
 	if ($target eq 'web' || $target eq 'grade'   || $target eq 'answer' ||
@@ -1754,7 +1789,8 @@ sub end_languageblock {
 	}
 	return '';
     }
-}
+}				# end langauge block specific tags.
+
 
 sub start_instructorcomment {
     my ($target,$token,$tagstack,$parstack,$parser,$safeeval,$style)=@_;