<html>
<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<font face="Helvetica, Arial, sans-serif">Hi again,<br>
<br>
one more thing. In the IBM documentation the functions are usually
denoted in a form like this:<br>
<br>
<b><font face="Courier New, Courier, monospace">Z←L+R </font></b>using
<b>Z</b> for the result and <b>L</b> and <b>R</b> for the left
and right value arguments.<br>
<br>
The ISO standard (also mainly written by IBM uses:<br>
</font><br>
<font face="Helvetica, Arial, sans-serif"><font face="Helvetica,
Arial, sans-serif"><b><font face="Courier New, Courier,
monospace">Z←A+B </font></b>using <b>Z</b> for the result
and <b>A</b> and <b>B</b> for the left and right value
arguments.<br>
<br>
My personal preference used to be</font>:<br>
</font><br>
<font face="Helvetica, Arial, sans-serif"><font face="Helvetica,
Arial, sans-serif"><font face="Helvetica, Arial, sans-serif"><b><font
face="Courier New, Courier, monospace">R←A+B </font></b>using
<b>R</b> for the result and <b>A</b> and <b>B</b> for the
left and right arguments. I guess this was from<br>
Gilman/Rose, but I am not sure.<br>
<br>
The GNU source code uses <b>Z</b>, <b>A</b>, and <b>B</b>
as well as <b>LO</b> and <b>RO</b> for the left and right
function arguments of operators.<br>
The <b>info apl</b> also uses <b>A</b> and <b>B</b>. I
would therefore like to prose (objections welcome) to use the
<font face="Courier New, Courier, monospace"><b>Z←A f </b></font><b>B</b>
for functions<br>
and <b>Z←A (LO op RO) B</b> for e.g. dyadic operators.<br>
<br>
Best Regards,<br>
Jürgen Sauermann<br>
<br>
<br>
<br>
</font></font><br>
<br>
<br>
</font><br>
<div class="moz-cite-prefix">On 04/11/2017 08:20 PM, Juergen
Sauermann wrote:<br>
</div>
<blockquote
cite="mid:9a4a0c70-b3ac-0e84-2b0b-***@t-online.de"
type="cite">
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<font face="Helvetica, Arial, sans-serif">Hi,<br>
<br>
it would be good if someone could provide the help texts.
Ideally as a macro called <b>help_def()</b> like this:<br>
<br>
<b>help_def(valence, function, short</b><b>_</b><b>decription,
long</b><b>_description)</b><b><br>
</b><br>
with: valence: number (0 for niladic, 1 for monadic, or 2 for
dyadic)<br>
function: String literal</font><font face="Helvetica, Arial,
sans-serif"> or just the text</font><br>
<font face="Helvetica, Arial, sans-serif">short_description:
String literal or just the text</font><br>
<font face="Helvetica, Arial, sans-serif">long_decription: String
literal</font><font face="Helvetica, Arial, sans-serif"><font
face="Helvetica, Arial, sans-serif"> or just the text<br>
<br>
Please no comma or ; at the end of the macro, and one line per
macro (no \ continuation).<br>
<br>
Using a macro as opposed to instantiating struct has the
advantage that it is easier to integrate into the C++ code of
GNU APL.<br>
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<br>
extension <b>.def</b> in the GNU APL <b>src</b> directory to
see how this type of macro is being used. Like <b>src/SystemVariable.def</b><b><br>
</b>which packs together figgerent properties of ⎕-Variables
from which later on the )HELP texts for the ⎕-variables is
derived.<br>
For example:<br>
<br>
</font></font><b><font face="Courier New, Courier, monospace">help_def(1,
"+B", Conjugate, <span class="pl-s"><span class="pl-pds">"</span>Returns
the conjugate of B<span class="pl-pds">")</span></span><br>
</font></b><span class="pl-s"><span class="pl-pds"><b><font
face="Courier New, Courier, monospace">help_def(2, "A+B",
Add, </font></b><span class="pl-s"><b><font
face="Courier New, Courier, monospace"><span
class="pl-pds">"</span>Returns the sum of A and B</font></b><span
class="pl-pds"><b><font face="Courier New, Courier,
monospace">")</font></b><br>
<br>
Finally it would be good if whoever provides this is
willing to release it under the GPL like all other GNU APL
code.<br>
So all the <b>help_def</b> macros should go into a single
file, say <b>Help.def </b>with the usual GPL text at the
beginning and<br>
whoever has provided it as the Copyright holder.<br>
<br>
I will then be happy to change the )HELP command to
display the texts provided.<br>
<br>
Thanks,<br>
Jürgen<br>
<br>
<br>
</span></span></span></span><br>
<font face="Helvetica, Arial, sans-serif"> </font>
<div class="moz-cite-prefix">On 04/11/2017 04:34 PM, Alexey
Veretennikov wrote:<br>
</div>
<blockquote
cite="mid:CAKE5LL6Y5mknDEe49F6ZHxjwAk+xxc4gifjwOn+OPO04owqa-***@mail.gmail.com"
type="cite">
<div dir="ltr">
<div>
<div>Hi,<br>
<br>
</div>
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 <br>
]help ⍣<br>
</div>
<div>or <br>
</div>
<div>]help ⎕FX<br>
<br>
</div>
<div>Br,<br>
</div>
<div>/Alexey<br>
</div>
<div><br>
</div>
</div>
<div class="gmail_extra"><br>
<div class="gmail_quote">2017-04-11 10:22 GMT+02:00 Elias
Mårtenson <span dir="ltr"><<a moz-do-not-send="true"
href="mailto:***@gmail.com" target="_blank">***@gmail.com</a>></span>:<br>
<blockquote class="gmail_quote" style="margin:0 0 0
.8ex;border-left:1px #ccc solid;padding-left:1ex">
<div dir="ltr">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.
<div><br>
</div>
<div>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,</div>
<div><br>
</div>
<div>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.</div>
<div><br>
</div>
<div>The following file contains the current
documentation in the Emacs mode:</div>
<div><br>
</div>
</div>
</blockquote>
</div>
</div>
</blockquote>
<br>
<blockquote
cite="mid:CAKE5LL6Y5mknDEe49F6ZHxjwAk+xxc4gifjwOn+OPO04owqa-***@mail.gmail.com"
type="cite">
<div class="gmail_extra">
<div class="gmail_quote">
<blockquote class="gmail_quote" style="margin:0 0 0
.8ex;border-left:1px #ccc solid;padding-left:1ex">
<div dir="ltr">
<div><br>
</div>
<div>Each element contains three strings:</div>
<div>
<ul>
<li>Invocation type (monadic, dyadic, etc)</li>
<li>Name of the function</li>
<li>One-line summary of the function</li>
<li>(optional) Longer description</li>
</ul>
</div>
<div>There are two questions:</div>
<div>
<ol>
<li>Is anybody willing to help out with expanding in
the reference documentation?<br>
</li>
<li>For Jürgen, are you willing to put this into GNU
APL itself instead of keeping it in the Emacs
mode?</li>
</ol>
<div>Regards,</div>
</div>
<div>Elias</div>
</div>
</blockquote>
</div>
<br>
</div>
</blockquote>
<br>
</blockquote>
<br>
</body>
</html>