--- loncom/homework/radiobuttonresponse.pm	2005/06/22 12:03:23	1.102
+++ loncom/homework/radiobuttonresponse.pm	2008/12/11 03:25:45	1.141
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # mutliple choice style responses
 #
-# $Id: radiobuttonresponse.pm,v 1.102 2005/06/22 12:03:23 albertel Exp $
+# $Id: radiobuttonresponse.pm,v 1.141 2008/12/11 03:25:45 raeburn Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -18,54 +18,77 @@
 # GNU General Public License for more details.
 #
 # You should have received a copy of the GNU General Public License
-# along with LON-CAPA; if not, write to the Free Software
-# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+# along with LON-CAPA; if not, write to the Free Software# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 #
 # /home/httpd/html/adm/gpl.txt
 #
 # http://www.lon-capa.org/
 #
 
+
+
 package Apache::radiobuttonresponse;
 use strict;
 use HTML::Entities();
 use Apache::lonlocal;
 use Apache::lonnet;
+use Apache::response;
+
+my $default_bubbles_per_line = 10;
+
 
 BEGIN {
     &Apache::lonxml::register('Apache::radiobuttonresponse',('radiobuttonresponse'));
 }
 
+sub bubble_line_count {
+    my ($numfoils, $bubbles_per_line) = @_;
+    my $bubble_lines;
+    $bubble_lines = int($numfoils / $bubbles_per_line);
+    if (($numfoils % $bubbles_per_line) != 0) {
+	$bubble_lines++;
+    }
+    return $bubble_lines;
+    
+}
+
+
 sub start_radiobuttonresponse {
     my ($target,$token,$tagstack,$parstack,$parser,$safeeval,$style)=@_;
     my $result;
+
     #when in a radiobutton response use these
     &Apache::lonxml::register('Apache::radiobuttonresponse',('foilgroup','foil','conceptgroup'));
     push (@Apache::lonxml::namespace,'radiobuttonresponse');
     my $id = &Apache::response::start_response($parstack,$safeeval);
+
     %Apache::hint::radiobutton=();
     undef(%Apache::response::foilnames);
     if ($target eq 'meta') {
 	$result=&Apache::response::meta_package_write('radiobuttonresponse');
     } elsif ($target eq 'edit' ) {
-	$result.=&Apache::edit::start_table($token).
-	    '<tr><td>'.&Apache::lonxml::description($token).
-	    &Apache::loncommon::help_open_topic('Radio_Response_Problems').
-	    "</td><td>Delete:".
-	    &Apache::edit::deletelist($target,$token)
-	    ."</td><td>&nbsp".&Apache::edit::end_row()
-	    .&Apache::edit::start_spanning_row();
+	$result.=&Apache::edit::start_table($token)
+           .'<tr><td>'.&Apache::lonxml::description($token)
+           .&Apache::loncommon::help_open_topic('Radio_Response_Problems')
+           .'</td>'
+           .'<td><span class="LC_nobreak">'.&mt('Delete?').' '
+           .&Apache::edit::deletelist($target,$token)
+           .'</span></td>'
+           .'<td>&nbsp;'.&Apache::edit::end_row()
+           .&Apache::edit::start_spanning_row();
 	$result.=
 	    &Apache::edit::text_arg('Max Number Of Shown Foils:','max',
-				    $token,'4').
-	    &Apache::edit::select_arg('Randomize Foil Order','randomize',
-				      ['yes','no'],$token).
+				    $token,'4').'&nbsp;'x 3 .
+	    &Apache::edit::select_arg('Randomize Foil Order:','randomize',
+				      ['yes','no'],$token).'&nbsp;'x 3 .
+	    &Apache::edit::select_arg('Display Direction:','direction',
+				      ['vertical','horizontal'],$token).
 				      &Apache::edit::end_row().
 				      &Apache::edit::start_spanning_row()."\n";
     } elsif ($target eq 'modified') {
 	my $constructtag=&Apache::edit::get_new_args($token,$parstack,
 						     $safeeval,'max',
-						     'randomize');
+						     'randomize','direction');
 	if ($constructtag) { $result = &Apache::edit::rebuild_tag($token); }
     } elsif ($target eq 'tex') {
 	my $type=&Apache::lonxml::get_param('TeXtype',$parstack,$safeeval,
@@ -81,9 +104,15 @@ sub start_radiobuttonresponse {
 	} else {
 	    $result .= ' \renewcommand{\labelenumi}{\Alph{enumi}.}';
 	}
-	$result .= '\begin{enumerate}';
+        if($env{'form.pdfFormFields'} eq 'yes') {
+            $result .= &Apache::lonxml::print_pdf_hiddenfield('meta', $env{'user.name'}, $env{'user.domain'});
+            $result .= "\n\\\\\n\\\\\n";
+        } else {
+            $result .= '\begin{enumerate}';
+        }
     } elsif ($target eq 'analyze') {
 	my $part_id="$Apache::inputtags::part.$id";
+        $Apache::lonhomework::analyze{"$part_id.type"} = 'radiobuttonresponse';
 	push (@{ $Apache::lonhomework::analyze{"parts"} },$part_id);
     }
     return $result;
@@ -93,7 +122,9 @@ sub end_radiobuttonresponse {
     my ($target,$token,$tagstack,$parstack,$parser,$safeeval,$style)=@_;
     my $result;
     if ($target eq 'edit') { $result=&Apache::edit::end_table(); }
-    if ($target eq 'tex') { $result .= '\end{enumerate}'; }
+    if ($target eq 'tex' and $env{'form.pdfFormFields'} ne 'yes') { 
+        $result .= '\end{enumerate}'; 
+    }
     &Apache::response::end_response;
     pop @Apache::lonxml::namespace;
     &Apache::lonxml::deregister('Apache::radiobuttonresponse',('foilgroup','foil','conceptgroup'));
@@ -134,22 +165,29 @@ sub storesurvey {
     return '';
 }
 
+
 sub grade_response {
-    my ($max,$randomize)=@_;
-    #keep the random numbers the same must always call this
-    my ($answer,@whichfoils)=&whichfoils($max,$randomize);
+    my ($answer, $whichfoils, $bubbles_per_line)=@_;
+
     if ( !&Apache::response::submitted() ) { return; }
     my $response;
+    
     if ($env{'form.submitted'} eq 'scantron') {
-	$response=&Apache::response::getresponse();
+	$response = &Apache::response::getresponse(1,undef,
+						   &bubble_line_count(scalar(@{ $whichfoils}),
+								      $bubbles_per_line),
+						   $bubbles_per_line);
+
     } else {
 	$response = $env{'form.HWVAL_'.$Apache::inputtags::response['-1']};
     }
+
+
     if ( $response !~ /[0-9]+/) { return; }
     my $part=$Apache::inputtags::part;
     my $id = $Apache::inputtags::response['-1'];
     my %responsehash;
-    $responsehash{$whichfoils[$response]}=$response;
+    $responsehash{$whichfoils->[$response]}=$response;
     my $responsestr=&Apache::lonnet::hash2str(%responsehash);
     my %previous=&Apache::response::check_for_previous($responsestr,
 						       $part,$id);
@@ -170,6 +208,17 @@ sub end_foilgroup {
     my ($target,$token,$tagstack,$parstack,$parser,$safeeval,$style)=@_;
 
     my $result;
+    my $bubble_lines;
+    my $bubbles_per_line;
+    my $answer_count;
+    my $id   = $Apache::inputtags::response['-1'];
+    my $part = $Apache::inputtags::part;
+    $bubbles_per_line = 
+	&Apache::response::get_response_param($Apache::inputtags::part."_$id",
+					      'numbubbles',
+					      $default_bubbles_per_line);
+
+
     if ($target eq 'grade' || $target eq 'web' || $target eq 'answer' ||
 	$target eq 'tex' || $target eq 'analyze') {
 	my $style = $Apache::lonhomework::type;
@@ -177,36 +226,57 @@ sub end_foilgroup {
 						   $safeeval,'-2');
 	if ( $style eq 'survey'  && $target ne 'analyze') {
 	    if ($target eq 'web' || $target eq 'tex') {
-		$result=&displayallfoils($direction);
+		$result=&displayallfoils($direction, $target);
 	    } elsif ( $target eq 'answer' ) {
 		$result=&displayallanswers();
 	    } elsif ( $target eq 'grade' ) {
 		$result=&storesurvey();
 	    }
+	    $answer_count = scalar(@{$Apache::response::foilgroup{'names'}});
+
 	} else {
+
 	    my $name;
 	    my $max = &Apache::lonxml::get_param('max',$parstack,$safeeval,
 						 '-2');
 	    my $randomize = &Apache::lonxml::get_param('randomize',$parstack,
 						       $safeeval,'-2');
+	    my ($answer, @shown) = &whichfoils($max, $randomize);
+	    $answer_count = scalar(@shown);
+
 	    if ($target eq 'web' || $target eq 'tex') {
-		$result=&displayfoils($target,$max,$randomize,$direction);
+		$result=&displayfoils($target,
+				      $answer, \@shown,
+				      $direction,
+				      $bubbles_per_line);
 	    } elsif ($target eq 'answer' ) {
-		$result=&displayanswers($max,$randomize);
+		$result=&displayanswers($answer, \@shown, $bubbles_per_line);
 	    } elsif ( $target eq 'grade') {
-		&grade_response($max,$randomize);
+		&grade_response($answer, \@shown, $bubbles_per_line);
 	    }  elsif ( $target eq 'analyze') {
-		my @shown = &whichfoils($max,$randomize);
+		my $bubble_lines = &bubble_line_count($answer_count, 
+						      $bubbles_per_line);
 		&Apache::response::analyze_store_foilgroup(\@shown,
 							   ['text','value','location']);
-		my $part_id="$Apache::inputtags::part.$Apache::inputtags::response[-1]";
+		my $part_id="$part.$id";
 		push (@{ $Apache::lonhomework::analyze{"$part_id.options"} },
 		      ('true','false'));
+
 	    }
 	}
+	$Apache::lonxml::post_evaluate=0;
+    }
+    if ($target eq 'web') {
+	&Apache::response::setup_prior_tries_hash(\&format_prior_answer,
+						  [\%Apache::response::foilgroup]);
     }
     &Apache::response::poprandomnumber();
-    &Apache::lonxml::increment_counter();
+    $bubble_lines = &bubble_line_count($answer_count, $bubbles_per_line);
+    &Apache::lonxml::increment_counter($bubble_lines,
+				       "$part.$id");
+    if ($target eq 'analyze') {
+	&Apache::lonhomework::set_bubble_lines();
+    }
     return $result;
 }
 
@@ -228,12 +298,27 @@ sub getfoilcounts {
     return ($truecnt,$falsecnt);
 }
 
+sub format_prior_answer {
+    my ($mode,$answer,$other_data) = @_;
+    my $foil_data = $other_data->[0];
+    my %response = &Apache::lonnet::str2hash($answer);
+    my ($name)   = keys(%response);
+    return '<span class="LC_prior_radiobutton">'.
+	$foil_data->{$name.'.text'}.'</span>';
+
+}
+
 sub displayallfoils {
-    my ($direction)=@_;
+    my ($direction, $target)=@_;
     my $result;
     &Apache::lonxml::debug("survey style display");
-    my @names = @{ $Apache::response::foilgroup{'names'} };
+    my @names;
+    if ( $Apache::response::foilgroup{'names'} ) {
+	@names= @{ $Apache::response::foilgroup{'names'} };
+    }
+
     my $temp=0;
+    my $i   =0;
     my $id=$Apache::inputtags::response['-1'];
     my $part=$Apache::inputtags::part;
     my $lastresponse=
@@ -243,19 +328,27 @@ sub displayallfoils {
     if (&Apache::response::show_answer() ) {
 	foreach my $name (@names) {
 	    if ($Apache::response::foilgroup{$name.'.value'} ne 'unused') {
-		if ($direction eq 'horizontal') {
+		if (($direction eq 'horizontal') && ($target ne 'tex')) {
 		    $result.="<td>";
 		} else {
-		    $result.="<br />";
+		    if ($target eq 'tex') {
+			$result .= '\item \vskip -2mm ';
+		    } else {
+			$result.="<br />";
+		    }
 		}
 		if (defined($lastresponse{$name})) {
-		    $result.='<b>';
+		    if ($target eq 'tex') {
+			$result .= '}';
+		    } else {
+			$result.='<b>';
+		    }
 		}
 		$result .= $Apache::response::foilgroup{$name.'.text'};
-		if (defined($lastresponse{$name})) {
+		if (defined($lastresponse{$name}) && ($target ne 'tex')) {
 		    $result.='</b>';
 		}
-		if ($direction eq 'horizontal') { $result.="</td>"; }
+		if (($direction eq 'horizontal') && ($target ne 'tex')) { $result.="</td>"; }
 	    }
 	}
     } else {
@@ -264,22 +357,55 @@ sub displayallfoils {
 		if ($direction eq 'horizontal') {
 		    $result.="<td>";
 		} else {
-		    $result.="<br />";
+		    if ($target eq 'tex') {
+		        if($env{'form.pdfFormFields'} eq 'yes') {
+                            my $fieldname = $env{'request.symb'}.
+                                           '&part_'. $Apache::inputtags::part.
+                                           '&radiobuttonresponse'.
+                                           '&HWVAL_' . $Apache::inputtags::response['-1'];
+                            my $value = $temp;
+                            my $text = $Apache::response::foilgroup{$name.'.text'};
+                            $result .= &Apache::lonxml::print_pdf_radiobutton($fieldname,
+                                                                             $value,
+                                                                             $text)."\n";
+                        } else {
+                            $result .= '\item \vskip -2mm ';
+                        }
+                    } else {
+			$result.="<br />";
+		    }
+		}
+		if ($target eq 'tex') {
+		    if($env{'form.pdfFormFields'} ne 'yes') {
+                        $result .= '$\bigcirc$'.$Apache::response::foilgroup{$name.'.text'}.'\\\\';  #' stupid emacs
+                    }
+		    $i++;
+		} else {
+		    $result .= '<label>';
+		    $result.="<input
+                       onchange=\"javascript:setSubmittedPart('$part');\"
+                       type=\"radio\"
+                       name=\"HWVAL_$Apache::inputtags::response['-1']\"
+                       value=\"$temp\" ";
+		    if (defined($lastresponse{$name})) { $result .= 'checked="on"'; }
+		    $result .= ' />'.$Apache::response::foilgroup{$name.'.text'}.
+			'</label>';
 		}
-                $result .= '<label>';
-		$result.="<input type=\"radio\" name=\"HWVAL_$Apache::inputtags::response['-1']\" value=\"$temp\" ";
-		if (defined($lastresponse{$name})) { $result .= 'checked="on"'; }
-		$result .= '>'.$Apache::response::foilgroup{$name.'.text'}.
-                    '</label>';
 		$temp++;
-		if ($direction eq 'horizontal') { $result.="</td>"; }
+		if ($target ne 'tex') {
+		    if (($direction eq 'horizontal') && ($target ne 'tex')) { $result.="</td>"; }
+		} else {
+		    $result.='\vskip 0 mm ';
+		}
 	    }
 	}
     }
-    if ($direction eq 'horizontal') { $result.='</tr></table>'; }
+    
+    if (($direction eq 'horizontal') && ($target ne 'tex')) { $result.='</tr></table>'; }
     return $result;
 }
 
+
 sub whichfoils {
     my ($max,$randomize)=@_;
 
@@ -289,7 +415,7 @@ sub whichfoils {
     my ($truecnt,$falsecnt) = &getfoilcounts();
     my $count=0;
     # we will add in 1 of the true statements
-    if (($falsecnt+1)>$max) { $count=$max } else { $count=$falsecnt+1; }
+    if ( $max>0 && ($falsecnt+1)>$max) { $count=$max } else { $count=$falsecnt+1; $max=$count; }
     my $answer=int(&Math::Random::random_uniform() * ($count));
     &Apache::lonxml::debug("Count is $count, $answer is $answer");
     my @names;
@@ -314,7 +440,7 @@ sub whichfoils {
 	    }
 	}
 	if (!$havetrue && $Apache::lonhomework::type ne 'survey') {
-	    &Apache::lonxml::error("There are no true statements available.<br />");
+	    &Apache::lonxml::error(&mt('There are no true statements available.').'<br />');
 	}
     } else {
 	my $current=0;
@@ -375,7 +501,7 @@ sub whichfoils {
 	my $dosplice=1;
 	if ($notrue && $Apache::lonhomework::type ne 'survey') {
 	    $dosplice=0;
-	    &Apache::lonxml::error("There are no true statements available.<br />");
+	    &Apache::lonxml::error(&mt('There are no true statements available.').'<br />');
 	}
 	#insert the true statement, keeping track of where it wants to be
 	if ($Apache::response::foilgroup{$truename.'.location'} eq 'top' && $dosplice) {
@@ -417,10 +543,9 @@ sub whichfoils {
 }
 
 sub displayfoils {
-    my ($target,$max,$randomize,$direction)=@_;
+    my ($target,$answer,$whichfoils,$direction, $bubbles_per_line)=@_;
     my $result;
 
-    my ($answer,@whichfoils)=&whichfoils($max,$randomize);
     my $part=$Apache::inputtags::part;
     my $solved=$Apache::lonhomework::history{"resource.$part.solved"};
     if ( ($target ne 'tex') &&
@@ -430,7 +555,7 @@ sub displayfoils {
 		$result.='<table><tr>';
 	    }
 	}
-	foreach my $name (@whichfoils) {
+	foreach my $name (@{ $whichfoils }) {
 	    if ($direction eq 'horizontal') {
 		if ($target ne 'tex') { $result.='<td>'; }
 	    }
@@ -440,9 +565,13 @@ sub displayfoils {
 		$result.='\item \vskip -2 mm  ';
 	    }
 	    if ($Apache::response::foilgroup{$name.'.value'} eq 'true') { 
-		if ($target ne 'tex') { $result.='Correct:<b>'; } else { $result.='Correct: \textbf{';}
+		if ($target ne 'tex') {
+                    $result.=&mt('Correct:').'<b>';
+                } else {
+                    $result.=&mt('Correct:').' \textbf{';
+                }
 	    } else {
-		$result.='Incorrect:';
+		$result.=&mt('Incorrect:');
 	    }
 	    if ($target eq 'web') { $result.="<label>"; }
 	    $result.=$Apache::response::foilgroup{$name.'.text'};
@@ -462,6 +591,8 @@ sub displayfoils {
     } else {
 	my @alphabet = ('A'..'Z');
 	my $i = 0;
+	my $bubble_number = 0;
+	my $line = 0;
 	my $temp=0;  
 	my $id=$Apache::inputtags::response['-1'];
 	my $part=$Apache::inputtags::part;
@@ -470,7 +601,7 @@ sub displayfoils {
 	if ($target ne 'tex' && $direction eq 'horizontal') {
 	    $result.="<table><tr>";
 	}
-	foreach my $name (@whichfoils) {
+	foreach my $name (@{ $whichfoils }) {
 	    if ($target ne 'tex') {
 		if ($direction eq 'horizontal') {
 		    $result.="<td>"; 
@@ -480,16 +611,38 @@ sub displayfoils {
 	    }
 	    if ($target ne 'tex') { 
                 $result.= '<label>';
-		$result.="<input type=\"radio\" name=\"HWVAL_$Apache::inputtags::response['-1']\" value=\"$temp\" ";
+		$result.=
+		    "<input type=\"radio\"
+                            onchange=\"javascript:setSubmittedPart('$part');\"
+                            name=\"HWVAL_$Apache::inputtags::response['-1']\"
+                            value=\"$temp\" ";
 		if (defined($lastresponse{$name})) { $result .= 'checked="on"'; }
-		$result .= '>'.$Apache::response::foilgroup{$name.'.text'}."</label>";
+		$result .= ' />'.$Apache::response::foilgroup{$name.'.text'}."</label>";
 	    } else {
 		if ($Apache::lonhomework::type eq 'exam') {
+		    if($bubble_number >= $bubbles_per_line) {
+			$line++;
+			$i = 0;
+			$bubble_number = 0;
+			$result.='\item[\textbf{'.($Apache::lonxml::counter+$line).'}.]';
+		    }
 		    $result .= '{\small \textbf{'.$alphabet[$i].'}}$\bigcirc$'.$Apache::response::foilgroup{$name.'.text'}.'\\\\';  #' stupid emacs
 		    $i++;
+		    $bubble_number++;
 		} else {
-		    $result .= '\vspace*{-2 mm}\item '.$Apache::response::foilgroup{$name.'.text'};
-		}
+		      if($env{'form.pdfFormFields'} eq 'yes') {
+
+                         my $fieldname = $env{'request.symb'}.
+                                         '&part_'. $Apache::inputtags::part.
+                                         '&radiobuttonresponse'.
+                                         '&HWVAL_' . $Apache::inputtags::response['-1'];
+                         my $value = $temp;
+                         my $text = $Apache::response::foilgroup{$name.'.text'};
+                         $result .= &Apache::lonxml::print_pdf_radiobutton($fieldname, $value, $text).'\newline'."\n";
+                     } else { 
+                         $result .= '\vspace*{-2 mm}\item '.$Apache::response::foilgroup{$name.'.text'};
+                     }
+                }
 	    }
 	    if ($target ne 'tex' && $direction eq 'horizontal') {
 		$result.="</td>"; 
@@ -505,8 +658,10 @@ sub displayfoils {
 }
 
 sub displayallanswers {
-    my @names = @{ $Apache::response::foilgroup{'names'} };
-  
+    my @names;
+    if ( $Apache::response::foilgroup{'names'} ) {
+	@names= @{ $Apache::response::foilgroup{'names'} };
+    }
     my $result=&Apache::response::answer_header('radiobuttonresponse');
     foreach my $name (@names) {
 	$result.=&Apache::response::answer_part('radiobuttonresponse',
@@ -517,13 +672,23 @@ sub displayallanswers {
 }
 
 sub displayanswers {
-    my ($max,$randomize)=@_;
-    my ($answer,@whichopt) = &whichfoils($max,$randomize);
-    my $result=&Apache::response::answer_header('radiobuttonresponse');
-    foreach my $name (@whichopt) {
+    my ($answer, $whichopt, $bubbles_per_line)=@_;
+    my $result;
+
+    if ($Apache::lonhomework::type eq 'exam') {
+	my $line = int($answer/$bubbles_per_line);
+	my $correct = ('A'..'Z')[$answer%$bubbles_per_line];
+	$result .= &Apache::response::answer_header('radiobuttonresponse',
+						    $line);
+	$result .= &Apache::response::answer_part('radiobuttonresponse',
+						  $correct);
+    } else {
+	$result .= &Apache::response::answer_header('radiobuttonresponse');
+    }
+    foreach my $name (@{ $whichopt }) {
 	$result.=&Apache::response::answer_part('radiobuttonresponse',
-						$Apache::response::foilgroup{$name.'.value'})
-	}
+						$Apache::response::foilgroup{$name.'.value'});
+    }
     $result.=&Apache::response::answer_footer('radiobuttonresponse');
     return $result;
 }
@@ -608,11 +773,11 @@ sub end_foil {
 	if ($value ne 'unused') {
 	    my $name = &Apache::lonxml::get_param('name',$parstack,$safeeval);
 	    if ($name eq "") {
-		&Apache::lonxml::warning("Foils without names exist. This can cause problems to malfunction.");
+		&Apache::lonxml::warning(&mt('Foils without names exist. This can cause problems to malfunction.'));
 		$name=$Apache::lonxml::curdepth;
 	    }
 	    if (defined($Apache::response::foilnames{$name})) {
-		&Apache::lonxml::error(&mt("Foil name <b><tt>[_1]</tt></b> appears more than once. Foil names need to be unique.",$name));
+		&Apache::lonxml::error(&mt('Foil name [_1] appears more than once. Foil names need to be unique.','<b><tt>'.$name.'</tt></b>'));
 	    }
 	    $Apache::response::foilnames{$name}++;
 	    my $location =&Apache::lonxml::get_param('location',$parstack,
@@ -643,4 +808,87 @@ sub insert_foil {
 }
 1;
 __END__
+
+
+
+=head1 NAME
+
+Apache::radiobuttonresponse
+
+=head1 SYNOPSIS
+
+Handles multiple-choice style responses.
+
+This is part of the LearningOnline Network with CAPA project
+described at http://www.lon-capa.org.
+
+=head1 SUBROUTINES
+
+=over
+
+=item start_radiobuttonresponse()
+
+=item bubble_line_count()
+
+=item end_radiobuttonresponse()
+
+=item start_foilgroup()
+
+=item storesurvey()
+
+=item grade_response()
+
+=item end_foilgroup()
+
+=item getfoilcounts()
+
+=item format_prior_answer()
+
+=item displayallfoils()
+
+=item &whichfoils($max,$randomize)
+
+Randomizes the list of foils.
+Respects
+  - each foils desire to be randomized
+  - the existance of Concept groups of foils (select 1 foil from each)
+  - and selects a single correct statement from all possilble true statments
+  - and limits it to a toal of $max foils
+
+WARNING: this routine uses the random number generator, it should only
+be called once per target, otherwise it can cause randomness changes in
+homework problems.
+
+Arguments
+  $max - maximum number of foils to select (including the true one)
+         (so a max of 5 is: 1 true, 4 false)
+
+  $randomize - whether to randomize the listing of foils, by default
+               will randomize, only if randomize is 'no' will it not
+
+Returns
+  $answer - location in the array of the correct answer
+  @foils  - array of foil names in to display order
+
+=item displayfoils()
+
+=item displayallanswers()
+
+=item displayanswers()
+
+=item start_conceptgroup()
+
+=item end_conceptgroup()
+
+=item insert_conceptgroup()
+
+=item start_foil()
+
+=item end_foil()
+
+=item insert_foil()
+
+=back
+
+=cut