[WWdevel] macro documentation

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

Hi Davide, Sam and other interested parties,

Here is the framework that I have started in order to document the  
existing macros.  This is the first step towards
consolidating many of the existing macros into a smaller core that is  
easier to remember, use and maintain.

In addition to macros stored in pg   I also plan to  convert to pod  
documentation many of the code comments from
the union macros file.  As Davide has pointed out even a few of union  
macro constructs are likely to be replaced by the new MathObjects
constructs (the new name for "parser" objects unless someone can  
think of something better quickly. :-) ), but they already
provide an improvement on earlier constructs and will help provide a  
smooth transition as well as an indication of
the direction in which the language is heading.  In order allow  
Davide to continue to maintain the union_problib/macros repository
I have made the pod documentation changes on the    rel-2-3- 
experimental branch of union_problib/macros.

I believe that this is transparent.  If you want to get the files  
with the new pod documentation issue, in union_problib macros

cvs update -r rel-2-3-experimental

If you want Davide's latest version of the macro files use

cvs update -r HEAD
or
cvs update -A

Hopefully this will work without interfering with each other and will  
make it a bit  easier to consolidate the code and the documentation
changes when the time comes.

For an example of how the union macros improve on the old constructs  
read the buglist reports related to multi_cmp and list_cmp.  I think  
I've established that list_cmp is a drop in
replacement for multi_cmp.  There are still a few issues with  
list_cmp and/or the old Complex structures that need to be investigated.
(One possible solution is to drop the old Complex structure, but it's  
a bit premature to be sure of that.)

Davide has pointed out that he likes to have comments set off by # so  
that it is easy to tell whether one is in the pod section or the
code section of a file.  (My recent version of BBedit has learned to  
read pod documentation and subtly grays out the print in the commented
out sections -- including pod documentation.  I hadn't realized quite  
how useful that's become.)
In any case I've modified Sam's program wwdocs2html.pl   to add a  
filter.   If a line has initial white space followed by a # then the
section from the beginning of the line to the # is deleted and the  
resulting file is passed to the pod2html program.

This means that a section such as:

=head3 num_list_cmp

#####################################################################
#
#Usage:  num_list_cmp(ans,options)
#
#  where ans is the string indicating the list (e.g., "10, -3, 5")
#  and options are any of those that can be passed to std_list_cmp.

=cut

will create an html page that has the information above but with the  
initial #'s removed.  By
using global search and replace to  replace    initial # by a space  
followed by a #  i.e.  $_ =~ (s/^#/ #/)
you can even run the .pl file through a standard pod processor and  
get reasonable HTML output, although the initial
#'s on each of the lines doesn't look great and probably not all of  
the standard pod features work.

Sam -- you'll find my version in ~/admintools.  I'm using a temporary  
file and I'm quite sure that the code can be modified to feed
the pod files through a filter and into the STDIN of pod2html -- then  
no obvious temporary file is written.  You may see other improvements
as well.

To see how this works  -- go the PGeditor on any problem,  click on  
"pod documentation" and navigate to
union_macros/listAnswer.pl.html

There only a few other files that have been converted to pod  
documentation so far, but there will be more as Spyro Roubos
gets working on the files and as I continue to use them to write  
homework problems for my complex variable course.

We will also link this urls into the twiki page reached by clicking  
on "macro list" from the PGeditor.  That hasn't started yet.

Comments and suggestions are welcome.

Take care,

Mike