Re: [WWdevel] A table of existing macros

[Michael E. G. <ga...@ma...>]

On Jul 5, 2005, at 8:02 AM, Davide P.Cervone wrote:

>> I've made a chart of most of the macros currently available for use in
>> WeBWorK problem  (this includes macros from union_problib/macros, but  
>> not
>> yet the macros from nau_problib/macros)
>
> This looks like a good start, and a useful thing, though it is going  
> to be a pain to maintain.  I wonder if we should institute some kind  
> of coding convention to help automatically separate the internal  
> routines from the public ones.  (Or do you envision maintaining this  
> by hand from now on?)
>
I can recreate it by hand if need be.  It's a pain and takes an hour or  
so to clean it up using BBedit. Eventually I could automate it if it  
proves useful.  It will be even more of pain to maintain the comments.   
For the moment I view it as a transitional document, to see where we  
are and what needs to be done.

> I'm not quite sure I think the last column is necessary, as it is  
> usually incomplete.
>
The third column is really for comments.  For those items that haven't  
been commented on it
just contains "{ " and sometimes a little code or a comment.  I was too  
lazy to clean the code, even though it's not hard to do.  Sometimes the  
comment is useful.

>> There are over 900 macros -- way too many -- so some consolidation is  
>> in order and the place to start would be to try to get a handle on  
>> what has already been produced and how they overlap.
>
> In addition to the suggestions that you recommend concerning the older  
> anser macros, quite a few of the parser-based routines are internal  
> and shouldn't be listed.  For example, pretty much everything in  
> context*.pl is internal.  You might even consider not including any of  
> the parser stuff here, as that is a whole other ball of wax, and only  
> a portion of its routines are in .pl files.
>
> This brings up the point that there are many important macros that are  
> part of the .pm files in pg/lib rather than .pl files in pg/macros.   
> The various list macros come to mind, and so on.  Should they be  
> included here?
>
The list is still incomplete.  It does not include the .pm files or any  
of the NAU files.  Most of the .pm methods  are either internal
or high-level, but not all of them.   I included the parser files  
mainly because I wanted to reveal any overlap with existing routines.   
That helps us understand which macros can be retired.

I view this document as useful to developers more than to problem  
writers and other users.  An abortive attempt to write manpages for the  
useful and common routines is listed at  
http://webhost.math.rochester.edu/webworkdocs/docs/pglanguage/manpages/ 
.  It  is bogged down because I'm the main contributor and because the  
best input method is using the radio/frontier outliner.  I suspect that  
I could generalize the input to handle any outliner that
uses OPML as an output or export format.  (I also have an poorly  
maintained script that will produce TeX output from the same outlines.)  
  I like the format for the routines (which I borrowed from  
docserver.userland.com), but I'm not wedded to the input mechanism.  If  
someone has a good idea of how to easily input and maintain the data  
currently in the manpages -- particularly if we can reformat that same  
data for TeX or XML or other formats, let's hear it.  Good manpages are  
becoming a high priority.

> Also, some of the routines listed are part of packages and can't be  
> called directly.  They either are object methods, or require package  
> names (package::routine).
>
>> One of my desires is to replace the calls such as
>>
>> strict_num_cmp( $ans, .001,'%0.5f')
>> by
>> num_cmp($ans, relTol=>.001, format=>'%0.5f', mode=>'strict')
>>
>> and
>>
>> strict_num_cmp_list(.001, '%0.5f',$ans1, $ans2, $ans3);
>>
>> by
>>
>> num_cmp([$ans1, $ans2, $ans3], relTol=>.001, mode=>'strict',  
>> format=>'%o.5f');
>>
>> perhaps a dozen different subroutines can be replaced by using num_cmp
>> with either a single answer, or a reference to an array of answers  
>> and then
>> followed by a list of parameters.
>

> This is admirable, but I'm not holding my breath to see people convert  
> their old problems or stop using the older forms in new ones.  If you  
> do actually remove them from PGanswermacros.pl, that will break lots  
> of existing problems, and while that will force them to update (or at  
> least to add PGcompatibility.pl to those files), it will also be a big  
> aggravation to them.  The huge number of different forms of these  
> macros is a pain, though, so I understand the desire to eliminate some  
> of them.
>
> It would not be too hard to write a script that does that conversion,  
> I would expect.  That would help people out.
>
Many of the people who might be most aggravated are using un-retouched  
versions of the rochester problem library.  By updating the library  
either by CVS or by tarball they'd have working problems.   
Unfortunately the aggravation will increase rather than decrease with  
time.  Since there are a number of new problem developers coming on  
board now, and hopefully new cleaned up problems will arrive by the end  
of the summer, now is probably as good a time as any to clean house.   
Writing transition scripts is also a good idea.

Take care,

Mike

> Davide
>