--- loncom/homework/structuretags.pm	2011/12/12 11:19:53	1.497.2.1
+++ loncom/homework/structuretags.pm	2011/12/12 11:40:30	1.497.2.2
@@ -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.2 2011/12/12 11:40:30 foxr Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -1659,7 +1659,45 @@ sub end_languageblock {
 }
 
 {
-    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'));