Language/OS - Multiplatform Resource Library/LANGUAGE OS.iso/maple/guide

Text File | 1994-06-21 | 7.8 KB | 208 lines

Guidelines for contributing to the Maple share library.
=======================================================

The purpose of the share library is to make Maple code and applications
worksheets which have been developed by Maple users and groups other than the
Maple company Waterloo Maple Software (WMS) freely available to Maple users.

For code and worksheets to be added to the share library, we require that

1) you grant WMS a non-exclusive right to distribute your code or worksheet(s)
   to any Maple user who requests it.  You may wish to include an authors
   copyright notice in your code so that other parties cannot distribute it,
   or sell it for profit.

2) you hereby authorize WMS to modify your code or worksheet(s) as required,
   for example, to correct bugs, and make changes required due to changes in
   new versions of Maple

3) you provide test file(s) (described below) that adequately test your Maple
   code so that we can reasonably determine whether the code is working.

4) you provide Maple style help file(s) (see below) as documentation for your
   Maple code.

Points 1) and 2) are stated precisely in the file called "agree".
Please read it, fill it out, sign it, and send or fax it to us at

  Dr. Michael Monagan
  Institute for Scientific Computation, ETH Zentrum,
  CH 8092 Zurich, Switzerland.
  FAX: [phone]
  EMAIL: [e-mail]

Code and worksheets must be sent by electronic mail to Dr. Monagan at the
above address.  We insist on electronic mail because this this only feasible
way in which we can contact you in case there is a problem with the code.

We also include some simple coding style conventions below.

Please understand that you are giving the code to the Maple community.
You may not expect the WMS to pay any royalty or other monies for the code.
However, WMS will NOT sell your code for profit.
You may of course sell or distribute your code yourself.


Test files
==========

The test file should read your code, and for each test, compare
the actual answer computed with the answer that it should yield.
If the comparison is okay, then the string "okay" should be printed.
Otherwise you should print the bad result.
Thus a typical test would be

  a := symmpoly([x,y,z],2):
  if a = x*y + x*z + y*z then print(okay) else print(a) fi;

Notice that the correct result is included in the test file.
And also that the output of a test which runs correctly is
simply a sequence of okay's.

Please include the examples that you use in your help file as tests.
In writing tests, you should also be aware of the following.
Maple, and/or your code may return an answer that looks different,
but is the same mathematically.  For example, Maple may return
exp(2*x) instead of exp(x)^2 .  In your application, both answers
may be acceptable.  Secondly, the output may come in a different
order, e.g. [x^2+x+1, x^4+x+1] instead of [x^4+x+1, x^2+x+1].


Coding conventions
==================

1: Global variables
-------------------
Every programmer has his/her own coding style and we are not
going to tell you how to program.  However, please do not use global
variables in your procedures unless absolutely necessary.
If necessary, please document them in the on-line help documentation.

The "mint" program will tell you which variables are global in
your procedures and which names clash with Maple library functions.
Look for global variables that you have forgotten to declare local.

2: Naming conventions
---------------------
Routines and global variables which are not meant to be directly accessed
by the user, should be given "slash" names.  E.g. if your package is called
foo, and you have a local routine which checks the input, you should call
it `foo/check` and not check.  The macro facility will be useful here to
avoid having to type `foo/check` throughout the code.  Simply put

  macro(foo = `foo/check`);

at the top of your code.  See ?macro for details

3: Type checking
----------------
Please include adequate type checking.  The type checking also serves
as useful documentation for finding errors and understanding which cases
your code is intended to handle.  For Maple V Release 2 and later versions,
it is possible to declare the type of parameters.  For example, a routine
foo which takes an algebraic expression a and an integer n as arguments can
be written in this way

  foo := proc(a:algebraic, n:integer)

A routine foo which takes a list E of polynomials and a list X of variables as
arguments can be written

  foo := proc(E:list(polynom),X:list(name))

4: Miscellaneous
---------------
Please do not use the old $ function for creating sequences.
Please use instead the seq function.
For example, instead of 'f(i)' $ 'i'=1..n use

  seq(f(i),i=1..n);

The seq function works like a for loop.  It doesn't require quotes and
consequently is much simpler to use.  It is also more efficient.


Documentation and Help files
============================

Remember, your code is only as useful as your documenation is clear.
We require that you include Maple style help files which include a desciption
of the user-level procedures and and global variables in your code, plus
examples showing typical usage.

A TeX or LaTeX document is welcome as additional documentation.
An Maple .ms worksheet (Release 2) showing how the package is used,
and typical examples, is especially welcome.

To write a Maple help file for a function called say "symmpoly"
one assigns an object of type TEXT to the name `help/text/symmpoly`.
A TEXT object is a function whose arguments are Maple strings.
For example, here is a help file for the symmpoly function

  `help/text/symmpoly` := TEXT(
  `FUNCTION: symmpoly - generate the symmetric polynomials`,
  `   `,
  `CALLING SEQUENCES: symmpoly([x1,x2,...,xn]);  or`,
  `                   symmpoly([x1,x2,...,xn],m);`,
  `   `,
  `PARAMETERS: x1,x2,...,xn - names`,
  `            m - non-negative integer`,
  `   `,
  `SYNOPSIS:   `,
  `- The call symmpoly([x1,...,xn],m) returns the symmetric polynomial`,
  `  in the variables x1,...,xn (which may not necessarilly be distinct)`,
  `  having total degree m`,
  `- The call symmpoly([x1,...,xn]); returns a sequence of the symmetric`,
  `  polynomials in x1, ..., xn for m = 0..n`,
  `   `,
  `EXAMPLES:   `,
  `   `,
  `> symmpoly([u,v,w,x],3);`,
  `   `,
  `                         u v w + u v x + u w x + v w x`,
  `> symmpoly([x,y,z]);`,
  `   `,
  `                      1, x + y + z, x y + x z + y z, x y z`
  ):


When the user does  ?symmpoly  the text of your help file will
be printed by Maple in the normal way. I.e. as

  FUNCTION: symmpoly - generate the symmetric polynomials

  CALLING SEQUENCES: symmpoly([x1,x2,...,xn]);  or
                     symmpoly([x1,x2,...,xn],m);

  ... etc. ...


How to create this TEXT object?
-------------------------------
Write the text for the help file in a file as you want it to appear
for the user.  You may find it convenient to copy and edit a Maple help file.
Under Unix, the C program "helptomaple" that you should find in the same
place as "maple" is kept, can be used to create a TEXT object from a file
of text.  For example

  helptomaple "help/text/symmpoly" < symmpolyhelp

outputs the TEXT object for symmpoly above, assigned to the name
`help/text/symmpoly`.

Alternatively, in Maple V Release 2 and later versions of Maple, you can
use the makehelp function from the Maple library.  Suppose the text you
have for your help file is in the file foo.  Then in Maple do

  > readlib(makehelp): # load from the Maple library
  > makehelp(topic, foo):
  > save `help/text/topic`, fooTEXT;

The text file foo is read and converted into a TEXT object and assigned
to the variable `help/text/topic`.  This has been saved into the file
fooTEXT which you can now include in your Maple src code.  Then when the
code loaded into Maple, the on-line help will also be there too.

Remember also to include the examples used in the help file in your test file!