Newsgroups: comp.lang.apl
Path: watmath!watserv2.uwaterloo.ca!torn!utnut!cs.utexas.edu!wupost!csus.edu!sfsuvax1.sfsu.edu!vpcsc4
From: vpcsc4@sfsuvax1.sfsu.edu (Emmett McLean)
Subject: Documentation and foreign verbs
Message-ID: <1993May15.231328.18776@csus.edu>
Sender: news@csus.edu
Organization: San Francisco State University
Date: Sat, 15 May 1993 23:13:28 GMT
Lines: 211


Recently Christopher Browne, David Gurr, and myself have been
corresponding about a set up for on line documentation.  Here
is some conversation. Feel free to post if you have suggestions.  

David, BTW, currently does not have posting capabilities but you can email him
at gurr@phase.mcg.edu

CB  The idea was that 10!:0 (or some equivalent) would return a boxed array
CB  looking like:
CB  
CB  10!:0 ''
CB  +------+-------------+
CB  |  0   |  Index      |
CB  +------+-------------+
CB  |  1   |  Cholesky   |
CB  +------+-------------+
CB  |  2   |  SVD        |
CB  +------+-------------+
CB  |  3   |  CDFN       |
CB  +------+-------------+
CB  
CB  Then, individual documentation might be returned by the dyadic version:
CB  0 10!:0 ''
CB  'Index:  List all LinkJ compiled conjunctions'
CB
CB  Since the arguments from 10!:0 would tend to be strings, I suppose that
CB  a function could be built to decompose the index, and generate "friendly"
CB  function names ala:
CB  
CB  Index =. 10!:0
CB  Cholesky =. 10!:1
CB  SVD =. 10!:2
CB  
CB  and so forth. 

CB  This idea could make the numbers irrelevant; I was even thinking of a scheme
CB  that would attach the numbers at run-time rather than compile time.  In
CB  such a case, you'd NEED 10!:0 and some associated utility functions
CB  (probably in normal J).
CB 
CB  I guess that my question would be: "Does the notion of not having fixed
CB  conjunction numbers offend people?"  In that there is no inherent link
CB  between numbers and functions, I don't think it should.
CB  
CB  I'm increasingly thinking that perhaps the documentation really should be
CB  external; perhaps in an indexed file of some sort.

CB  Frankly, I think
CB that's the step AFTER the creation of 10!:0 in the fashion I propose above.
CB Get the first idea to work first; 
 
CB THEN worry about the second.


EM  I think adding a set of functions with English spellings would be against
EM  the spirt of J.
 

EM  And I have an alternative documentation idea.  Suppose you have 
EM  300 !: conjuctions. This forces the user, on average, to read
EM  150 lines of code to find what he wants. Also, up to now, theres been
EM  no mention of a scheme for a user to scroll through the help.
EM
EM  10!:0 should only have about 25 different things in it.  Something 
EM  more like
EM
EM  + -----+-------------+
EM  |  1   |  file I/O   |
EM  | -----+-------------+
EM  |  2   |  workspaces |
EM  +------+-------------+
EM  ......................
EM  |  10  |  index      |
EM  +------+-------------+
EM  |  20  |  lapack     |
EM  +------+-------------+
EM  |  21  |  vfft       |
EM  +------+-------------+
EM  |  30  |  graphics   |
EM  +------+-------------+
EM  |  40  |  statistics |
EM  +------+-------------+
EM
EM
EM  Then 
EM  10!:0 20
EM  would give an overall view of documentation for LAPACK.
EM
EM  1 10!0 20
EM  would give documentation about, say, the complex svd    
EM
EM  Then
EM  20!:1 a
EM  would provide the complex svd for matrix a.
EM
EM
EM  If you use Mike Powell's keyed file utilies the user can apropos as
EM  functions can have multiple keys, for example :
EM
EM  ('svd') 10!:0 ('')
EM
EM  would return the same result as
EM
EM   (1) 10!:0 (20)

EM  Mike Powell's file utilities also allow for reading the documenation
EM  from a source file.  Let's put the doc into a file and set it up so 
EM  as more conjuctions are added it will be easy to add the documentation.

  
DG %% Bounce this off the net?
 
DG I'm thinking that things like LAPACK should be an array P, of boxes.
DG The first box is the items of nameclass 0 in the package, the second is
DG the items of nameclass 1, etc. The first box is a pair of vectors where the first 
DG vector has the names and the second has the arrays.  The second box also has
DG two vectors, the first is names and the second is an agenda of external 
DG verbs, I don't know what the structure that holds conjunctions or adverbs is so maybe
DG packages cannot have conjunctions or adverbs, for the moment.  
DG 
DG Two whereases, 1) I don't know how to make a agenda of external functions without
DG using !: to get the functions first, 2) dynamic loading would be nice for packages.
DG Back to reading the little yellow book.
DG 
DG Documentation is external to the package and is done with ascii files as per 
DG what you and Christopher come up with. -David
DG 
DG 


More on documentation. A letter from David Gurr to me.


EM   Was Christopher suggesting using enlish spellings instead of conjuction
EM   numbers? 

DG Christopher suggested that one could write a function that searched the
DG documentation for the name of the function and call it. 
DG 
DG doc =. 'y.!:0':''
DG packagefunctionslist =. (1&{)@doc
DG fftpack =. 22
DG functionindex =. (packagefunctionslist i. ])
DG bangcolon =. '':'x.!: (functionindex y.)'
DG 
DG so that:
DG 
DG (fftpack bangcolon dfftr) is the real reverse fft (d=double=real)
DG 
DG At least that was my take on what he said.
DG 

...

DG I agree that compiling the documentation is a bad idea.  My reason for
DG having the *names* compiled in to the code is that things like bangcolon
DG would work even if one removed the documentation file completely.  This
DG would be usefull if one was very pressed for RAM or if one wanted to 
DG send someone a "J application" (setting up env variables is a pain in the
DG rump for someone who simply wants to use my code without learning J).
DG 

EM  Until you have a graphical front end, for portability's sake,
EM  I'd say with ascii for now. Also, if the documenation is done
EM  using keyed files then you could implement both ascii and Tekinfo.
EM  Keeping the alternative documentation for each in different files.

DG I think that there is a clever stand alone (no Emacs) hypertext texinfo
DG reader that works on ascii terminals.  If there was texinfo documentation  
DG J could use 0!:0 to call the texinfo reader.  I'm quite pleased with
DG calling Gnuplot via 0!:0, so the texinfo reader might be nice.  Your
DG idea of using keyed files so one can simply swap doc files from ascii
DG to texinfo sounds good.

EM  If you experiment with Mike Powell's programs you may like
EM  my suggestions regarding documenation better. 

DG Don't get me wrong, I like your idea.  I'll do you one better:
DG with your idea, one can document ANY function or variable, not
DG just externals.  How about a dyadic verb that assigns a documentation
DG vector of boxes to a function or variable?  One could use 4!:1
DG to get a list of user defined variables and function, x !:0 to
DG get lists of external variables and functions in package number x, 
DG and one could hack say 127!:0 to be the list of primative functions 
DG and variables. 
DG 
DG Since (4!:1) n returns a list of objects of nameclass n, maybe
DG (packagenumber !:0) n should return the list of objects of 
DG nameclass n in the package.
DG 
DG Here are some questions:  
DG * Should there be a documentation prefix, or sufix
DG   packagenumber !: 0  vs  99 !: packagenumber
DG 
DG * Should there be a single prefix for packages or separate numbers
DG   10!: packagenumber,functionindex vs packagenumber !: functionindex
DG 
DG * Should documentation be for all defined entities or just entities 
DG   from packages
DG 
DG * Should there be two forms of documentation or one
DG   number,number compiled in and comments,credits,manpage in textfile
DG vs. number,number,comments,credits,manpage in textfile
DG 
DG * Should documentation be insertable at runtime via a verb
DG 
DG * Should functions etc be insertable at runtime in packages?
DG 
DG Please add yours.

