Restructire the POD of macros (contexts)

macros/contexts/contextABCD.pl

@@ -9,6 +9,8 @@ =head1 DESCRIPTION
 for matching problems (where you match against A, B, C, D,
 and so on).
 
+=head1 SYNOPSIS
+
 There are two contexts defined here,
 
     Context("ABCD");

macros/contexts/contextAlternateDecimal.pl

@@ -1,7 +1,7 @@
 
 =head1 NAME
 
-C<Context("AlternateDecimal")> - Provides a context that allows the
+contextAlternateDecimal.pl - Provides a context that allows the
 entry of decimal numbers using a comma for the decimal indicator
 rather than a dot (e.g., C<3,14159> rather than C<3.14159>).
 
@@ -13,11 +13,7 @@ =head1 DESCRIPTION
 the other form produces an error message when used.  You can also
 force the display of numbers to use one or the other form.
 
-=head1 USAGE
-
-To use this file, first load it into your problem, then select the
-context that you wish to use.  There are three pre-defined contexts,
-C<AlternateDecimal>, C<AlternateDecimal-Only>, and
+There are three pre-defined contexts, C<AlternateDecimal>, C<AlternateDecimal-Only>, and
 C<AlternateDecimal-Warning>.  The first allows both the standard and
 alternate forms to be used, the second allows only the alternate form,
 and the third allows only the standard form, but recognizes the
@@ -82,7 +78,7 @@ =head1 USAGE
 numebrs would be displayed in standard form.
 
 
-=head1 LISTS IN ALTERNATE FORMAT
+=head2 LISTS IN ALTERNATE FORMAT
 
 Because the alternate format allows numbers to be entered using commas
 rather than periods, this makes the formation of lists harder.  For
@@ -107,16 +103,16 @@ =head1 LISTS IN ALTERNATE FORMAT
 must be a list separator.
 
 
-=head1 SETTING THE ALTERNATE FORM AS THE DEFAULT
+=head2 SETTING THE ALTERNATE FORM AS THE DEFAULT
 
 If you want to force existing problems to allow (or force, or warn about)
 the alternate format instead, then create a file named
 C<parserCustomization.pl> in your course's C<templates/macros>
 directory, and enter the following in it:
 
     loadMacros("contextAlternateDecimal.pl");
-        context::AlternateDecimal->Default("either","either");
-        Context("Numeric");
+    context::AlternateDecimal->Default("either","either");
+    Context("Numeric");
 
 This will alter all the standard contexts to allow students to enter
 numbers in either format, and will display them using the form that
@@ -125,17 +121,17 @@ =head1 SETTING THE ALTERNATE FORM AS THE DEFAULT
 You could also do
 
     loadMacros("contextAlternateDecimal.pl");
-        context::AlternateDecimal->Default(".",".");
-        Context("Numeric");
+    context::AlternateDecimal->Default(".",".");
+    Context("Numeric");
 
 to cause a warning message to appear when students enter the alternate
 format.
 
 If you want to force students to enter the alternate format, use
 
     loadMacros("contextAlternateDecimal.pl");
-        context::AlternateDecimal->Default(",",",");
-        Context("Numeric");
+    context::AlternateDecimal->Default(",",",");
+    Context("Numeric");
 
 This will force the display of all numbers into the alternate form (so
 even the ones created in the problem using standard form will show
@@ -149,14 +145,10 @@ =head1 SETTING THE ALTERNATE FORM AS THE DEFAULT
 
 =cut
 
-###########################################################
-
 loadMacros("MathObjects.pl");
 
 sub _contextAlternateDecimal_init { context::AlternateDecimal->Init }
 
-###########################################################
-
 package context::AlternateDecimal;
 
 #

macros/contexts/contextAlternateIntervals.pl

@@ -1,11 +1,10 @@
 
 =head1 NAME
 
-C<Context("AlternateIntervals")> - Provides a context that allows the
+contextAlternateIntervals.pl - Provides a context that allows the
 entry of intervals using reversed bracket notation for open endpoints
 (e.g., C<]a,b[> rather than C<(a,b)> for an open interval).
 
-
 =head1 DESCRIPTION
 
 This macro file defines contexts in which open intervals can be
@@ -14,9 +13,6 @@ =head1 DESCRIPTION
 form produces an error message when used.  You can also force the
 display of intervals to use one or the other form.
 
-
-=head1 USAGE
-
 To use this file, first load it into your problem, then select the
 context that you wish to use.  There are three pre-defined contexts,
 C<AlternateIntervals>, C<AlternateIntervals-Only>, and
@@ -83,7 +79,7 @@ =head1 USAGE
 would allow students to enter intervals in either format, but all
 intervals would be displayed in standard form.
 
-=head1 Setting the alternate form as the default
+=head2 Setting the alternate form as the default
 
 If you want to force existing problems that use the Interval context
 to use one of the alternate contexts instead, then create a file named
@@ -122,14 +118,10 @@ =head1 Setting the alternate form as the default
 
 =cut
 
-##########################################################################
-
 loadMacros("MathObjects.pl");
 
 sub _contextAlternateIntervals_init { context::AlternateIntervals->Init }
 
-##########################################################################
-
 package context::AlternateIntervals;
 
 #  Create the AlternateIntervals contexts
@@ -176,23 +168,22 @@ sub Enable {
 	$context->lists->set("Interval" => { class => "context::AlternateIntervals::Parser::Interval" });
 }
 
-#
 #  Sets the default Interval context to use alternate decimals.  The
 #  two arguments determine the values for the enterIntervals and
 #  displayIntervals flags.  If enterIntervals is "alternate", then
 #  student answers must use the alternate format for entering
 #  intervals (though professors can use either).
-#
+
 sub Default {
 	my $self    = shift;
 	my $enter   = shift || "either";
 	my $display = shift || "either";
 	my $cmp     = ($enter eq "alternate");
 	$enter = "either" if $cmp;
-	#
+
 	#  This adds the names from InequalitySetBuilder, but we need a better way to
 	#  link into contexts as they are created and copied.
-	#
+
 	my @InequalitySetBuilder = (
 		"SetBuilder::",                   "InequalitySetBuilder::",
 		"InequalitySetBuilderInterval::", "InequalitySetBuilderUnion::",
@@ -211,8 +202,6 @@ sub Default {
 	main::Context(main::Context()->{name});
 }
 
-##########################################################################
-
 package context::AlternateIntervals::Formula;
 our @ISA = ('Value::Formula');
 
@@ -245,13 +234,12 @@ sub Open {
 	$self->push($item);
 }
 
-#
 #  We need to modify the test for formInterval to NOT check the number
 #  of entries so that better error messages are produced, and to handle
 #  multiple close delimiters.  These are both in teh "operand" branch,
 #  so do the original for all the choices, and copy that branch here,
 #  with our modifications.
-#
+
 sub Close {
 	my ($self, $type, $ref) = @_;
 	$self->{ref} = $ref;
@@ -306,8 +294,6 @@ sub Close {
 
 sub class {'Formula'}
 
-##########################################################################
-
 package context::AlternateIntervals::Interval;
 our @ISA = ('Value::Interval');
 

macros/contexts/contextArbitraryString.pl

@@ -4,12 +4,7 @@ =head1 NAME
 contextArbitraryString.pl - Implements a context in which the student's answer is treated as a
 literal string, and not parsed further.
 
-=head1 DESCRIPTION
-
-Implements a context in which the student's answer is treated as a
-literal string, and not parsed further.  The real answer checking
-should be performed in a custom checker passed to the answer
-string's C<cmp()> method.  E.g.,
+=head1 SYNOPSIS
 
     loadMacros("contextArbitraryString.pl");
     Context("ArbitraryString");
@@ -26,6 +21,13 @@ =head1 DESCRIPTION
         return $score;
     }));
 
+=head1 DESCRIPTION
+
+Implements a context in which the student's answer is treated as a
+literal string, and not parsed further.  The real answer checking
+should be performed in a custom checker passed to the answer
+string's C<cmp()> method.
+
 The default checker is essentially that given above, so if you want
 the student answer to match the correct one exactly (spacing and
 case are significant), then you don't have to use a custom checker.
@@ -79,16 +81,14 @@ sub _contextArbitraryString_init {
 	$context->update;
 }
 
-#
 #  Handle creating String() constants
-#
+
 package context::ArbitraryString;
 sub new { shift; main::Compute(@_) }
 
-#
 #  Replacement for Parser::String that uses the original string verbatim
 #  (but replaces \r and \r\n by \n to handle different browser multiline input)
-#
+
 package context::ArbitraryString::Parser::String;
 our @ISA = ('Parser::String');
 
@@ -100,16 +100,14 @@ sub new {
 	$self->SUPER::new($equation, $value, $ref);
 }
 
-#
 #  Replacement for Value::String that creates preview strings
 #  that work for multiline input
-#
+
 package context::ArbitraryString::Value::String;
 our @ISA = ("Value::String");
 
-#
 #  Mark a multi-line string to be displayed verbatim in TeX
-#
+
 sub quoteTeX {
 	my $self = shift;
 	my $s    = shift;
@@ -119,9 +117,8 @@ sub quoteTeX {
 	"\\begin{array}{l}" . join("\\\\ ", @tex) . "\\end{array}";
 }
 
-#
 #  Quote HTML special characters
-#
+
 sub quoteHTML {
 	my $self = shift;
 	my $s    = $self->SUPER::quoteHTML(shift);
@@ -130,10 +127,8 @@ sub quoteHTML {
 	return $s;
 }
 
-#
-#  Adjust preview and strings so they display
-#  multiline answers properly.
-#
+#  Adjust preview and strings so they display multiline answers properly.
+
 sub cmp_preprocess {
 	my $self = shift;
 	my $ans  = shift;

macros/contexts/contextBaseN.pl

@@ -10,11 +10,9 @@ =head1 DESCRIPTION
 greater than or equal to 2.  The numbers will be stored internally in decimal, though parsed
 and shown in the chosen base.
 
-In addition, basic integer arithemetic (+,-,*,/,%,^) are available for these numbers.
-Division is defined in an integer sense.
-
 The original purpose for this is simple conversion and operations in another base, however
-it is not limited to this.
+it is not limited to this. In addition, basic integer arithemetic (+,-,*,/,%,^) are available for these numbers.
+Division is defined in an integer sense.
 
 To use a non-decimal base MathObject, first load the contextBaseN.pl file:
 
@@ -114,12 +112,14 @@ sub Init {
 	$context->parens->undefine('|', '{', '[');
 }
 
+=head1 FUNCTIONS
+
 =head2 convertBase
 
 The function C<convertBase(value, opts)> converts the value from or to other bases depending on the options
 in C<opts>.  The input C<value> is a positive number or string version of a positive number in some base.
 
-=head3 options
+=head3 Options
 
 =over
 
@@ -302,9 +302,8 @@ sub eval {
 package context::BaseN::BOP::modulo;
 our @ISA = ('Parser::BOP::divide');
 
-#
 #  Do the division.
-#
+
 sub _eval { $_[1] % $_[2] }
 
 #  A replacement for Value::Real that handles non-decimal integers