Merge pull request #1271 from Alex-Jordan/restructure-pod-macros-contexts

Restructire the POD of macros (contexts)

Author: somiaj

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

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

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.
@@ -131,8 +133,7 @@ sub quoteHTML {
 }
 
 #
-#  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;

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
 

macros/contexts/contextBoolean.pl

@@ -5,6 +5,10 @@ =head1 NAME
 
 =head1 DESCRIPTION
 
+This macro provides functionality for handling boolean expressions.
+
+=head1 SYNOPSIS
+
 Load this file:
 
     loadMacros('contextBoolean.pl');
@@ -13,7 +17,7 @@ =head1 DESCRIPTION
 
     Context('Boolean');
 
-=head2 CONSTANTS
+=head1 CONSTANTS
 
 This constant recognizes two constants by default, C<T> and C<F>. The following are all equivalent:
 
@@ -22,22 +26,22 @@ =head2 CONSTANTS
     $T = Context()->T;
     $T = context::Boolean->T;
 
-=head2 VARIABLES
+=head1 VARIABLES
 
 By default, this context has two variables, C<p> and C<q>. More variables can be added through the usual
 means of modifying context:
 
     Context->variables->add( r => 'Boolean' );
 
-=head2 OPERATORS
+=head1 OPERATORS
 
 Changing the LaTeX representations of the boolean operators is handled through the operators C<or>, C<and>,
 C<xor>, and C<not>. Note the extra space following the LaTeX command.
 
     Context->operators->set( not => { TeX => '\neg ' } );
 
 
-=head3 Aliases and Alternatives
+=head2 Aliases and Alternatives
 
 Modifications to the operators should be applied to the string versions of each operator: 'or', 'xor', 'and',
 and 'not'; rather than to any of the following aliases or alternatives.
@@ -66,7 +70,7 @@ =head3 Aliases and Alternatives
 
 =back
 
-=head2 OPERATOR PRECEDENCE
+=head1 OPERATOR PRECEDENCE
 
 =over
 
@@ -86,7 +90,7 @@ =head2 OPERATOR PRECEDENCE
 
 =back
 
-=head2 REDUCTION
+=head1 REDUCTION RULES
 
 The context also handles C<reduceConstants> with the following reduction rules:
 
@@ -114,7 +118,7 @@ =head2 REDUCTION
 
 =back
 
-=head2 COMPARISON
+=head1 COMPARISON
 
 Boolean Formula objects are considered equal whenever the two expressions generate the same truth table.
 

macros/contexts/contextComplexExtras.pl

@@ -1,7 +1,7 @@
 
 =head1 NAME
 
-F<contextCopmlesExtras.pl> - Add conjugation to Complex contexts, and
+contextComplexExtras.pl - Add conjugation to Complex contexts, and
 transpose, conjugate transpose, trace, and determinant to Complex-Matrix context.
 
 =head1 DESCRIPTION
@@ -11,6 +11,8 @@ =head1 DESCRIPTION
 answers in the Complex-Matrix context, and adds conjugation to all
 Complex contexts.
 
+=head1 SYNOPSIS
+
 Conjugation is represented by C<~>, as in C<~z> or C<~M> to conjugate
 a complex number or complex matrix.  This can be used in both PG code
 as well as student answers.  The transpose is represented by C<^T>, as
@@ -180,10 +182,8 @@ sub _eval {
 }
 
 #
-#  Check for a single Matrix-valued argument
-#  Then promote it to a Matrix (does error checking)
-#    and call the routine from Value package (after
-#    converting "tr" to "trace")
+#  Check for a single Matrix-valued argument. Then promote it to a Matrix (does error checking)
+#    and call the routine from Value package (after converting "tr" to "trace")
 #
 sub _call {
 	my $self = shift;
@@ -195,3 +195,5 @@ sub _call {
 	$name = "trace" if $name eq "tr";    # method of Matrix is trace not tr
 	$self->Package("Matrix")->promote($context, $M)->$name;
 }
+
+1;

macros/contexts/contextComplexJ.pl

@@ -1,7 +1,7 @@
 
 =head1 NAME
 
-C<contextComplexJ.pl> - Alters the Complex context to allow the
+contextComplexJ.pl - Alters the Complex context to allow the
 use of j-notation in addition to (or in place of) i-notation for
 complex numbers.
 
@@ -14,9 +14,6 @@ =head1 DESCRIPTION
 type), and how complex numbers should be displayed (you can force
 either form to be used regardless of how they were entered).
 
-
-=head1 USAGE
-
 To use this file, first load it into your problem, then use the
 Complex context as usual.  Both i and j notation will be allowed,
 and numbers will display in whichever format they were originally
@@ -68,7 +65,7 @@ =head1 USAGE
 all numebrs 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 to allow (or force, or warn
 about) the j notation, then create a file named

macros/contexts/contextCongruence.pl

@@ -1,10 +1,9 @@
 
-=encoding UTF-8
-=head1 NAME
+=encoding utf8
 
+=head1 NAME
 
-C<Context("Congruence")> - Provides contexts that allow the
-entry of congruence solutions
+contextCongruence.pl - Provides contexts that allow the entry of congruence solutions
 
 =head1 DESCRIPTION
 
@@ -19,9 +18,6 @@ =head1 DESCRIPTION
 
 Congruences must be created with three paramters (a, b, m) from ax ≡ b (mod m).
 
-=head1 USAGE
-
-
     loadMacros("contextCongruence.pl");
 
     Context("Congruence");

macros/contexts/contextCurrency.pl

@@ -153,7 +153,6 @@ =head1 DESCRIPTION
 =cut
 
 loadMacros("MathObjects.pl");
-#loadMacros("problemPreserveAnswers.pl");  # obsolete
 
 sub _contextCurrency_init { Currency::Init() }