From c17ada78c12cd4c0819d00cbb887c5bb9b25b61f Mon Sep 17 00:00:00 2001 From: Daniel Bergey Date: Fri, 8 Jan 2016 12:14:44 -0500 Subject: [PATCH 1/7] manual: add install section Copied from README This addresses part of https://github.com/haskell/haskell-mode/issues/197 --- doc/haskell-mode.texi | 54 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 52 insertions(+), 2 deletions(-) diff --git a/doc/haskell-mode.texi b/doc/haskell-mode.texi index 924004ff7..2ac900d3f 100644 --- a/doc/haskell-mode.texi +++ b/doc/haskell-mode.texi @@ -126,8 +126,58 @@ Requests}. @node Getting Started @chapter Getting Started -If you are reading this, you have most likely already managed to install -Haskell Mode in one way or another. +@section Quick Installation + +Make sure you have this in your @uref{http://www.gnu.org/software/emacs/manual/html_node/emacs/Init-File.html, init file} (usually `~/.emacs`). If you already have @code{custom-set-variables}, merge its contents: + +@lisp +(require 'package) +(custom-set-variables + ;; custom-set-variables was added by Custom. + ;; If you edit it by hand, you could mess it up, so be careful. + ;; Your init file should contain only one such instance. + ;; If there is more than one, they won't work right. + '(package-archives + (quote + (("gnu" . "http://elpa.gnu.org/packages/") + ("melpa-stable" . "http://stable.melpa.org/packages/"))))) +@end lisp + +Then run emacs, and evaluate: + + @code{M-x package-refresh-contents} + +and then follow by + + @code{M-x package-install RET haskell-mode} + +Voila! @code{haskell-mode} is installed! You should be able to edit Haskell +source code in color now. + +@section Installation - more information + +@code{haskell-mode} supports GNU Emacs versions 23, 24 and upcoming 25 +(snapshot). + +@code{haskell-mode} is available from @uref{http://stable.melpa.org,melpa-stable (releases)} and @uref{http://melpa.org, melpa +(git snapshots)}. + +Other means of obtaining `haskell-mode` include +@uref{https://github.com/dimitri/el-get, el-get}, +@uref{https://github.com/bbatsov/prelude, Emacs Prelude}) and @uref{https://packages.debian.org/search?keywords=haskell-mode, Debian package}. + +Emacs23 requires an the use of @code{cl-lib}. cl-lib.el can be found in +the tests/compat directory. Copy cl-lib.el to your emacs +directory, e.g. ~/.emacs.d directory and put + +@lisp +(add-to-list 'load-path "~/.emacs.d/") +(require 'cl-lib) +@end lisp + +in your .emacs file. + +@section Customizing @cindex customizing Most of Haskell Mode's settings are configurable via customizable From 9e236a99995bcd677843cb2dd17f9804254c6846 Mon Sep 17 00:00:00 2001 From: Daniel Bergey Date: Fri, 8 Jan 2016 12:25:03 -0500 Subject: [PATCH 2/7] manual: haskell-indentation-mode is the default - `haskell-indent-mode` is not recommended, - `haskell-simple-indent` is gone - `haskell-indentation-mode` doesn't do anything special with DEL This updates the manual to reflect changes in: - 10f7da71aefefeddf39ac0d2cd9c5fe144970c6a - ee5effd110cd0f23d36cc391fbba767816dfc83b - 883bfd9e115aff50686cf34a4e8a5ce575c3251f --- doc/haskell-mode.texi | 53 +++++++++++++------------------------------ 1 file changed, 16 insertions(+), 37 deletions(-) diff --git a/doc/haskell-mode.texi b/doc/haskell-mode.texi index 2ac900d3f..637ef755b 100644 --- a/doc/haskell-mode.texi +++ b/doc/haskell-mode.texi @@ -191,9 +191,7 @@ One of the important setting you should customize is the @code{haskell-mode-hook} variable (@pxref{Hooks,,,emacs}) which gets run right after the @code{haskell-mode} major mode is initialized for a buffer. You can customize @code{haskell-mode-hook} by @kbd{M-x -customize-variable @key{RET} haskell-mode-hook}. It's highly recommended -you set up indentation to match your preferences; @xref{Indentation}, -for more details about the indentation modes included with Haskell Mode. +customize-variable @key{RET} haskell-mode-hook}. @c TODO: @c provide basic instructions to get up and running with haskell-mode @@ -393,47 +391,28 @@ block structure@footnote{Haskell also supports braces and semicolons notation for conveying the block structure. However, most Haskell programs written by humans use indentation for block structuring.}. -As GNU Emacs' default indentation function (i.e. @code{indent-relative}) -is not designed for use with Haskell's layout rule, Haskell mode -includes three different indentation minor modes with different -trade-offs: +As GNU Emacs' default indentation function +(i.e. @code{indent-relative}) is not designed for use with Haskell's +layout rule, Haskell mode includes indentation rules adapted to +Haskell. @code{haskell-indentation-mode} binds @key{TAB} to cycle +through possible indentation points based on some clever heuristics. +@key{SHIFT-TAB} cycles in the reverse direction, and @key{RET} moves +to a new line and indents to the first possible indentation level. -@ftable @code +@section haskell-indent-mode -@item haskell-indent-mode - -Intelligent semi-automatic indentation for Haskell's layout rule. The -basic idea is to have @key{TAB} cycle through possibilities indentation -points based on some clever heuristics. - -The rationale and the implementation principles are described in more -detail in the article @cite{Dynamic tabbing for automatic indentation -with the layout rule} published in the Journal of Functional Programming -8.5 (1998). - -@item haskell-indentation-mode - -Improved variation of @code{haskell-indent-mode} indentation -mode. Rebinds @key{RET} and @key{DEL}, so that indentations can be set -and deleted as if they were real tabs. - -@end ftable - -To enable one of these three mutually exclusive indentation schemes, you -just need call one (and only one!) of the @code{*-mode} commands -while in the buffer you want the indentation scheme to be activated for. - -The recommended way is to add one of @code{*-mode} commands to -@code{haskell-mode-hook}. This can be done either by using @kbd{M-x -customize-variable @key{RET} haskell-mode-hook} which provides a -convenient user interface or by adding @emph{one} of the following three -lines to your @file{.emacs} file: +If you want to use the obsolete @code{haskell-indent-mode}, the +recommended way is to load it in @code{haskell-mode-hook}. This can be +done either by using @kbd{M-x customize-variable @key{RET} +haskell-mode-hook} which provides a convenient user interface or by +adding the following line to your @file{.emacs} file: @lisp (add-hook 'haskell-mode-hook 'haskell-indent-mode) -(add-hook 'haskell-mode-hook 'haskell-indentation-mode) @end lisp +Either of these will turn off @code{haskell-indentation-mode}. + @section Interactive Block Indentation By inserting the key bindings for @kbd{C-,} and @kbd{C-.} (these From b64262a93cb90b8a0d8734712783a3f57e78e300 Mon Sep 17 00:00:00 2001 From: Daniel Bergey Date: Fri, 8 Jan 2016 16:43:54 -0500 Subject: [PATCH 3/7] fix typo in code comment --- haskell.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/haskell.el b/haskell.el index 816e79758..876cff753 100644 --- a/haskell.el +++ b/haskell.el @@ -100,7 +100,7 @@ (line-beginning-position))) (list (match-beginning 0) (match-end 0) haskell-ghc-supported-options)) ;; Complete LANGUAGE, a list of completions comes from variable - ;; `haskell-ghc-supported-options' + ;; `haskell-ghc-supported-extensions' ((and (nth 4 (syntax-ppss)) (save-excursion (let ((p (point))) From 5895dc484d0a02c8fdc18028563d6ee2aabea762 Mon Sep 17 00:00:00 2001 From: Daniel Bergey Date: Fri, 8 Jan 2016 16:44:11 -0500 Subject: [PATCH 4/7] readme: link to HTML version of Texinfo manual Not to Github wiki --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 187ef6c5a..7c7839a43 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ For setup instructions, please consult the integrated `haskell-mode` manual which can be accessed after installation via `M-x info-display-manual [RET] haskell-mode`. Alternatively, you can also direct your browser to the -[the online haskell-mode manual](https://github.com/haskell/haskell-mode/wiki) +[the online haskell-mode manual](http://haskell.github.io/haskell-mode/manual/latest/) for setup and user guide. From be6560a459f1fc5c30cb0a22e66873f608ff7706 Mon Sep 17 00:00:00 2001 From: Daniel Bergey Date: Fri, 8 Jan 2016 16:57:25 -0500 Subject: [PATCH 5/7] manual: subsection for stylish-haskell-on-save After the sections on elisp import formatting. --- doc/haskell-mode.texi | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/doc/haskell-mode.texi b/doc/haskell-mode.texi index 637ef755b..92b7d6dca 100644 --- a/doc/haskell-mode.texi +++ b/doc/haskell-mode.texi @@ -308,6 +308,16 @@ which will prompt a list of all modules, either installed modules or local project directory files. Then it'll insert it and then format that module section. +@subsection stylish-haskell + +As an alternative to the elisp functions described above, haskell-mode +can use the program @url{ +http://hackage.haskell.org/package/stylish-haskell, stylish-haskell} +to format imports. You can set this behavior by typing: @kbd{M-x +customize-variable @key{RET} haskell-stylish-on-save}. You can +install @code{stylish-haskell} by running @code{stack install +stylish-haskell}, or if you have not installed @code{stack}, +@code{cabal install stylish-haskell}. @section Completion support From ef96a536cb2f7d29e4493445c9edaa04d36d59b0 Mon Sep 17 00:00:00 2001 From: Daniel Bergey Date: Fri, 8 Jan 2016 17:05:20 -0500 Subject: [PATCH 6/7] manual: update interactive block indentation Recommend transient-mark-mode and TAB, instead of `haskell-move-nested-{left,right}`. Follows gracjan's changes to the wiki in https://github.com/haskell/haskell-mode/wiki/Indentation/_compare/a251fed86858fd9a4f322c385d70fd25b8293ebf As far as I can tell the move-nested functions don't indent enough nested code to preserve valid layout. They also don't have default key bindings. --- doc/haskell-mode.texi | 22 ++-------------------- 1 file changed, 2 insertions(+), 20 deletions(-) diff --git a/doc/haskell-mode.texi b/doc/haskell-mode.texi index 92b7d6dca..dbd4a69a5 100644 --- a/doc/haskell-mode.texi +++ b/doc/haskell-mode.texi @@ -425,26 +425,8 @@ Either of these will turn off @code{haskell-indentation-mode}. @section Interactive Block Indentation -By inserting the key bindings for @kbd{C-,} and @kbd{C-.} (these -bindings are convenient on keyboard layouts where @key{,} and @key{.} -are adjacent keys) as shown below you can interactively de/indent either -the following nested block or, if a region is active while in Transient -Mark Mode (@pxref{Disabled Transient Mark,,,emacs}), de/indent the -active region. - -By using a numeric prefix argument (@pxref{Prefix Command -Arguments,,,elisp}) you can modify the shift-amount; for instance, -@kbd{C-u C-,} increases indentation by 4 characters at once. - -@findex haskell-move-nested-left -@findex haskell-move-nested-right - -@lisp -(eval-after-load "haskell-mode" - '(progn - (define-key haskell-mode-map (kbd "C-,") 'haskell-move-nested-left) - (define-key haskell-mode-map (kbd "C-.") 'haskell-move-nested-right))) -@end lisp +@code{haskell-indentation} can move whole blocks to the left or to the +right. Just mark a block and then use @key{TAB} or @key{S-TAB}. @section Rectangle Commands From 9af63c41944d20a9c90913d49f04b14adede20fe Mon Sep 17 00:00:00 2001 From: Daniel Bergey Date: Fri, 8 Jan 2016 19:39:19 -0500 Subject: [PATCH 7/7] manual: singular, not plural Need to use singular form, because there is only `haskell-indent-mode` left. --- doc/haskell-mode.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/haskell-mode.texi b/doc/haskell-mode.texi index dbd4a69a5..96e87cbe3 100644 --- a/doc/haskell-mode.texi +++ b/doc/haskell-mode.texi @@ -421,7 +421,7 @@ adding the following line to your @file{.emacs} file: (add-hook 'haskell-mode-hook 'haskell-indent-mode) @end lisp -Either of these will turn off @code{haskell-indentation-mode}. +This will turn off @code{haskell-indentation-mode}. @section Interactive Block Indentation