Fixes to some of the =headN in the POD

pstaabp · pstaabp · commit abbefab8755b · 2025-07-07T15:59:10.000-04:00
Some other formatting fixes.
diff --git a/lib/PGcore.pm b/lib/PGcore.pm
@@ -667,7 +667,7 @@ sub surePathToTmpFile {
 	return $path;
 }
 
-=head1 FUNCTIONS from IO.pm
+=head1 Macros from IO.pm
 
 		includePGtext
 		read_whole_problem_file
diff --git a/macros/PG.pl b/macros/PG.pl
@@ -3,7 +3,7 @@ =head1 NAME
 
 PG.pl - Provides core Program Generation Language functionality.
 
-=head1 SYNPOSIS
+=head1 SYNOPSIS
 
 In a PG problem:
 
diff --git a/macros/answers/PGasu.pl b/macros/answers/PGasu.pl
@@ -9,9 +9,11 @@ =head1 DESCRIPTION
 
 =head1 FUNCTIONS
 
-=head2 auto_right()
+=head2 auto_right
 
-Usage: C<ANS(auto_right());>
+Usage:
+
+    ANS(auto_right());
 
 or
 
@@ -442,7 +444,7 @@ sub pc_evaluator {
 	$ans_evaluator;
 }
 
-=head2 weighted_partial_grader
+=head2 weighted_partial_grader [DEPRECATED]
 
 This is a grader which weights the different parts of the problem
 differently.  The weights passed to it through the environment.  In
diff --git a/macros/answers/PGstringevaluators.pl b/macros/answers/PGstringevaluators.pl
@@ -14,6 +14,12 @@ =head1 DESCRIPTION
 
 String answer evaluators compare a student string to the correct string.
 
+=head2 MathObjects and answer evaluators
+
+The MathObjects system provides a String->cmp() method that produce answer
+evaluators for string comparisons. It is recommended that you use the String
+object's cmp() method directly if possible.
+
 =cut
 
 BEGIN { strict->import; }
@@ -226,7 +232,7 @@ =head3 options
 	ANS(str_cmp($ans, 'remove_whitespace', 'ignore_order'));
 	ANS(str_cmp($ans, filters=>['remove_whitespace', 'ignore_order']));
 
-=head3 Examples
+=head2 Examples
 
 	# same as std_str_cmp() -- matches "Hello", "  hello", etc.
 	str_cmp("Hello")
diff --git a/macros/answers/extraAnswerEvaluators.pl b/macros/answers/extraAnswerEvaluators.pl
@@ -9,7 +9,7 @@ =head1 DESCRIPTION
 This is a list of macros that create "answer evaluators" for checking student
 answers of various "exotic" types.
 
-=head1 SYNPOSIS
+=head1 SYNOPSIS
 
 	interval_cmp() -- checks answers which are unions of intervals. It can also
 					  be used for checking an ordered pair or list of ordered
diff --git a/macros/answers/unorderedAnswer.pl b/macros/answers/unorderedAnswer.pl
@@ -29,7 +29,7 @@ =head2 UNORDERED_ANS
 below.  Otherwise, be sure to use C<UNORDERED_ANS> right after the answer
 rules for the answers you want to compare.
 
-Format:
+Usage:
 
     UNORDERED_ANS(checker1, checker2, ...);
 
@@ -64,9 +64,9 @@ =head2 UNORDERED_NAMED_ANS
 Collect a group of answer checkers for use with named answers that
 can be given in any order.
 
-Format:
+Usage:
 
-UNORDERED_NAMED_ANS(name1 => checker1, name2 => checker2, ...);
+    UNORDERED_NAMED_ANS(name1 => checker1, name2 => checker2, ...);
 
 Example:
 
diff --git a/macros/contexts/contextAlternateDecimal.pl b/macros/contexts/contextAlternateDecimal.pl
@@ -76,7 +76,7 @@ =head1 DESCRIPTION
 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
@@ -101,16 +101,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
@@ -119,17 +119,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
@@ -143,14 +143,10 @@ =head1 SETTING THE ALTERNATE FORM AS THE DEFAULT
 
 =cut
 
-###########################################################
-
 loadMacros("MathObjects.pl");
 
 sub _contextAlternateDecimal_init { context::AlternateDecimal->Init }
 
-###########################################################
-
 package context::AlternateDecimal;
 
 #
diff --git a/macros/contexts/contextAlternateIntervals.pl b/macros/contexts/contextAlternateIntervals.pl
@@ -78,7 +78,7 @@ =head1 DESCRIPTION
 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
diff --git a/macros/contexts/contextBaseN.pl b/macros/contexts/contextBaseN.pl
@@ -73,7 +73,7 @@ =head1 DESCRIPTION
 
 The last two digits for C<base64> are nonstandard. We want to avoid '+' and '/' here as they have arithmetic meaning.
 
-=head1 Sample PG problem
+=head2 Sample PG problem
 
 A simple PG problem that asks a student to convert a number into base-5:
 
@@ -119,7 +119,7 @@ =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
 
diff --git a/macros/contexts/contextBoolean.pl b/macros/contexts/contextBoolean.pl
@@ -41,7 +41,7 @@ =head1 OPERATORS
     Context->operators->set( not => { TeX => '\neg ' } );
 
 
-=head1 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.
@@ -70,7 +70,7 @@ =head1 Aliases and Alternatives
 
 =back
 
-=head1 OPERATOR PRECEDENCE
+=head2 Operator Precedence
 
 =over
 
@@ -90,7 +90,7 @@ =head1 OPERATOR PRECEDENCE
 
 =back
 
-=head1 REDUCTION
+=head2 Reduction Rules
 
 The context also handles C<reduceConstants> with the following reduction rules:
 
@@ -118,7 +118,7 @@ =head1 REDUCTION
 
 =back
 
-=head1 COMPARISON
+=head2 Comparison
 
 Boolean Formula objects are considered equal whenever the two expressions generate the same truth table.
 
diff --git a/macros/contexts/contextComplexJ.pl b/macros/contexts/contextComplexJ.pl
@@ -65,7 +65,7 @@ =head1 DESCRIPTION
 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
diff --git a/macros/contexts/contextFiniteSolutionSets.pl b/macros/contexts/contextFiniteSolutionSets.pl
@@ -11,7 +11,7 @@ =head1 DESCRIPTION
 Load the macro and set the Context:
 
     loadMacros('contextFiniteSolutionSets.pl');
-	Context('FiniteSolutionSets');
+    Context('FiniteSolutionSets');
 
 Then create answers such as:
 
diff --git a/macros/core/PGanswermacros.pl b/macros/core/PGanswermacros.pl
@@ -7,7 +7,7 @@ =head1 NAME
 
 PGanswermacros.pl - Macros for building answer evaluators.
 
-=head1 SYNPOSIS
+=head1 SYNOPSIS
 
 Number Answer Evaluators:
 
diff --git a/macros/core/PGbasicmacros.pl b/macros/core/PGbasicmacros.pl
@@ -2573,8 +2573,8 @@ =head2 PGsort
 Because of the way sort is optimized in Perl, the symbols $a and $b
 have special significance.
 
-C<sort {$a<=>$b} @list>
-C<sort {$a cmp $b} @list>
+    sort {$a<=>$b} @list
+    sort {$a cmp $b} @list
 
 sorts the list numerically and lexically respectively.
 
@@ -2638,7 +2638,9 @@ sub num_sort {
 
 =head2 Macros for handling tables
 
-    Usage:
+B<< Note: that these are deprecated.  See L<nicetables.pl> for a replacement. >>
+
+Usage:
     begintable( number_of_columns_in_table)
     row(@dataelements)
     endtable()
diff --git a/macros/core/PGcommonFunctions.pl b/macros/core/PGcommonFunctions.pl
@@ -19,12 +19,12 @@ package CommonFunction;
 =head2 NOTE
 
 
-#  Either call Parser (if it has been loaded) or
-#  the functions below.  (If it's ever the case
-#  that both the Parser and PGauxiliaryFunctions.pl are
-#  both preloaded, then there will be no need for
-#  this, as you can always use the Parser versions.
-#  We only need this because Parser might not be loaded.)
+Either call Parser (if it has been loaded) or
+the functions below.  (If it's ever the case
+that both the Parser and PGauxiliaryFunctions.pl are
+both preloaded, then there will be no need for
+this, as you can always use the Parser versions.
+We only need this because Parser might not be loaded.)
 
 
 =cut
diff --git a/macros/core/PGessaymacros.pl b/macros/core/PGessaymacros.pl
@@ -3,7 +3,7 @@ =head1 NAME
 
 PGessaymacros.pl - Macros for building answer evaluators.
 
-=head2 SYNPOSIS
+=head2 SYNOPSIS
 
 Answer Evaluators:
 
diff --git a/macros/core/RserveClient.pl b/macros/core/RserveClient.pl
@@ -38,7 +38,9 @@ =head1 METHODS
 The methods in this file set up a connection to the R server and pass a string
 parameter to R for evaluation.  The result is returned as a Perl object.
 
-=head2 rserve_start, rserve_finish
+=head2 rserve_start
+
+=head2 rserve_finish
 
 Start up and close the current connection to the Rserve server. In normal use,
 these functions are not needed because a call to any of the other methods will
diff --git a/macros/deprecated/CofIdaho_macros.pl b/macros/deprecated/CofIdaho_macros.pl
@@ -3,7 +3,7 @@ =head1 NAME
 
 CofIdaho.pl - extra macros for Intermediate Algebra problems at The College of Idaho
 
-=head1 Synposis
+=head1 SYNOPSIS
 
 macros by R Cruz -- The College of Idaho
 
diff --git a/macros/deprecated/PGsequentialmacros.pl b/macros/deprecated/PGsequentialmacros.pl
@@ -4,7 +4,7 @@ =head1 NAME
 PGsequentialmacros.pl -  Provides support for writing sequential problems, where certain parts
 of the problem are hidden until earlier questions are answered correctly.
 
-=head1 SYNPOSIS
+=head1 SYNOPSIS
 
 The basic sequential problem structure:
 
diff --git a/macros/graph/PGgraphmacros.pl b/macros/graph/PGgraphmacros.pl
@@ -3,7 +3,7 @@ =head1 NAME
 
 PGgraphmacros.pl - provides functionality for plotting functions, points and adding labels.
 
-=head1 SYNPOSIS
+=head1 SYNOPSIS
 
     use Fun;
     use Label;
@@ -402,7 +402,9 @@ sub closed_circle {
 	new Circle($cx, $cy, 4, $color, $color);
 }
 
-=head2 tring_to_sub, my_math_constants
+=head2 tring_to_sub
+
+=head2 my_math_constants
 
 These are internal macros which govern the interpretation of equations.
 
diff --git a/macros/graph/PGstatisticsGraphMacros.pl b/macros/graph/PGstatisticsGraphMacros.pl
@@ -3,7 +3,7 @@ =head1 NAME
 
 PGstatisticsGraphMacros.pl - Provides statistic graphs using the WWPlot macros.
 
-=head1 SYNPOSIS
+=head1 SYNOPSIS
 
     use Fun;
     use Label;
diff --git a/macros/math/LinearProgramming.pl b/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.
 
diff --git a/macros/math/MatrixCheckers.pl b/macros/math/MatrixCheckers.pl
diff --git a/macros/math/PGmatrixmacros.pl b/macros/math/PGmatrixmacros.pl
diff --git a/macros/math/PGmorematrixmacros.pl b/macros/math/PGmorematrixmacros.pl
diff --git a/macros/math/VectorListCheckers.pl b/macros/math/VectorListCheckers.pl
diff --git a/macros/math/tableau.pl b/macros/math/tableau.pl
diff --git a/macros/misc/randomPerson.pl b/macros/misc/randomPerson.pl

Original file line number	Diff line number	Diff line change
`@@ -667,7 +667,7 @@ sub surePathToTmpFile {`
`667`	`667`	`return $path;`
`668`	`668`	`}`
`669`	`669`
`670`		`-=head1 FUNCTIONS from IO.pm`
	`670`	`+=head1 Macros from IO.pm`
`671`	`671`
`672`	`672`	`includePGtext`
`673`	`673`	`read_whole_problem_file`