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