RE: antlr-mode.el - need some support by python.el

[Wedler, Christoph]

>> +PREVIOUS-CHUNKS, if non-nil, provides the indentation engine of
>> +the sub mode with the virtual context of the code chunk.  Valid
>> +values are:
>> +
>> + - A string containing code which the indentation engine can
>> +   consider as standing in front of the code chunk.  For example,
>> +   it can contain a function header to make the code chunk
>> +   being correctly indented as a function body.
>> +
>> + - A function called with the start position of the current
>> +   chunk.  It will return either the region of the previous chunk
>> +   as \(PREV-START . PREV-END) or nil if there is no further
>> +   previous chunk.")

> This is very unclear, so I'm not sure how an inner-mode could make use
> of it.

Many modes use more than the current line / code chunk in their
indentation calculations.  For example, in `c-guess-basic-syntax', the
outer language constructs are also considered.  If the indentation
engine of the inner mode just see the code chunks, there is a potential
problem...

Code chunks in grammars (like ANTLR) are valid sub constructs (basically
like a function bodies), but are not necessarily valid top/root constructs
according to the grammar of the inner mode.  This might affect the
indentation calculation - and if so, the inner mode hopefully uses the
PREVIOUS-CHUNKS specification, e.g. `c-guess-basic-syntax' could use it
to compute an initial value for `c-syntactic-context'.

In the literate programming case (which I'm less interested in, but you
and Fabián seemed to be), the code chunks are not necessary even valid
sub constructs, e.g. a code chunk could just be the "else" clause.  Here,
it might be even essential that the indentation engine of the inner mode
knows the previous code chunks.

> Who (and how) decides what the values will be?  The outer-mode
> or the inner-mode?

The outer mode (like the rest of the value) - after all, the preceding
part of the docstring was "the major mode of such a main language [...]
is supposed to bind this variable"

>> +(defun prog-widen ()
>> +  "Remove restrictions (narrowing) from current code chunk or buffer.
>> +This function should be used instead of `widen' in any function
>> +used by the indentation engine to make it respect the value
>> +`prog-indentation-context'.

> I don't see a need for "should" here.

What else - a "must" (This function is to be used)?

>> +  (widen)
>> +  (let ((chunk (cadr prog-indentation-context)))
>> +    (when chunk
>> +      (narrow-to-region (car chunk) (or (cdr chunk) (point-max))))))

> Better do

>     (let ((chunk (cadr prog-indentation-context)))
>       (if chunk
>           (narrow-to-region (car chunk) (or (cdr chunk) (point-max)))
>         (widen))))

OK, I didn't know whether I should rely on the behavior (defined in
src/editfns.c) that narrow-to-region might also `widen'...

This behavior could be mentioned in the docstring  - other possibilties
would be:
 - (when (or (> (point-min) start) (< (point-max) end)) (error ...))
 - (narrow--internal (max (point-min) start) (min (point-max) end)

-- Christoph