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

[Alexey Veretennikov]

Hi,

My bad, apparently I've accidentally modified the source file while
browsing around the code.

Thanks, looks like it (help) works now!

Juergen Sauermann <address@hidden> writes:

> Hi Alexey,
>
> that string appears nowhere in my code:
>
> address@hidden:~/projects/juergen/apl-1.7$ grep -r 
> doFooWithExtendedMarkupLanguageSoon .
> address@hidden:~/projects/juergen/apl-1.7$ 
>
> And QuadFunction.cc:120 simply reads:
>
> }
>
> and hasn't changed in the last 4 weeks.
>
> /// Jürgen
>
> On 04/17/2017 08:52 PM, Alexey Veretennikov wrote:
>
>  Hi,
>
> Thanks! This is awesome.
> I can't build this version however:
>
> QuadFunction.cc:120:2: error: 'doFooWithExtendedMarkupLanguageSoon' does not 
> name a type
>  }doFooWithExtendedMarkupLanguageSoon
>   ^
>
>
> Juergen Sauermann <address@hidden> writes:
>
>  Hi,
>
> I have integrated Alexey's help texts into GNU APL. SVN 921.
>
> To display help for an APL primitive say e.g.
>
> ]HELP ⌹
> monadic function: Z ← ⌹ B (Matrix inverse)
> Inverse of matrix B
>
> dyadic function: Z ← A ⌹ B (Matrix divide)
> Solution to system of linear equations Ax = B
>
> To get a list of all primitives use tab-expansion (which also works for other 
> things like filenames,
> user defined and distinguished names, etc, depending on context):
>
> ]HELP <TAB>
> Help topics (APL primitives) are:
> + - × ÷ ⋆ ⍟ ⌈ ⌊ ∣ ∼ ! < ≤ = ≥ > ≠ ∨ ∧ ⍱ ⍲ ○ ? ∊ ⍷ ⍴ ↑ ↓ , \ ⍀ / ⌿ ⍳ ⌹ ⌽ ⊖ ⍕ ⍉
> ⍋ ⍒ ⍎ ⊂ ⊃ ∪ ≡ ≢ ⊥ ⊤ ⊢ ⊣ ⍪ ← → ∇ ⍨ ¨ .
>
> The descriptions deserve some more polishing, in particular for consistency 
> and terminology.
>
> Enjoy,
> 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@hidden> 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
>
>
>
>
>
>

-- 
Br,
/Alexey