def-lkb/merlin — pull request #1 by gasche (2013-02-17 12:12:10+00:00)
Title: Translate comments from French to English

Here is a list of notes I gathered during the translation.

history.mli:

- the `backward` return type could be `('a t * 'a) option`, rather
than `('a * 'a t) option`, to preserve the left-right spatial
intuition.

- `seek` is hard to specify and use correctly. Is it necessary to
expose it through the interface? It seems that only the derived
`seek_pos` is used outside the module.

- The notion of "current element", "point", and "previous element" are
used interchangeably. In the Sync documentation for example it's
unclear that "the point" means "the last previous element".

There is something fishy in the way "the past" denotes all elements
to the left of the cursor, and is not disjoint with "the present"
which is the previous element. Zipper representations of the form
`'a list * 'a * 'a list` remove this problem, but cannot represent
the empty list which seems crucial here (on typing environment
reset, `let types = Typer.sync state.chunks History.empty`).

outline_utils.mli:

- unsure about the translation of `nesting`

original:

> "let module = … in " permet de définir un module à l'intérieur d'une
> définition, mais le parser d'outline ne sait pas interrompre une définition
> (elle est soit complètement correcte, soit complètement fausse)

translation attempt:

> The construct "let module = … in " allows to define a module
> locally inside a definition, but our outline parser cannot work
> inside a definition (it is either correct as a whole,
> or incorrect).

- it looks like `nesting` is never used outside the module, as the
better enter_sub/leave_sub/emit_top abstraction is used. Could we
not hide `nesting` altogether? (In that case the current comment
should be adapted to explain the role of enter_sub/leave_sub)