--- loncom/homework/structuretags.pm	2011/09/13 15:40:37	1.496
+++ 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.496 2011/09/13 15:40:37 raeburn Exp $
+# $Id: structuretags.pm,v 1.497.2.3 2011/12/12 12:07:45 foxr Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -283,7 +283,7 @@ sub page_start {
         &Apache::lonhtmlcommon::clear_breadcrumbs();
         &Apache::lonhtmlcommon::add_breadcrumb({
             'text'  => 'Construction Space',
-            'href'  => &Apache::loncommon::authorspace(),
+            'href'  => &Apache::loncommon::authorspace($env{'request.uri'}),
         });
         # breadcrumbs (and tools) will be created 
         # in start_page->bodytag->innerregister
@@ -1539,54 +1539,100 @@ sub end_block {
     }
     return $result;
 }
-
+#
+#  <languageblock [include='lang1,lang2...'] [exclude='lang1,lang2...']>
+#  ...
+#  </languageblock>
+#
+#   This declares the intent to provide content that can be rendered in the
+#   set of languages in the include specificatino but not in the exclude
+#   specification.  If a currently preferred language is in the include list
+#   the content in the <languageblock>...</languageblock> is rendered
+#   If the currently preferred language is in the exclude list,
+#   the content in the <languageblock>..></languageblock is not rendered.
+#
+#   Pathalogical case handling:
+#     - Include specified, without the preferred language but exclude  specified
+#       also without the preferred langauge results in rendering the block.
+#     - Exclude specified without include and excluden not containing a 
+#       preferred language renders the block.
+#     - Include and exclude both specifying the preferred language does not
+#       render the block.
+#     - If neither include/exclude is specified, the block gets rendered.
+#
+#  This tag has no effect when target is in {edit, modified}
+#
 sub start_languageblock {
     my ($target,$token,$tagstack,$parstack,$parser,$safeeval,$style)=@_;
 
-    my $result;
+    my $result = '';
 
     if ($target eq 'web' || $target eq 'grade'   || $target eq 'answer' ||
 	$target eq 'tex' || $target eq 'analyze' || $target eq 'webgrade') {
 	my $include = $token->[2]->{'include'};
 	my $exclude = $token->[2]->{'exclude'};
         my @preferred_languages=&Apache::lonlocal::preferred_languages();
-# This should not even happen, since we should at least have the server language
-        if (!$preferred_languages[0]) { $preferred_languages[0]='en'; }
-# Now loop over all languages in order of preference
+
+        # This should not even happen, since we should at least have the server language
+
+        if (!$preferred_languages[0]) { 
+	    $preferred_languages[0]='en'; 
+	}
+
+        # Now loop over all languages in order of preference
+
         foreach my $preferred_language (@preferred_languages) {
-# If the languageblock has no arguments, show the contents
-           $result=1;
+
+	    # If neither include/nor exlude is present the block is going
+	    # to get rendered.
+
+           my $render=1;
            my $found=0;
-# Do we have an include argument?
+           
+	   #  If include is specified,  don't render the block
+	   #  unless the preferred language is included in the set.
+
 	   if ($include) {
-# If include is specified, by default, don't render the block
-              $result=0;
+              $render=0;
               foreach my $included_language (split(/\,/,$include)) {
-# ... but if my preferred language is included, render it
                  if ($included_language eq $preferred_language) {
-                    $result=1; 
+                    $render=1; 
                     $found=1; 
+		    last;	# Only need to find the first.
                  }
               }
 	   }
-# Do we have an exclude argument?
+           # Do we have an exclude argument?
+	   # If so, and one of the languages matches a preferred language
+	   # inhibit rendering the block.  Note that in the pathalogical case the
+	   # author has specified a preferred language in both the include and exclude
+	   # attribte exclude is preferred.  
+
            if ($exclude) {
-              $result=1;
+              $render=1;
               foreach my $excluded_language (split(/\,/,$exclude)) {
                  if ($excluded_language eq $preferred_language) {
-                    $result=0;
+                    $render=0;
                     $found=1;
+		    last;	# Only need to find the first.
                  }
               }
 	   }
-           if ($found) { last; }
+           if ($found) { 
+	       last; 		# Done on any match of include or exclude.
+	   }
         }
-	if ( ! $result ) {
+	# If $render not true skip the entire block until </languageblock>
+	#
+
+	if ( ! $render ) {
 	    my $skip=&Apache::lonxml::get_all_text("/languageblock",$parser,
 						   $style);
 	    &Apache::lonxml::debug("skipping ahead :$skip: $$parser[-1]");
 	}
-	$result='';
+	# If $render is true, we've not skipped the contents of the <languageglock>
+	# and the normal loncapa processing flow will render it as a matter of course.
+
     } elsif ($target eq 'edit') {
 	$result .=&Apache::edit::tag_start($target,$token);
 	$result .=&Apache::edit::text_arg(&mt('Include Language:'),'include',
@@ -1611,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'));
@@ -1639,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' ||
@@ -1670,7 +1789,8 @@ sub end_languageblock {
 	}
 	return '';
     }
-}
+}				# end langauge block specific tags.
+
 
 sub start_instructorcomment {
     my ($target,$token,$tagstack,$parstack,$parser,$safeeval,$style)=@_;