Margins example in the Elisp manual. [Was: [Emacs-diffs] master 29d1c72: Introduce new value t for compilation-context-lines to eliminate scrolling]

[Alan Mackenzie <acm@muc.de>]

Hello, Eli.

On Sat, Aug 31, 2019 at 14:06:30 +0300, Eli Zaretskii wrote:
> > Date: Sat, 31 Aug 2019 10:53:16 +0000
> > From: Alan Mackenzie <acm@muc.de>
> > Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org

[ .... ]

> > As above, I think a complete example in the "Display Margins" page would
> > be helpful.  I'll get around to formulating this some time (soon?).

> Thanks.

OK, here's a first draught of the example, based on the emacs-26 branch.
As always, comments and criticism are welcome.



diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 55a0a2f924..f2379cc8c7 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -4956,6 +4956,64 @@ Display Margins
 selected window is used.
 @end defun
 
+@menu
+* Margin Example::              A working example of the use of margins.
+@end menu
+
+@node Margin Example
+@subsubsection Margin Example
+@cindex margin example
+@findex foo-mode
+
+The following incomplete, but working, minor mode illustrates one way
+of using margins in your code (@pxref{Display Margins}).  To see it
+working, load the code into your Emacs, then toggle the minor mode on
+with @kbd{M-x foo-mode @key{RET}} in some window.  You will see a two
+character left margin containing the string ''=>'' on the line
+containing point.
+
+@example
+(defvar-local foo-arrow-overlay nil
+  "Overlay with the before-string property of `foo-dummy-string'.
+
+When non-nil, this overlay causes redisplay to display `foo-margin-string'
+at the overlay's start position.")
+
+(defconst foo-margin-string
+  (propertize "=>" 'face 'default)
+  "The string which will appear in the margin in foo mode.")
+
+(defconst foo-dummy-string
+  (propertize ">" 'display
+              `((margin left-margin) ,foo-margin-string))
+  "A string which is only a placeholder for foo-margin-string.
+Actual value is never used, only the text property.")
+
+(defun foo-post-command-hook ()
+  (when foo-arrow-overlay
+    (move-overlay foo-arrow-overlay
+                  (line-beginning-position) (line-beginning-position))))
+(add-hook 'post-command-hook #'foo-post-command-hook)
+
+(defvar-local foo-mode nil)
+(defun foo-mode (&optional arg)
+  "Minor mode to indicate current line by a \"=>\" in the margin."
+  (interactive "P")
+  (setq foo-mode
+        (cond
+         ((null arg) (not foo-mode))
+         ((> arg 0) t)
+         (t nil)))
+  (if foo-mode
+      (progn
+        (setq foo-arrow-overlay (make-overlay (point) (point)))
+        (overlay-put foo-arrow-overlay 'before-string foo-dummy-string)
+        (set-window-margins (selected-window) (+ (or (car (window-margins)) 0) 2)))
+    (delete-overlay foo-arrow-overlay)
+    (setq foo-arrow-overlay nil)
+    (set-window-margins (selected-window) (- (car (window-margins)) 2))))
+@end example
+
 @node Images
 @section Images
 @cindex images in buffers


-- 
Alan Mackenzie (Nuremberg, Germany).