gfm-mode and line wrapping

[petere]

I think there is some confusion around what GitHub Flavored Markdown actually is. There are actually two levels:

1. https://help.github.com/articles/github-flavored-markdown/ -- This is the real "GitHub Flavored Markdown", which has things like different behavior for underscores, URL autolinking, and fenced code blocks. This is what most people probably want to use.
2. https://help.github.com/articles/writing-on-github/ -- This is "GitHub Flavored Markdown along with some additional features", which has different newline behavior, task lists, and auto-linked references to issues and such. This only applies to writing issues and comments on the GitHub site.

gfm-mode apparently wants to combine both in one, but that seems wrong. If I write a README.md for including in a GitHub repository, then I do want the URL autolinking and the fenced code blocks, but I don't want the newline-is-significant behavior.

Since only the most die-hard users would use Emacs for writing issues and comments on GitHub, I would remove support for the second variant altogether. In practice, the difference is small, and arguably it is not the job of a major mode to fiddle with visual-line-mode anyway.

[jrblevin]

I take your point about the distinction between the two levels of GitHub Flavored Markdown. Thanks for making the distinction so clear.

Aside from the newline behavior, gfm-mode also now includes support for task lists. I suppose that is harmless for people expecting only the first level, while turning on visual-line-mode is a little more intrusive. Enough people seem to want the second level though, given the number of patches I've received with these features.

How does this for a middle ground? Keep the task list support and other things (maybe nothing else currently) that would typically be invisible to people expecting level 1, but ask users wanting level 2 to add a hook to turn on visual-line-mode if desired. So, the only change would be to remove the following five lines from the gfm-mode definition (and adding a note to the documentation about creating a hook function):

;; Use visual-line-mode if available, fall back to longlines-mode:
(cond ((fboundp 'visual-line-mode)
       (visual-line-mode 1))
      ((fboundp 'longlines-mode)
       (longlines-mode 1)))

I think the next best alternative would be to create a second derived mode, but that seems unnecessary if defaulting to visual-line-mode is the only concern.

[petere]

I think that's reasonable for now. In the long run, it looks like a number of features from GFM are migrating to mainstream markdown (see also CommonMark). So the endgame might to have a bunch of feature toggles and then make several predefined "styles" or something like that, like "classic", "pandoc", "gfm", "commonmark", and so on. Clearly, none of those will want the line-breaking behavior, however.

[jrblevin]

Commit da8bc8a addresses gfm-mode line wrap behavior and updates the documentation regarding GFM- and GitHub-specific features.

1. visual-line-mode is no longer enabled by default in gfm-mode, as discussed above.
2. The documentation been rewritten to explain in detail which GFM/GitHub features are supported by which mode (gfm-mode only, or more broadly in markdown-mode itself).
3. Adds a gfm-mode-hook for those who want to keep visual-line-mode on by default in gfm-mode.

Please double-check what I wrote in the README.md file about the various features. There are some additional caveats, such as (read only) task lists being supported in all Markdown documents since April of 2014, despite not being supported in GFM as originally described.

[jrblevin]

I'm closing this issue since the changes seem to be uncontroversial. If anyone has further thoughts, please feel free to re-open.