search

Macaulay2 / M2-emacs

Macaulay2 emacs files
GNU General Public License v3.0
5 stars 3 forks source link

Add SimpleDoc major mode #20

Closed d-torrance closed 3 years ago

d-torrance commented 3 years ago

The new indent/newline behavior I introduced in #18 totally broke writing SimpleDoc documentation. Since it doesn't use parentheses, everything is automatically flushed to the far left:

doc ///
Key
foo
Description
Text
foo
///

Of course, users can still get around this by turning off electric-indent-mode, or just using C-j for newlines, but I figured taking a stab at tackling #13 would be nice.

This PR is a first draft a new major mode, M2-simple-doc-mode. It's derived from M2-mode and only defines a new indent-line-function. Users can toggle between the two with M2-toggle-simple-doc-mode (currently bound to C-c C-s, but I'm open to suggestions!) With this mode enabled, tabbing works as expected:

doc ///
  Key
    foo
  Description
    Text
      foo
///

It's not perfect yet (Inputs, Outputs, and CannedExample don't quite work yet), but it's certainly better than the current behavior!

DanGrayson commented 3 years ago

How do you figure this will work, since a buffer can be in just one mode but may contain both Macaulay2 code and SimpleDoc code?

d-torrance commented 3 years ago

How do you figure this will work, since a buffer can be in just one mode but may contain both Macaulay2 code and SimpleDoc code?

By toggling back and forth between the two as necessary using M2-toggle-simple-doc-mode.

DanGrayson commented 3 years ago

Such toggling will be annoying, so people will be tempted to have files that consist entirely of simple doc code. What about a file extension for such files, and add it to auto-mode-alist?

mahrud commented 3 years ago

If this is a separate mode, then please put it in a separate file. It would be good to also separate M2-mode and M2-comint-mode, but I never got around to doing that. Also, I don't like hardcoding the keywords in M2-simple-doc-keywords.

I have to say, my preference is to revert #18. I don't think the simplifications there are worth adding the complexity in this PR. For #13 specifically, I've seen other languages with modes that support special indentation inside docstrings without the need for a separate mode and I think that would be an easier solution. But if you must add a new mode, perhaps M2-doc-mode or M2-docstring-mode is a better name.

mahrud commented 3 years ago

Also, would be great if you could check that the additions don't introduce new linting errors (see https://github.com/melpa/melpa/pull/6984 for links to how to run the checks).

d-torrance commented 3 years ago

I've seen other languages with modes that support special indentation inside docstrings without the need for a separate mode and I think that would be an easier solution.

I like this idea. I'll convert this to a draft for now and play around with it some more.

d-torrance commented 3 years ago

Closing. I plan to work on indentation for SimpleDoc strings later, but in another pull request.