On Fri, 22 May 2009, iga Lenari wrote:
< Perhaps on example of copylist, copymatrix and copy we think about
< how functions should be deprecated.
<
< The way I see it, the best way to go about deprecating functions is:
< -creating a new category in help: 'Deprecated functions'
< -move the texi desriptions of deprecated functions (copylist and
< copymatrix in this example) into that category
< -modify the texi to contain
< 'This function is deprecated. Use 'copy' instead.'
<
< Additionaly a new help category could be added:
< 'What's new'
< which contains entries
< 'Maxima 5.19.0'
< 'Maxima 5.20.0'
< ...
< So the user is informed what has changed since the last version - if
< there are new functions available etc (like changes, but more general
< end-user oriented).
<
< On a side note: I browse html Maxima help in wxMaxima. Categories
< have working hyperlinks. What I would think would benefit html help
< greatly is a new 'tag'
< @link{}
< which would create a hyperlink to that symbol's help.
<
< So we would have
< 'See also @link{makelist},.. '
< This would make jumping through html help much faster - easier to
< explore.
I agree in general with these suggestions, without endorsing the example.
In addition to a 'deprecated' list, a list of 'suggested alternatives'
is also required. This would allow bleeding edge users to discover,
experiment with, and find the big bugs in, new code. The reliability and
stability of maxima would be maintained without sacrificing innovation.
Leo
--
The University of Edinburgh is a charitable body, registered in
Scotland, with registration number SC005336.