Dear all,

I am trying to integrate support for a syntactic construct into the
SMIE setup of a major mode I maintain. The construct is somewhat
unconventional, and I might be at a loss as to where to even start.

In a simplified form the construct looks like this:

begin <identifier> ( <arguments> ) -> <returntype>
> " <docstring> "
> <instructions>
> end


Instructions are separated by semicolons, and both arguments and return
types can be comma-separated lists. The complexity is far from ending
there, but the point at which I cannot get enough control starts here.

A test file and an attempt at defining a corresponding mode are attached,
but it's really not much more than an initial attempt. I'm not even sure
that the grammar is the most appropriate one.

I have the following questions:

- What is/should be the parent of a token? For example, should the grammar
try to ensure that the parents of "->" and the docstring's opening quote
are "begin", or should the rules function take care of navigating to the
"real" syntactic parent?

Also, the documentation makes a difference between the parent and the
opener of a token. Is there a way to find the opener? Can we for example
trust that `backward-up-list` takes us there?

- Is it possible to understand the meaning of the variable `smie--parent`?
Its 2nd and 3rd items are the position and the token corresponding to the
parent, I believe, but what is the car?
And is there a difference between cases where `smie--parent` is nil and
cases where it is unbound?

- How are the calls to the rules function determined? For example, if I
indent before the quote (point 42), the function is called 2 or 3 times:
once with :list-intro, one with :elem args, and once (if the previous was
nil) with :elem basic (incidentally, there seems to be a small mistake in
the documentation there).

I was so far assuming that those cases were just meant for base settings
which are used everywhere, but does this behaviour mean that I should have
the rules function return something different also for :elem, based on
context? Actually that would also be a good reason for not simply having
variables.

Even more confusing, if I indent the line immediately after (point 55), it
seems that the rules function is not called at all. It shouldn't be a
problem for my case, the indentation after the docstring should always be
the one for the docstring, but why does it happen?

Sorry for the possibly naive questions! It's very possible that I have been
digging too far in the wrong direction...

Thanks, best wishes!
Thibaut