--- loncom/homework/radiobuttonresponse.pm 2004/03/31 05:23:59 1.87
+++ loncom/homework/radiobuttonresponse.pm 2010/12/19 04:24:29 1.147
@@ -1,7 +1,7 @@
# The LearningOnline Network with CAPA
# mutliple choice style responses
#
-# $Id: radiobuttonresponse.pm,v 1.87 2004/03/31 05:23:59 albertel Exp $
+# $Id: radiobuttonresponse.pm,v 1.147 2010/12/19 04:24:29 raeburn Exp $
#
# Copyright Michigan State University Board of Trustees
#
@@ -18,53 +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).
- '
'.&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').' 'x 3 .
+ &Apache::edit::select_arg('Randomize Foil Order:','randomize',
+ ['yes','no'],$token).' '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,
@@ -77,10 +101,17 @@ sub start_radiobuttonresponse {
$result .= ' \renewcommand{\labelenumi}{\alph{enumi}.}';
} elsif ($type eq 'i') {
$result .= ' \renewcommand{\labelenumi}{\roman{enumi}.}';
+ } else {
+ $result .= ' \renewcommand{\labelenumi}{\Alph{enumi}.}';
}
- $result .= '\begin{enumerate}';
+ if($env{'form.pdfFormFields'} eq 'yes' && $Apache::inputtags::status[-1] eq 'CAN_ANSWER') {
+ $result .= '\begin{itemize}';
+ } 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;
@@ -90,7 +121,13 @@ 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' ) {
+ if($env{'form.pdfFormFields'} eq 'yes' and $Apache::inputtags::status[-1] eq 'CAN_ANSWER') {
+ $result .= '\end{itemize}';
+ } else {
+ $result .= '\end{enumerate}';
+ }
+ }
&Apache::response::end_response;
pop @Apache::lonxml::namespace;
&Apache::lonxml::deregister('Apache::radiobuttonresponse',('foilgroup','foil','conceptgroup'));
@@ -104,7 +141,7 @@ sub start_foilgroup {
my $result;
%Apache::response::foilgroup=();
$Apache::radiobuttonresponse::conceptgroup=0;
- &Apache::response::setrandomnumber();
+ &Apache::response::pushrandomnumber(undef,$target);
if ($target eq 'tex' && $Apache::lonhomework::type eq 'exam') {
$result.='\item[\textbf{'.$Apache::lonxml::counter.'}.]';
}
@@ -112,36 +149,58 @@ sub start_foilgroup {
}
sub storesurvey {
- if ( !defined($ENV{'form.submitted'})) { return ''; }
- my $response = $ENV{'form.HWVAL_'.$Apache::inputtags::response['-1']};
+ my ($style) = @_;
+ if ( !&Apache::response::submitted() ) { return ''; }
+ my $response = $env{'form.HWVAL_'.$Apache::inputtags::response['-1']};
&Apache::lonxml::debug("Here I am!:$response:");
if ( $response !~ /[0-9]+/) { return ''; }
+ my $part = $Apache::inputtags::part;
my $id = $Apache::inputtags::response['-1'];
my @whichfoils=@{ $Apache::response::foilgroup{'names'} };
my %responsehash;
$responsehash{$whichfoils[$response]}=$response;
- $Apache::lonhomework::results{"resource.$Apache::inputtags::part.$id.submission"}=&Apache::lonnet::hash2str(%responsehash);
- $Apache::lonhomework::results{"resource.$Apache::inputtags::part.$id.awarddetail"}='SUBMITTED';
+ my $responsestr=&Apache::lonnet::hash2str(%responsehash);
+ $Apache::lonhomework::results{"resource.$part.$id.submission"}=
+ $responsestr;
+ my %previous=&Apache::response::check_for_previous($responsestr,$part,$id);
+ my $ad;
+ if ($style eq 'anonsurvey') {
+ $ad=$Apache::lonhomework::results{"resource.$part.$id.awarddetail"}='ANONYMOUS';
+ } elsif ($style eq 'anonsurveycred') {
+ $ad=$Apache::lonhomework::results{"resource.$part.$id.awarddetail"}='ANONYMOUS_CREDIT';
+ } elsif ($style eq 'surveycred') {
+ $ad=$Apache::lonhomework::results{"resource.$part.$id.awarddetail"}='SUBMITTED_CREDIT';
+ } else {
+ $ad=$Apache::lonhomework::results{"resource.$part.$id.awarddetail"}='SUBMITTED';
+ }
+ &Apache::response::handle_previous(\%previous,$ad);
&Apache::lonxml::debug("submitted a $response \n");
return '';
}
+
sub grade_response {
- my ($max,$randomize)=@_;
- #keep the random numbers the same must always call this
- my ($answer,@whichfoils)=&whichfoils($max,$randomize);
- if (!defined($ENV{'form.submitted'})) { return; }
+ my ($answer, $whichfoils, $bubbles_per_line)=@_;
+
+ if ( !&Apache::response::submitted() ) { return; }
my $response;
- if ($ENV{'form.submitted'} eq 'scantron') {
- $response=&Apache::response::getresponse();
+
+ if ($env{'form.submitted'} eq 'scantron') {
+ $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']};
+ $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);
@@ -162,40 +221,77 @@ 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;
- if ( $style eq 'survey' && $target ne 'analyze') {
+ my $direction = &Apache::lonxml::get_param('direction',$parstack,
+ $safeeval,'-2');
+ if ( (($style eq 'survey') || ($style eq 'surveycred') ||
+ ($style eq 'anonsurvey') || ($style eq 'anonsurveycred'))
+ && ($target ne 'analyze')) {
if ($target eq 'web' || $target eq 'tex') {
- $result=&displayallfoils();
+ $result=&displayallfoils($direction, $target);
} elsif ( $target eq 'answer' ) {
$result=&displayallanswers();
} elsif ( $target eq 'grade' ) {
- $result=&storesurvey();
+ $result=&storesurvey($style);
}
+ $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);
+ $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();
+ $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();
}
- &Apache::lonxml::increment_counter();
return $result;
}
@@ -217,42 +313,124 @@ 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 ''.
+ $foil_data->{$name.'.text'}.'';
+
+}
+
sub displayallfoils {
+ 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=
- $Apache::lonhomework::history{"resource.$part.$id.submission"};
+ my $lastresponse;
+ my ($lastresponse,$newvariation,$showanswer);
+ if ((($Apache::lonhomework::history{"resource.$part.type"} eq 'randomizetry') ||
+ ($Apache::lonhomework::type eq 'randomizetry')) &&
+ ($Apache::inputtags::status[-1] eq 'CAN_ANSWER')) {
+ if ($env{'form.'.$part.'.rndseed'} ne
+ $Apache::lonhomework::history{"resource.$part.rndseed"}) {
+ $newvariation = 1;
+ }
+ }
+ $showanswer = &Apache::response::show_answer();
+ unless ((($Apache::lonhomework::history{"resource.$part.type"} eq 'anonsurvey') || ($Apache::lonhomework::history{"resource.$part.type"} eq 'anonsurveycred')) && (defined($env{'form.grade_symb'})) ||
+ ($newvariation && !$showanswer)) {
+ $lastresponse =
+ $Apache::lonhomework::history{"resource.$part.$id.submission"};
+ }
+ if ($direction eq 'horizontal') { $result.='
'; }
my %lastresponse=&Apache::lonnet::str2hash($lastresponse);
- if (&Apache::response::show_answer() ) {
+ if ($showanswer) {
foreach my $name (@names) {
if ($Apache::response::foilgroup{$name.'.value'} ne 'unused') {
- $result.=" ";
+ if (($direction eq 'horizontal') && ($target ne 'tex')) {
+ $result.="
"; }
+ } else {
+ $result.='\vskip 0 mm ';
+ }
}
}
}
+
+ if (($direction eq 'horizontal') && ($target ne 'tex')) { $result.='
'; }
return $result;
}
+
sub whichfoils {
my ($max,$randomize)=@_;
@@ -262,7 +440,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;
@@ -286,6 +464,13 @@ sub whichfoils {
&Apache::lonxml::error(&HTML::Entities::encode("No valid value assigned ($Apache::response::foilgroup{$name.'.value'}) for foil $name in ",'<>&"'));
}
}
+ if ((!$havetrue) &&
+ ($Apache::lonhomework::type ne 'survey') &&
+ ($Apache::lonhomework::type ne 'surveycred') &&
+ ($Apache::lonhomework::type ne 'anonsurvey') &&
+ ($Apache::lonhomework::type ne 'anonsurveycred')) {
+ &Apache::lonxml::error(&mt('There are no true statements available.').' ');
+ }
} else {
my $current=0;
&Apache::lonhomework::showhash(%Apache::response::foilgroup);
@@ -343,9 +528,13 @@ sub whichfoils {
&Apache::lonxml::debug("Answer wants $answer");
my $truename=$truelist[$whichtrue];
my $dosplice=1;
- if ($notrue && $Apache::lonhomework::type ne 'survey') {
+ if (($notrue) &&
+ ($Apache::lonhomework::type ne 'survey') &&
+ ($Apache::lonhomework::type ne 'surveycred') &&
+ ($Apache::lonhomework::type ne 'anonsurvey') &&
+ ($Apache::lonhomework::type ne 'anonsurveycred')) {
$dosplice=0;
- &Apache::lonxml::error("There are no true statements available. ");
+ &Apache::lonxml::error(&mt('There are no true statements available.').' ');
}
#insert the true statement, keeping track of where it wants to be
if ($Apache::response::foilgroup{$truename.'.location'} eq 'top' && $dosplice) {
@@ -387,65 +576,132 @@ sub whichfoils {
}
sub displayfoils {
- my ($target,$max,$randomize)=@_;
+ 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') &&
&Apache::response::show_answer() ) {
- foreach my $name (@whichfoils) {
+ if ($direction eq 'horizontal') {
+ if ($target ne 'tex') {
+ $result.='
';
+ }
+ }
+ foreach my $name (@{ $whichfoils }) {
+ if ($direction eq 'horizontal') {
+ if ($target ne 'tex') { $result.='
'; }
+ }
if ($target ne 'tex') {
$result.=" ";
} else {
$result.='\item \vskip -2 mm ';
}
if ($Apache::response::foilgroup{$name.'.value'} eq 'true') {
- if ($target ne 'tex') { $result.='Correct:'; } else { $result.='Correct: \textbf{';}
+ if ($target ne 'tex') {
+ $result.=&mt('Correct:').'';
+ } else {
+ $result.=&mt('Correct:').' \textbf{';
+ }
} else {
- $result.='Incorrect:';
- }
- if ($target ne 'tex') {
- $result.=$Apache::response::foilgroup{$name.'.text'}."\n";
- } else {
- $result.=$Apache::response::foilgroup{$name.'.text'};
+ $result.=&mt('Incorrect:');
}
+ if ($target eq 'web') { $result.=""; }
if ($Apache::response::foilgroup{$name.'.value'} eq 'true') {
if ($target ne 'tex') { $result.='';} else {$result.='}';}
}
+ if ($direction eq 'horizontal') {
+ if ($target ne 'tex') { $result.='
'; }
+ }
+ }
+ if ($direction eq 'horizontal') {
+ if ($target ne 'tex') {
+ $result.='
';
+ }
}
} 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;
- my $lastresponse=$Apache::lonhomework::history{"resource.$part.$id.submission"};
+ my ($lastresponse,$newvariation);
+ if ((($Apache::lonhomework::history{"resource.$part.type"} eq 'randomizetry') ||
+ ($Apache::lonhomework::type eq 'randomizetry')) &&
+ ($Apache::inputtags::status[-1] eq 'CAN_ANSWER')) {
+ if ($env{'form.'.$part.'.rndseed'} ne
+ $Apache::lonhomework::history{"resource.$part.rndseed"}) {
+ $newvariation = 1;
+ }
+ }
+ unless ($newvariation) {
+ $lastresponse=$Apache::lonhomework::history{"resource.$part.$id.submission"};
+ }
my %lastresponse=&Apache::lonnet::str2hash($lastresponse);
- foreach my $name (@whichfoils) {
+ if ($target ne 'tex' && $direction eq 'horizontal') {
+ $result.="
";
+ }
+ foreach my $name (@{ $whichfoils }) {
if ($target ne 'tex') {
- $result.=" \n";
+ if ($direction eq 'horizontal') {
+ $result.="
";
}
$temp++;
}
+ if ($target ne 'tex' && $direction eq 'horizontal') {
+ $result.="
";
+ }
}
- if ($target ne 'tex') { $result.=" "; } else { $result.='\vskip 0 mm '; }
+ if ($target ne 'tex') { if ($direction ne 'horizontal') { $result.=" ";} } else { $result.='\vskip 0 mm '; }
return $result;
}
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',
@@ -456,13 +712,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;
}
@@ -510,6 +776,9 @@ sub start_foil {
my $result='';
if ($target eq 'web' || $target eq 'tex' || $target eq 'analyze') {
&Apache::lonxml::startredirection;
+ if ($target eq 'analyze') {
+ &Apache::response::check_if_computed($token,$parstack,$safeeval,'value');
+ }
} elsif ($target eq 'edit') {
$result=&Apache::edit::tag_start($target,$token);
$result.=&Apache::edit::text_arg('Name:','name',$token);
@@ -543,9 +812,12 @@ sub end_foil {
my $value = &Apache::lonxml::get_param('value',$parstack,$safeeval);
if ($value ne 'unused') {
my $name = &Apache::lonxml::get_param('name',$parstack,$safeeval);
- if (!$name) { $name=$Apache::lonxml::curdepth; }
+ if ($name eq "") {
+ &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 [_1] 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.',''.$name.''));
}
$Apache::response::foilnames{$name}++;
my $location =&Apache::lonxml::get_param('location',$parstack,
@@ -576,4 +848,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