Also noticed that the “Find”, “Encode” and “Decode” are defined in two different places of the file, with slightly different wording.
> On Apr 16, 2017, at 16:19, Alexey Veretennikov > <alexey.veretenni...@gmail.com> 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. > > > <Help.def> > > > Juergen Sauermann <juergen.sauerm...@t-online.de > <mailto:juergen.sauerm...@t-online.de>> 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 <loke...@gmail.com>: >> >> 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 >> >> > > -- > Br, > /Alexey --- Louis Chrétien lchret...@mac.com
