Re: [Bug-apl] Free APL reference documentation, any takers?

[Elias Mårtenson]

Hello Jürgen,

What is the API provided to programmatically access the documentation for a given function?

Whatever the API is, may I suggest that this function also accepts any defined function? The text returned should of course be the content of the comment header (i.e. the comments at the beginning of the function prefixed with two ⍝ symbols. The first line is the summary, while the rest is the long description.

For the benefit of others on the list that doesn't know how that works, here's an example from the SQL library:

∇Z←statement SQL∆Select[db] args

⍝⍝ Execute a select statement and return the result table.

⍝⍝

⍝⍝ The axis parameter indicates the database handle.

⍝⍝

⍝⍝ L is a select statement to be executed. Positional parameters can

⍝⍝ be supplied by specifying a question mark "?" in the statemement.

⍝⍝

⍝⍝ R is an array containing the values for the positional parameters.

⍝⍝ If the array is of rank 2, the statement will be executed multiple

⍝⍝ times with each row being the values for each call.

⍝⍝

⍝⍝ The return value is a rank-2 array representing the result of the

⍝⍝ select statement. Null values are returned as ⍬ and empty strings

⍝⍝ are returned as ''.

  Z←statement ⎕SQL[3,db] args

∇

On 17 April 2017 at 18:37, Juergen Sauermann <address@hidden> wrote:

Hi Alexey,

thanks a lot, I will integrate it into GNU APL.
I will also fix the typos reported by Louis.

/// Jürgen

On 04/16/2017 10:19 PM, Alexey Veretennikov wrote:

Hi Juergen, Elias,

I've converted documentation from GNU APL Emacs mode with permission of
Elias to the format proposed by you.

I've only added additional 2nd argument with the plain symbol/text of
the function/operator to make it easier to parse/lookup.

I've not reviewed this documentation, just converted it to this format
and fixed naming conventions.
Please note what this is just a beginning and I hope myself and
community will work on this file further and hopefully continuously,
refining the open GNU APL documentation.

Juergen Sauermann <address@hiddende> writes:

Hi again,

one more thing. In the IBM documentation the functions are usually denoted in a form like this:

Z←L+R using Z for the result and L and R for the left and right value arguments.

The ISO standard (also mainly written by IBM uses:

Z←A+B using Z for the result and A and B for the left and right value arguments.

My personal preference used to be:

R←A+B using R for the result and A and B for the left and right arguments. I guess this was from
Gilman/Rose, but I am not sure.

The GNU source code uses Z, A, and B as well as LO and RO for the left and right function arguments of
operators.
The info apl also uses A and B. I would therefore like to prose (objections welcome) to use the Z←A f B
for functions
and Z←A (LO op RO) B for e.g. dyadic operators.

Best Regards,
Jürgen Sauermann

On 04/11/2017 08:20 PM, Juergen Sauermann wrote:

 Hi,

 it would be good if someone could provide the help texts. Ideally as a macro called help_def() like
 this:

 help_def(valence, function, short_decription, long_description)

 with: valence: number (0 for niladic, 1 for monadic, or 2 for dyadic)
 function: String literal or just the text
 short_description: String literal or just the text
 long_decription: String literal or just the text

 Please no comma or ; at the end of the macro, and one line per macro (no \ continuation).

 Using a macro as opposed to instantiating struct has the advantage that it is easier to integrate into
 the C++ code of GNU APL.
 It is also easier to read and makes it possible to omit the "" (for function and short_description). Have
 a look at the files with
 extension .def in the GNU APL src directory to see how this type of macro is being used. Like
 src/SystemVariable.def
 which packs together figgerent properties of ⎕-Variables from which later on the )HELP texts for the
 ⎕-variables is derived.
 For example:

 help_def(1, "+B", Conjugate, "Returns the conjugate of B")
 help_def(2, "A+B", Add, "Returns the sum of A and B")

 Finally it would be good if whoever provides this is willing to release it under the GPL like all other GNU
 APL code.
 So all the help_def macros should go into a single file, say Help.def with the usual GPL text at the
 beginning and
 whoever has provided it as the Copyright holder.

 I will then be happy to change the )HELP command to display the texts provided.

 Thanks,
 Jürgen

 On 04/11/2017 04:34 PM, Alexey Veretennikov wrote:

 Hi,

 Indeed I was also thinking on creating such a documentation even in terms of notes for myself. I
 don't always use Emacs for GNU APL (I run it on a device where I'm not able to compile emacs
 but fine to compile GNU APL), so I would be happy to read this documentation from within the
 interpreter, for example using like 
 ]help ⍣
 or 
 ]help ⎕FX

 Br,
 /Alexey

 2017-04-11 10:22 GMT+02:00 Elias Mårtenson <address@hidden>
:

 The Emacs mode for GNU APL contains a (small) reference manual. Really nothing more
 than a short paragraph on most system functions, enough for the integrated documentation
 features to work. It's been pointed out to me that it would be nice if the documentation was
 more complete, particularly with examples of the use of each function in addition to the
 abstract explanation as to what it does. 

 Now, I feel that this documentation doesn't really belong in the Emacs mode. It belongs in
 GNU APL itself. Emacs should simply access this from the APL runtime when needed,

 Thus, I would like to suggest creating an integrated reference documentation inside GNU
 APL itself. We could start with what I have in the Emacs mode, and then add more.

 The following file contains the current documentation in the Emacs mode:

 Each element contains three strings:

 * Invocation type (monadic, dyadic, etc) 
 * Name of the function 
 * One-line summary of the function 
 * (optional) Longer description 

 There are two questions:

 1 Is anybody willing to help out with expanding in the reference documentation?
 2 For Jürgen, are you willing to put this into GNU APL itself instead of keeping it in the
 Emacs mode? 

 Regards,
 Elias