builtin documentation and inverses

[Leopold]

Hi,

it would be awesome if J had builtin documentation.

b.0 provides the ranks of a given verb. how about having

b._ return the description of the moadic version of a verb and

b.__ return the description of the dyadic version?

Since we're talking about b.

Why does b._1 not just provide the (ob-/)inverse of a verb but

basically its full definition? And why does it not do that for

builtin primitives in the same way? It would be cool if

b._1 always just provided the moadic ob-/inverse and a new

b._2 always just provides the dyadic ob-/inverse.

J already has to be able to figure them out somehow,

otherwise it could not run them when asked to...

To get documentation on adverbs, conjunctions, keywords and other

syntax like ) as well as to search all such documentation there could be a verb help which takes a string such that you can

search for ) like so: help')'

regards

[Viktor Grigorov]

Hello, 

I reckon the idea for a hello verb splendid. Clear-cut, perhaps an example, would suffice rather than combing the wiki. 

Feb 9, 2026, 20:58 by leopol...@gmail.com:

> To unsubscribe from this group and stop receiving emails from it, send an email to > forum+un...@jsoftware.com> .
>

[Viktor Grigorov]

Damn autocorrect. I meant help. 

Feb 9, 2026, 21:17 by fo...@jsoftware.com:

> Hello, 
>
> I reckon the idea for a hello verb splendid. Clear-cut, perhaps an example, would suffice rather than combing the wiki. 
>
> Feb 9, 2026, 20:58 by leopol...@gmail.com:
>

[Henry Rich]

We already have Ctrl+F1 in Jqt that provides help on anything.

Your b. is a cute idea, but it works only for verbs, as you note.

And how would the user know to run (+ b. _) or ('/' b. __) ?

Since they would have to learn about the verb from somewhere, it might
as well be an addon.  You could write it!  It feels to me like something
that shouldn't be frozen into the C source code.

Your (b. _2) is problematic.  The inverse (x u^:_1 y) is (x&u)^:_1, i.
e. it doesn't necessarily exist until x is known

What do you mean 'basically the full definition' of a verb?  Would that
be a J model of how the verb works?  That can be pretty complicated. 
The model for (x ; y) is not something you would want to see.

Henry Rich

[Raul Miller]

For reference purposes, I think it might be worth reviving the "dictionary model" of documentation.

The oxford dictionary - arguably one of the best english language dictionaries in existence - is basically a collection of use examples for each word.

More generally, a dictionary definition is a sequence of what a coder might call "conditional cases" - usually arranged so the most commonly used case is first . (and in english language, a single word may have cases with different grammar. ("light" is both a noun and a verb, "some" is both a pronoun and an adjective and an adverb, "before" is both an adverb and a conjunction, etc.)

So, for reference purposes, I think listing various simple implementations which show relevant use cases for the primitive should be adequately comprehensible.

This kind of documentation can and should coexist with tutorial documentation, of course. And, granted, the implementation of the language needs to eliminate all ambiguity. But most users, most of the time, do not want or need something which gets into all the gory details of corner cases. (Though, granted, some people enjoy that kind of documentation.)

-- 

Raul

[Don Guinn]

Don't forget the two-page cheet sheet.

[Raul Miller]

The cheat sheet is nice, but it's more for advanced users who want something to prompt their memory of the language.

-- 

Raul

[A G]

Is this the mentioned cheatsheet: https://sergeyqz.github.io/jcheatsheet/

[Jan-Pieter Jacobs]

I guess people are referring the reference card https://code.jsoftware.com/wiki/User:Viktor_Grigorov/j90xrefsheet

The PDF's are also linked at the top of Nuvoc.

Best regards,

Jan-Pieter

[Raul Miller]

There's multiple J cheatsheets (and there used to be more, but four of
the references I checked are no longer reachable - so that's a hazard
worth considering).

Anyways, in addition to https://sergeyqz.github.io/jcheatsheet/
there's the older
https://code.jsoftware.com/mediawiki/images/5/53/J602_RefCard_color_letter_current.pdf
and there's https://github.com/abo-abo/helm-j-cheatsheet and
https://github.com/dankilman/j-cheat-sheet/blob/master/cheat-sheet.ijs

That said, I guess Sergey's is the most recent, and linguistic drift
is a thing here.

Thanks,

--
Raul

[Leopold]

> What do you mean 'basically the full definition' of a verb?  Would that
> be a J model of how the verb works?  That can be pretty complicated.
> The model for (x ; y) is not something you would want to see.

I just meant that I find it strange that b._1 returns just the inverse
of a primitive -- but the full definition of any other verb:
```
    myverb =: < :. >
    < b._1
>
    myverb b._1
> :.<
```

This inverse is not directly usable, because it is the whole definition
and thus does not know that the inverse is to be invoked:
```
   1 (> :.<) 0 1 2
1 0 0
   1 > 0 1 2
1 0 0
   1 < 0 1 2
0 0 1
```

> Your (b. _2) is problematic.  The inverse (x u^:_1 y) is (x&u)^:_1, i.
> e. it doesn't necessarily exist until x is known

Ok, but does it have to be exactly what will be executed? As shown
above, `b._1` currently does not return exactly what will be executed
anyways, so it's perfectly fine to show the inverse using `u` as a
placeholder.

In fact, placeholder style is preferable and should always be used
including showing the arguments x and y, because it is not always
obvious what is going on. For example, most would assume the inverse of
dyad `+` is simply dyad `-` , thus `x-y`, but it's not
(`_4= 7 +^:_1] 3`), so `(x&u)^:_1 y` is actually a good description,
because it shows that x is first bound to u to make a monad.

There could be a dedicated modifier, say `B.`, which always shows
the correct inverse for the situation it is in; meaning it won't be
called in isolation, but inserted into a sentence where you want to see
the inverse of a verb. Therefore, it does know everything necessary to
compute the inverse because it does not use x to determine its behaviour
(inverse, rank or identity), but rather interprets x and y as the
arguments to its verb u. `7 +B. 3` could show `(7&+)^:_1 (3)` or even
the full resolution of what the inverse does: `-&7`

Anyways, could the behaviour not at least be changed for the following
obvious case (a custom function), since the behaviour of primitives and
custom functions already differs and nobody would use the current
behaviour to create executable inverses anyways:

```
hi =: {{
    echo 'Hi, world', y
:
    echo 'Hi, ', x, y
}} :. {{
    echo 'Bye, world', y
:
    echo 'Bye, ', x, y
}}
'Bob' hi '!'
'Bob' hi ^:_1 '!'
```

...where I would want to see just the inverse function with `b._1` or,
even better, just `{{ echo 'Bye, world', y }}` with `b._1` and
`{{ echo 'Bye, ', x, y }}` with `b._2`.

> Your b. is a cute idea, but it works only for verbs, as you note.
> And how would the user know to run (+ b. _) or ('/' b. __) ?
>
> Since they would have to learn about the verb from somewhere, it might
> as well be an addon.  You could write it!  It feels to me like something
> that shouldn't be frozen into the C source code.

Well, how do you currently expect the user to know about `b.0` to query
the ranks? If he has to look up `b.0`, he could also just look up the
verb itself to read about its ranks. But in reality, one discovers this
verb and remembers it, because one uses it constantly. Nevertheless, an
explicit verb `help` would always take a string and work for everything
(verbs, modifiers, keywords and syntax).

Moreover, this shouldn't be a whole wiki page, but just a sentence or
so, explaining what it does; barely more than a sentence per feature of
the thing would already be sufficient and reduces maintenance to adding
and removing a sentence for new/removed features. It should definitely
be part of the source, because then, it always accurately describes the

version you use. As Raul Miller says:

> There's multiple J cheatsheets (and there used to be more, but four of
> the references I checked are no longer reachable - so that's a hazard
> worth considering).

```
help '+'
help '/'
help ')'
help 'whilst.'

'monadic' help '+'  NB. just show monadic case
'dyadic' help '+'   NB. just show dyadic case
```

My idea was something like bash's `help` command. Why does bash have it,
despite coming with a thorough man-page and tex-info pages? Because
people just want a quick quick answers to simple questions: What does
`{` do in bash? `help {`

> We already have Ctrl+F1 in Jqt that provides help on anything.

That's awesome but it would be even more awesome if one could access
this information from the repl and in your editor.

[Raul Miller]

Hmm...

b._1 produces a noun result, not a verb result. For a verb result, use ^:_1

As for b.0 there's other ways of seeing a verb's rank. For example, to
see that + has a rank of zero, you could use <@+ on a small array (or
you could use <@verb in a small test with any arbitrary verb). That
said, it is wise to read the documentation on the language. (Though,
also, I still habitually reach for verb"verb to see a display of the
verb's rank. But " no longer works that way.)

...

I am also struggling to understand your proposal for B. Could you
perhaps show an example, the way it would appear on the command line?

Anyways, ... maybe I or we need to implement a vestigial help system,
with an eye towards enhancing it later? Something along these lines:

require'general/help'
help '+'
Addition: 2=1+1

Thanks,

--
Raul

[Henry Rich]

Given:

    myv =: +: :. *:

What is myv^:_1 ?  What is myv^:_1^:_1 ?

Stop reading until you have decided your answer.

(spoiler alert)





























   myv^:_1 (5)
25

   myv^:_1^:_1 (5)
10

  The obverse of the obverse of myv is +: .  That's why (b. _1) shows
the obverse explicitly:

   myv b. _1
*: :.+:

 it would be wrong if it were left out.





I think your help verb is a fine idea and if someone writes it I would
vote to include it in stdlib.

Henry Rich

[Don Guinn]

Rather than a definition inside the engine, why not create an add-on script that does this. Then it would be easy to enhance it as the problem is better defined.

[Leopold]

Ok, it makes sense to show the full definition since it is reversed:

if `foo =: one :. two` then `foo b._1` should return `two :. one`

I got confused because I experimented with the `hi` verb above and

it's inverse definition is shown as explicit definition! Since I used

a direct definition and was shown an explicit definition which takes

the function bodies in reverse order, it looked like the order did not change. Thereafter I did not carefully enough inspect the shorter example I posted. My apologies.

> I am also struggling to understand your proposal for B. Could you

> perhaps show an example, the way it would appear on the command line?

The example I gave was `7 +B. 3`, but here is another one which might

be more insightful:

```

   B =: {{)a
    NB. here we know x u y; since there currently is no way to
    NB. show the correct dyadic inverse, I show the monadic one:
    echo x, (u b._1), y
}}
   
   'left' < B 'right'
left>right

```

[Jan-Pieter Jacobs]

Regarding the help addon:

For a quantum computing addon I wrote a while back, I made a help verb: fh (for find help). Maybe someone could use it as inspiration?

https://github.com/jpjacobs/general_qcj/blob/3ba3fc512c47817a1a870672c2a3398817994c12/qcj.ijs#L122

fh =: (help&([#~+./@E.&tolower"1~) : (help#~[ (<.@-:@<:@[ |.^:(0<:*@[) (0#~<:@|@[), |@[ +./\ ]) +./@E.&tolower"1&help@]))

It's rather rudimentory, looking up all lines where string y is present in the help noun, and when called as dyad, gives also x lines of context (centered on each match if x>0 and starting form each match if x<0).

Perhaps my line-based approach is usable, perhaps it's cleaner to work with properly separated chunks of text per primitive.

Anyway, I think it's important to think of content and presentation together with the retrieval.

It would also be really cool if this could become a standard for addons as well in addition to the primitives, looking also through all locales having a specific help-text noun, or through files in the folders of loaded addons (memory mapped, perhaps).

I'm open to collaborate on this project.

Jan-Pieter

[Jan-Pieter Jacobs]

Couldn't help myself starting a help addon...

The content is only for testing purposes so far, but I'll take any pull request for completion.

Try it out with:

install'github:jpjacobs/general_help'

load'general/help'

help'  +' NB. get entry for +

help 'gen';'parts of speech' NB. get parts of speech in section general

help <'# arithmetic'  NB. get section Arithmetic

It sources content from a simple text file ~addons/general/help/help.txt, and gets the right part using cut (<;.1 and <;.2) in combination with E. . I'd want to keep it dependency free (so no regex or mapped files) so it would work on the J playground as well.

The file is divided in sections starting with ### and entries ending with --- (so a section starts with a general entry that can describe it if needed).

The first example has two spaces preceding the +, to avoid noise from all examples that happen to use +, and instead return the "+" entry only. I'm also planning to use "{  term}" and "{### section}" as cross references.

All comments welcome!

Best regards,

Jan-Pieter