Merge pull request #1268 from Alex-Jordan/restructure-pod-macros-math

Restructire the POD of macros (math)

Author: drgrice1

macros/math/LinearProgramming.pl

@@ -4,7 +4,7 @@ =head1 NAME
 LinearProgramming.pl - Macros for the simplex tableau for linear programming
 problems.
 
-=head1 SYNPOSIS
+=head1 SYNOPSIS
 
 Macros related to the simplex method for Linear Programming.
 
@@ -33,7 +33,7 @@ =head1 DESCRIPTION
 
 or something similar which arises after pivoting.
 
-=head1 MACROS
+=head1 FUNCTIONS
 
 =head2 lp_pivot
 

macros/math/MatrixCheckers.pl

@@ -1,10 +1,8 @@
-sub _MatrixCheckers_init { };    # don't reload this file
-
-=pod
 
 =head1 NAME
 
-MatrixCheckers.pl
+MatrixCheckers.pl - Provides subroutines for answer checking using MathObjects
+matrices with real entries.
 
 =head1 SYNOPSIS
 
@@ -17,57 +15,47 @@ =head1 DESCRIPTION
 First, load the C<MatrixCheckers.pl> macro file.  If the basis has
 more than one vector, also load C<parserMultiAnswer.pl>.
 
-=over 12
-
-=item loadMacros("PGstandard.pl","MathObjects.pl","parserMultiAnswer.pl","MatrixCheckers.pl");
-
-=back
+    loadMacros("PGstandard.pl","MathObjects.pl","parserMultiAnswer.pl","MatrixCheckers.pl");
 
 For a matrix that has a single column or row, the way to use the
 answer checkers is the same as using a custom answer checker
-inside of C<cmp(checker=>~~&name_of_answer_checker_subroutine)>
+inside of C<< cmp(checker=>~~&name_of_answer_checker_subroutine) >>
 such as
 
-=over 12
+    ANS( Matrix([[1],[2],[3]])->cmp( checker=>~~&basis_checker_one_column ) );
+    ANS( Matrix([[1],[2],[3]])->cmp( checker=>~~&unit_basis_checker_one_column ) );
 
-=item C<ANS( Matrix([[1],[2],[3]])->cmp( checker=>~~&basis_checker_one_column ) );>
-
-=item C<ANS( Matrix([[1],[2],[3]])->cmp( checker=>~~&unit_basis_checker_one_column ) );>
-
-=back
 
 The "one column" at the end of the checker name refers to the
 fact that the student answer is a one-column matrix.  The "unit
 basis checker" ensures that the student answer has unit length.
 
+=head2 Checkers
+
 For answers that are a collection of column or row vectors, the
 way to use the answer checkers is inside of a MultiAnswer object.
 The macro C<parserMultiAnswer.pl> should also be loaded.
 The answer checkers that should be used inside a MultiAnswer
 object are:
 
-=over 12
+=head3 basis_checker_columns
 
-=item C<basis_checker_columns>
+=head3 orthonormal_basis_checker_columns
 
-=item C<orthonormal_basis_checker_columns>
+=head3 basis_checker_rows
 
-=item C<basis_checker_rows>
+=head3 orthonormal_basis_checker_rows
 
-=item C<orthonormal_basis_checker_rows>
+=head3 parametric_plane_checker_columns
 
-=item C<parametric_plane_checker_columns>
-
-=back
+=head2 Examples
 
 Here is an example of how to use these answer checkers.
 In the setup section of the PG file we create two 3 x 1 MathObject
 matrices with real-entries that serve as basis vectors.  The object
 C<$multians> takes the basis vectors as input and passes them
 to the custom answer checker called by C<checker =<gt>...>.
 
-=over 12
-
     $basis1 = Matrix([1/sqrt(2), 0, 1/sqrt(2)])->transpose;
     $basis2 = Matrix([0,1,0])->transpose;
 
@@ -79,17 +67,12 @@ =head1 DESCRIPTION
         checker => ~~&orthonormal_basis_checker_columns,
     );
 
-=back
-
 In the main text portion of the PG file, we use C<\{ $multians-<gt>ans_array(15) \}>
 to create an array of text boxes that are 15 characters wide and have square
 brackets around them to look like a matrix.  The braces around the vectors, which
 are produced by C<\(\Bigg\lbrace\)> and C<\(\Bigg\rbrace\)>, are a matter of personal
 preference (since a basis is an ordered set, I like to include braces).
 
-
-
-    Context()->texStrings;
     BEGIN_TEXT
     Find an orthonormal basis for...
     $BR
@@ -101,18 +84,11 @@ =head1 DESCRIPTION
     \(\Bigg\rbrace.\)
     $ECENTER
     END_TEXT
-    Context()->normalStrings;
-
-
 
 The answer evaluation section of the PG file is totally standard.
 
-=over 12
-
     ANS( $multians->cmp );
 
-=back
-
 The C<parametric_plane_checker_columns> should be used for
 solutions to non-homogeneous systems of linear equations for
 which the solution is essentially a point plus the span of
@@ -122,17 +98,11 @@ =head1 DESCRIPTION
 particular solution), while the remaining vectors are a basis for
 the hyperplane (i.e., they span the homogeneous solution set).
 
-=head1 AUTHORS
-
-Paul Pearson, Hope College, Department of Mathematics
-
 =cut
 
-################################################
-
-loadMacros("MathObjects.pl",);    # , will "parserMultiAnswer.pl" create an infinite loop?
+sub _MatrixCheckers_init { };    # don't reload this file
 
-################################################
+loadMacros("MathObjects.pl",);   # , will "parserMultiAnswer.pl" create an infinite loop?
 
 sub concatenate_columns_into_matrix {
 
@@ -145,8 +115,6 @@ sub concatenate_columns_into_matrix {
 
 }
 
-##########################################
-
 sub basis_checker_one_column {
 
 	my ($correct, $student, $answerHash) = @_;
@@ -168,8 +136,6 @@ sub basis_checker_one_column {
 
 }
 
-##########################################
-
 sub basis_checker_columns {
 
 	my ($correct, $student, $answerHash) = @_;
@@ -215,8 +181,6 @@ sub basis_checker_columns {
 
 }
 
-#############################################
-
 sub unit_basis_checker_one_column {
 
 	my ($correct, $student, $answerHash) = @_;
@@ -236,8 +200,6 @@ sub unit_basis_checker_one_column {
 
 }
 
-###############################################
-
 sub orthonormal_basis_checker_columns {
 
 	my ($correct, $student, $answerHash) = @_;
@@ -290,8 +252,6 @@ sub orthonormal_basis_checker_columns {
 
 }
 
-##############################################
-
 sub basis_checker_rows {
 
 	my ($correct, $student, $answerHash) = @_;
@@ -338,8 +298,6 @@ sub basis_checker_rows {
 
 }
 
-#############################################
-
 sub orthonormal_basis_checker_rows {
 
 	my ($correct, $student, $answerHash) = @_;
@@ -393,8 +351,6 @@ sub orthonormal_basis_checker_rows {
 
 }
 
-##############################################
-
 sub parametric_plane_checker_columns {
 
 	my ($correct, $student, $answerHash) = @_;
@@ -457,6 +413,4 @@ sub parametric_plane_checker_columns {
 
 }
 
-########################################################
-
 1;

macros/math/MatrixReduce.pl

@@ -1,16 +1,14 @@
-sub _MatrixReduce_init { };    # don't reload this file
-
-=pod
 
 =head1 NAME
 
-MatrixReduce.pl - reduced row echelon form, row
-operations, and elementary matrices.
+MatrixReduce.pl - Provides subroutines for elementary matrix computations using
+MathObjects matrices.
 
-=head1 SYNOPSIS
+=head1 DESCRIPTION
 
-Provides subroutines for elementary matrix
-computations using MathObjects matrices.
+Provides subroutines for elementary matrix computations using MathObjects
+matrices, such as finding the reduced row echelon form, performing row
+operations, and constructing elementary matrices.
 
 =over 12
 
@@ -68,7 +66,7 @@ =head1 SYNOPSIS
 
 =back
 
-=head1 DESCRIPTION
+=head1 SYNOPSIS
 
 Usage:
 
@@ -147,9 +145,10 @@ =head1 AUTHORS
 # a consistent system.  Also, with randomly chosen matrices, it is
 # possible to get rows or columns of zeros, so watch out!
 
+sub _MatrixReduce_init { };    # don't reload this file
+
 loadMacros("MathObjects.pl", "contextFraction.pl",);
 
-################################################
 #  rref: input and output are MathObject matrices.
 #  Should be run in Fraction context for best results.
 
@@ -201,7 +200,6 @@ sub rref_perl_array {
 	return @A;
 }
 
-################################################
 #  This was written by Davide Cervone.
 #  http://webwork.maa.org/moodle/mod/forum/discuss.php?d=2970
 
@@ -216,15 +214,11 @@ sub change_matrix_entry {
 	}
 }
 
-################################################
-
 sub identity_matrix {
 	my $n = shift;
 	return Value::Matrix->I($n);
 }
 
-################################################
-
 sub elem_matrix_row_switch {
 
 	# $n = number of rows (and columns) in matrix
@@ -241,8 +235,6 @@ sub elem_matrix_row_switch {
 
 }
 
-#########################################
-
 sub elem_matrix_row_mult {
 
 	# $n = number of rows (and columns) in matrix
@@ -263,8 +255,6 @@ sub elem_matrix_row_mult {
 
 }
 
-######################################
-
 sub elem_matrix_row_add {
 
 	# $n = number of rows (and columns) in matrix
@@ -285,16 +275,14 @@ sub elem_matrix_row_add {
 
 }
 
-##############################################
-
 sub row_add {
 
 	# put  (row i) + s * (row j) into (row i)
 
-	my $M = shift;    # MathObject matrix
-	my $i = shift;    # row index
-	my $j = shift;    # row index
-	my $s = shift;    # scaling factor
+	my $M = shift;                   # MathObject matrix
+	my $i = shift;                   # row index
+	my $j = shift;                   # row index
+	my $s = shift;                   # scaling factor
 
 	my ($r, $c) = $M->dimensions;
 	if (($i < 1) or ($j < 1) or ($i > $r) or ($j > $r)) {
@@ -318,8 +306,6 @@ sub row_add {
 
 }
 
-####################################
-
 sub row_switch {
 
 	my $M  = shift;    # MathObject matrix
@@ -336,8 +322,6 @@ sub row_switch {
 
 }
 
-#########################################
-
 sub row_mult {
 
 	my $M = shift;    # MathObject matrix
@@ -357,8 +341,6 @@ sub row_mult {
 
 }
 
-####################################
-
 sub apply_fraction_to_matrix_entries {
 
 	my $M = shift;