Thank you very much for this. I remember having a very hard time finding good, easy-to-use documentation as a beginner. One page that I used often was http://microapl.com/apl_help/ch_020_020.htm
Perhaps it could serve as inspiration / reference for our documentation? Louis > On 16 Apr 2017, at 17:34, Louis Chrétien <lchret...@mac.com> wrote: > > 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> 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 > > > >
