[Aimmath-developers] authoring tools and other mods

[Ken M. <mo...@pt...>]

I just committed all of the stuff I had been working on for the past couple
of weeks.  Most of it consists of question authoring tools.  Most if it is
also rather harmless, in that if you don't use it in writing your questions
it shouldn't break anything.  However, there are a few things that could
affect the LaTeX formatting of the mathematics in existing questions (though
I hope in most cases it will be for the better). If there is some change you
don't like, let me know and I'll do a feature-ectomy on that item.  See
below for details.

COMMITTED CHANGES: Sep 1, 2003
------------------------------

* Added the following files:

1. aim/Inert.mpl

This file contains a package called 'Inert'. (It has nothing to do with
ToInert and FromInert.)  It is an authoring tool that is designed to provide
inert forms of Maple expressions whose formatted appearance is independent
and separate from their mathematical value (somewhat analogous to the inert
operators Int or Diff in Maple). It is difficult to explain this in a short
email message, so I wrote up a quick explanation/introduction and
temporarily put it in the file AuthoringGuide.pdf in the docs directory.

This package is intended to be a first step towards solving the problem of
how to overcome the default simplification and formatting choices that are
made by Maple and AiM in order to give question authors the ability to
customize the notation used for a given expression according to their
lecture style and/or textbook.  This also solves the problem raised by Greg
recently regarding specifying the display format of the teacher's answer,
since using an Inert Expression as the teacher's answer puts the choice of
formatting under the question author's control.  Finally, it makes it
possible for me to donate some of the AiM questions I've written to the AiM
community, since almost all of my AiM questions are written using the Inert
package and its associated utilities.

Many of the changes in this round of updates are geared toward putting the
"hooks" for the Inert package throughout the system so that AiM becomes
'Inert'-aware.  Thus you can use Inert Expressions just like ordinary Maple
expressions with @-substitution with the t> flag, or as the teacher's answer
with the a> flag, etc.

If all of this sounds a bit vague, I apologize, but if you read the
AuthoringGuide.pdf, it should all make much more sense.

2.  aim/Decimal.mpl

This is a package for dealing with the decimal representations of rational
numbers in a rigorous manner that avoids the round off problems inherent in
working with floats.

3.  aim/SET.mpl

This defines a package that defines an AiM class called SET, which
represents and ordinary mathematical set. Ordinary Maple sets cannot be used
in AiM questions for the most part, because there is no guaranteed order to
the elements of a Maple set (so e.g. if you display the set to the student,
the order of the elements can change each time he reloads the page).  This
package replaces a Maple set with a SET object whose elements do have a
fixed order (but unlike a list, there cannot be duplicate elements). All of
the typical elementary set operations are also defined for SET's in this
package.

4.  aim/Number.mpl

This is a package of utilities for dealing with numbers and their
representations. It has routines for converting a positive integers to a
Roman numerals, Maple integers to their English word names, insert commas in
a large integer (e.g. 1234567 -> 1,234,567), produce the prime factorization
of an integer as a nicely formatted LaTeX string, and a routine similar to
Greg's nth() operation except that it puts the suffix as an exponent in a
LaTeX string.

5. aim/admin/CompileSubject.mpl

I got sick of going around to each of my quizzes and recompiling all of the
questions when I made significant changes to the code to see if the
questions all still compile, so I wrote a new admin command called
CompileSubject that compiles all of the files in all of the question source
directories of all of the non-hidden quizzes in a given subject.  I also put
a link to this on the subject admin page.  If you think this is too
dangerous of a command for the ordinary AiM user to have access to, we can
always delete the link to it from the subject page and just call it from a
shortcut externally or something.

6. AuthoringGuide.pdf (in the docs directory)

This is a temporary rough draft of what I hope will eventually become a
question authoring guide.  Currently it only contains a brief tutorial on
using the Inert package, but I hope to add sections about the Random package
and the Rand command, and the SET, Decimal, and Number packages.  Perhaps
others will want to eventually add sections about the Int, Diff, Trig, etc
packages... i.e. anything that is primarily a question authoring tool.  I
think this would be a big help for new question authors.  I often find
myself writing a particular utility, only to find out later that it already
exists somewhere in the AiM code.  This would be a more direct way to learn
what tools are available.

* In addition to adding the above packages, this round of changes also
includes the following

1. Changes to aim/Random.mpl
   + added several new features and options to Rand (documentation to follow
later)
   + added `Nice/Monomial`(), `Nice/Binomial`(), `Nice/Trinomial`() commands
to produce "Nice" versions of binomials, etc. For example, most textbooks
avoid using binomials like -2x^2-5 whereas something like x^2+1 is used all
of the time.  See the code if you want the exact definition of "Nice".

2. aim/Util.mpl
   + added the Keys() command and two minor utilities.  The Keys() command
is a utility for easily making question selector functions. See the docs for
the Keys() command.

3. aim/admin/Subject.mpl
   + added the link to the CompileSubject command

4. Aim.mpl
   + fixed the bug that was preventing guest access

5. aim/Test.mpl
   + upgraded `aim/Test` so it can handle Inert, InertExpr, and SET objects

6. aim/SyntaxHints
   + modified `aim/EntryHint`() so it can deal with InertExpr's.

7. aim/LaTeX
   + changed the default definition `latex/latex/**` to prevent it
     from making undesirable simplifications. We handle that
     manually in Inert.
   + changed the default definition of `latex/exp` so it formats exp(x) as
     "{{\\boldmath e}^{`latex/print`(x)}}" and exp(1) as {\\boldmath e}
   + changed `latex/latex/*` so it doesn't override the AiM default for
     _LaTeXSmallFractionConstant
   + defined a global variable 'LaTeXDigits', that is analogous to the Maple
variable 'Digits', except that it only affects the number of significant
digits displayed when converting a float to a LaTeX string, but does not
affect the number of digits used for doing calculations. The default value
is 3.
   + defined `latex/latex/float` to provide better conversion of floating
point numbers to LaTeX.
   + upgraded `aim/LaTeX` to handle InertExpr objects
   + defined a TeX() proc that behaves exactly like `aim/LaTeX` except that
strings are returned without adding extra double quotes around them (which
is almost always what you want in AiM).
   + fixed a bug in aim/LaTeX/Subs
   + added five new helper utilities to the aim/LaTeX packaged (mostly
needed to implement other things)

8. aim/MultiQuestion.mpl
   + changed the default time limit in the initialize routine from 2.0
seconds to the value of Config['TimeLimit'].

9. AliceServer.mpl
   + no longer unassign `latex/exp` since we define it in aim/LaTeX
   + define e:=exp(1) globally. Note that this means you probably can't use
e as a local variable in your AiM questions. On the other hand both you and
the students can use e^x for exp(x).
   + define _LaTeXSmallFractionConstant := 5000 (TODO: implement a more
flexible way to set this value).

10. Util.mpl
   + added two technical utilities I needed elsewhere

-----------
Having installed both the above changes and the most recent changes posted
to the archive, I can report that most things seem to be working for me
under Maple 9.  The only things I have noticed so far are:

  + ln is now formatting incorrectly for some reason. It is coming out in
italics. I think latex/latex/symbol is messed up in Maple 9.  I'll try to
debug this.

  + there is an error message:

    Error, (in Class/IndexFunction) Type error in assignment: field
InertFunction in class InertExpr should have type Inert

  That occurs quite frequently, though I can't reproduce the exact
conditions to make it repeatable.  If I change the 3 lines labeled WAS: in
Class/IndexFunction in Class.mpl back to what they were the error to goes
away. I don't really understand that proc or why those changes were made in
the first place so I don't want to just change it back since someone
obviously changed them for a reason. I'll post this to the official bug site
list tomorrow.

  + I still get a sporadic error:

    Validation Note: bad name x.

    when Trying certain questions.  It is non-repeatable. It is always with
one-letter variable when it does occur.  It only ever happens when I Try the
questions or Try a quiz as administrator and the system is filling in the
answer box for me, never  when I attempt the question as a student.  It is
very strange.

OK,... time for bed.  I'll post the bugs and continue testing and working on
documentation tomorrow...

ciao,
KEN

-----------------------------------------
Ken Monks - Professor of Mathematics
            University of Scranton
            Scranton, PA 18510
email: mailto:mo...@sc...
web:   http://www.scranton.edu/~monks
-----------------------------------------