Skip to content

Restructire the POD of macros (contexts) #1271

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions macros/contexts/contextABCD.pl
Original file line number Diff line number Diff line change
Expand Up @@ -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");
Expand Down
24 changes: 10 additions & 14 deletions macros/contexts/contextAlternateDecimal.pl
Original file line number Diff line number Diff line change
@@ -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>).

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
8 changes: 2 additions & 6 deletions macros/contexts/contextAlternateIntervals.pl
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
17 changes: 9 additions & 8 deletions macros/contexts/contextArbitraryString.pl
Original file line number Diff line number Diff line change
Expand Up @@ -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");
Expand All @@ -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.
Expand Down Expand Up @@ -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;
Expand Down
10 changes: 5 additions & 5 deletions macros/contexts/contextBaseN.pl
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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

Expand Down
18 changes: 11 additions & 7 deletions macros/contexts/contextBoolean.pl
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,10 @@ =head1 NAME

=head1 DESCRIPTION

This macro provides functionality for handling boolean expressions.

=head1 SYNOPSIS

Load this file:

loadMacros('contextBoolean.pl');
Expand All @@ -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:

Expand All @@ -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.
Expand Down Expand Up @@ -66,7 +70,7 @@ =head3 Aliases and Alternatives

=back

=head2 OPERATOR PRECEDENCE
=head1 OPERATOR PRECEDENCE

=over

Expand All @@ -86,7 +90,7 @@ =head2 OPERATOR PRECEDENCE

=back

=head2 REDUCTION
=head1 REDUCTION RULES

The context also handles C<reduceConstants> with the following reduction rules:

Expand Down Expand Up @@ -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.

Expand Down
12 changes: 7 additions & 5 deletions macros/contexts/contextComplexExtras.pl
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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;
Expand All @@ -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;
7 changes: 2 additions & 5 deletions macros/contexts/contextComplexJ.pl
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
10 changes: 3 additions & 7 deletions macros/contexts/contextCongruence.pl
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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");
Expand Down
1 change: 0 additions & 1 deletion macros/contexts/contextCurrency.pl
Original file line number Diff line number Diff line change
Expand Up @@ -153,7 +153,6 @@ =head1 DESCRIPTION
=cut

loadMacros("MathObjects.pl");
#loadMacros("problemPreserveAnswers.pl"); # obsolete

sub _contextCurrency_init { Currency::Init() }

Expand Down
9 changes: 8 additions & 1 deletion macros/contexts/contextFiniteSolutionSets.pl
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,14 @@ =head1 NAME

=head1 DESCRIPTION

After setting the context to "FiniteSolutionSets", make an answer like:
This provides some common input forms for a finite solution set.

Load the macro and set the Context:

loadMacros('contextFiniteSolutionSets.pl');
Context('FiniteSolutionSets');

Then create answers such as:

Formula("1,2")
Formula("1/2,2/3,3/4")
Expand Down
Loading