--- loncom/homework/structuretags.pm	2011/12/12 11:19:53	1.497.2.1
+++ 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.1 2011/12/12 11:19:53 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,9 +1657,47 @@ sub end_languageblock {
     }
     return $result;
 }
-
+#  languagblock specific tags:
 {
-    my %available_texts;
+    # For chunks of a resource that has translations, this hash contains
+    # the translations available indexed by language name.
+    #
+
+    my %available_texts;       
+
+    # <translated> starts a block of a resource that has multiple translations.
+    # See the <lang> tag as well.
+    # When </translated> is encountered if there is a translation for the 
+    # currently preferred language, that is rendered inthe web/tex/webgrade
+    # targets.  Otherwise, the default text is rendered.
+    #
+    # Note that <lang> is only registered for the duration of the 
+    #  <translated>...</translated> block 
+    #
+    # Pathalogical case handling:
+    #   - If there is no <lang> that specifies a 'default' and there is no
+    #     translation that matches a preferred language, nothing is rendered.
+    #   - Nested <translated>...</translated> might be linguistically supported by
+    #     XML due to the stack nature of tag registration(?) however the rendered
+    #     output will be incorrect because there is only one %available_texts
+    #     has and end_translated clears it.
+    #   - Material outside of a <lang>...</lang> block within the
+    #     <translated>...<translated> block won't render either e.g.:
+    #    <translated>
+    #      The following will be in your preferred langauge:
+    #      <lang which='en'>
+    #         This section in english
+    #      </lang>
+    #      <lang which='sgeiso'>
+    #         Hier es ist auf Deutsch.
+    #      </lang>
+    #      <lang which='sfriso'>
+    #         En Francais
+    #      </lang>
+    #    </translated>
+    #
+    #    The introductory text prior to the first <lang> tag is not rendered.
+    #
     sub start_translated {
 	my ($target,$token,$tagstack,$parstack,$parser,$safeeval,$style)=@_;
 	&Apache::lonxml::register('Apache::structuretags',('lang'));
@@ -1685,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' ||
@@ -1716,7 +1789,8 @@ sub end_languageblock {
 	}
 	return '';
     }
-}
+}				# end langauge block specific tags.
+
 
 sub start_instructorcomment {
     my ($target,$token,$tagstack,$parstack,$parser,$safeeval,$style)=@_;