Peoblem with the manual (was: Square pulse function?)

On Fri, 2008-05-30 at 12:03 +0000, Paul wrote:
> > (%i15)  load("orthopoly")$
> > (%i16) unit_step(0.5);
> > (%o16)                       1
> 
> Okay, thanks. Pity that "? unit_step" didn't mention this.

This brings up a general problem we currently have with the
documentation. When a function makes part of an additional package; if
you happen to look up the documentation for that package, it will tell
you that you need to load it in order to use any of its functions.

But if you jump directly into the section for a function or variable
inside a contributed package, you will miss that part. Try for instance:
  ? poly_primitive_part
it will show you an example; if you repeat that example it will fail,
unless you have already loaded package grobner.

Some contributors have solved that problem by including an example for
every single variable and function in their packages, and starting those
examples with the load command. But including an example, with at least
two lines, for every variable and function could be annoying in some
cases. Others have had their packages loaded automatically when a
function in those packages is used for the first time.

Should we start writing/rewriting examples in the texinfo files for all
additional packages? or should we add more auto-loading rules for all
additional packages? for some of them, which appear to be broken, this
would be a bad idea. Should we do a combination of the two things?
I'd like to hear opinions.

Regards,
Jaime