[Octave-patch-tracker] [patch #8988] Adding to index.html of manual, installation/loading commands

[Carnë Draug]

Follow-up Comment #16, patch #8988 (project octave):

I will just throw a very different opinion for your consideration.  I don't
think that a package index page should have install and load instructions.

Installing and loading package is a pretty standard and simple job.  So
standard and simple that makes install and load instructions only useful for
very new Octave users.  Anyone else will already know it so adding this
instructions will increase cognitive load of the page.  Note that just because
one already knows the information in those info boxes, it doesn't mean there
is no cost associated.  The info in the boxes still needs to recognized so one
knows it can be ignored.  This would make the page worse for Octave users.

There is also one other reason why even recent users will already now about
pkg.  Without wanting to downplay the importance of the many Forge packages,
I'll guess that new users are more likely to be faced with this issue (install
and loading a package) when dealing with functions from one of the Matlab
toolboxes. In such case, Octave will already show the user a error message
reminding the user first to install (maybe we should show how to actually
install a package instead of just noting is not installed?), and then to load
the package:


octave:1> pkg uninstall statistics

octave:2> pdist
warning: the 'pdist' function belongs to the statistics package from Octave
Forge
which seems to not be installed in your system.

Please read <http://www.octave.org/missing.html> to learn how you can
contribute missing functionality.
warning: called from
    __unimplemented__ at line 524 column 5
error: 'pdist' undefined near line 1 column 1

octave:2> pkg install -forge statistics
For information about changes from previous versions of the statistics
package, run 'news statistics'.

octave:3> pdist
warning: the 'pdist' function belongs to the statistics package from Octave
Forge
which you have installed but not loaded.  To load the package, run 'pkg
load statistics' from the Octave prompt.

Please read <http://www.octave.org/missing.html> to learn how you can
contribute missing functionality.
warning: called from
    __unimplemented__ at line 524 column 5
error: 'pdist' undefined near line 1 column 1


I'd argue that this boils down to: who's the target audience for the index
page of a package? Is it for an Octave user (which will already know about
pkg) to gain information about the package? Or is it for new Octave users that
will start using it? These instructions are only useful for the later and will
just be noise for others.

    _______________________________________________________

Reply to this item at:

  <http://savannah.gnu.org/patch/?8988>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.gnu.org/