bug#19129: 25.0.50; recenter-positions is missing a reference to move-to-window-line-top-bottom

bug#19129: 25.0.50; recenter-positions is missing a reference to move-to-window-line-top-bottom

[H. Dieter Wilhelm]

Hello,

in the documentation for recenter-positions was forgotten that it is
also used in move-to-window-line-top-bottom.  I added below patch as an
illustration.

----------------------------------------------------------------------
Further wish:

I'm missing a separate positional defcustoms for each function -
recenter-top-bottom and move-to-window-line-top-bottom. Because in my
use cases M-r (move-to-window-line-top-bottom) is mostly applied to
pre-adjust the cursor position within the buffer before refining the
movement with an isearch-forward/backward so as to lessen statistically
the chances of multiple hits.  So I'd like to suggest something similar
to

(setq move-to-window-line-positions '(.25 middle .75))

(I'm using M-0 M-r and M-- M-r in the borderline cases as well..)

C-l on the other hand I'm using mostly for inspecting further text
around the cursor context, so

(setq recenter-positions '(top middle bottom)) 

is more appropriate in most of my cases.  (I don't want to suggest a
change of the current default of recenter-positions, just to clarify why
an additional positioning option might be worthwhile to implement)

         Dieter


diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 510cd32..c559308 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,9 @@
+2014-11-20  H. Dieter Wilhelm  <dieter@duenenhof-wilhelm.de>
+
+	Documentation fix in recenter-positions
+	* window.el (recenter-positions): Added missing reference to
+	move-to-window-line-top-bottom
+
 2014-11-20  Michael Albinus  <michael.albinus@gmx.de>
 
         Improve XEmacs compatibility.
diff --git a/lisp/window.el b/lisp/window.el
index 7d76649..a137fb6 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -7370,17 +7370,24 @@ Return non-nil if the window was shrunk, nil otherwise."
 Possible values: `top', `middle', `bottom', integer or float numbers.")
 
 (defcustom recenter-positions '(middle top bottom)
-  "Cycling order for `recenter-top-bottom'.
-A list of elements with possible values `top', `middle', `bottom',
-integer or float numbers that define the cycling order for
-the command `recenter-top-bottom'.
-
-Top and bottom destinations are `scroll-margin' lines from the true
-window top and bottom.  Middle redraws the frame and centers point
-vertically within the window.  Integer number moves current line to
-the specified absolute window-line.  Float number between 0.0 and 1.0
-means the percentage of the screen space from the top.  The default
-cycling order is middle -> top -> bottom."
+  "Cycling order for `recenter-top-bottom' and `move-to-window-line-top-bottom'.
+A list of elements with possible values `top', `middle',
+`bottom', integer or float numbers that define the cycling order
+for the command `recenter-top-bottom' and
+`move-to-window-line-top-bottom'.
+
+Top and bottom destinations are `scroll-margin' lines from the
+true window top and bottom.  For `recenter-top-bottom' position
+`middle' redraws the frame and centers point vertically within
+the window.  Integer number moves current line to the specified
+absolute window-line.  In the case of
+`move-to-window-line-top-bottom' position `middle' moves the
+cursor point vertically to the center of the window.  Integer
+number moves point to the specified absolute window-line.
+
+Float number between 0.0 and 1.0 means the percentage of the
+screen space from the top.  The default cycling order is middle
+-> top -> bottom."
   :type '(repeat (choice
 		  (const :tag "Top" top)
 		  (const :tag "Middle" middle)




In GNU Emacs 25.0.50.2 (x86_64-unknown-linux-gnu, GTK+ Version 2.24.25)
 of 2014-11-20 on vsl28t2g
Repository revision: f5d77aafa9d59c4afb13d744e67a0e4daf3be31a
Windowing system distributor `The X.Org Foundation', version 11.0.11601901
System Description:	Debian GNU/Linux testing (jessie)

Configured features:
XPM JPEG TIFF GIF PNG RSVG IMAGEMAGICK SOUND GPM DBUS GCONF GSETTINGS
NOTIFY GNUTLS LIBXML2 FREETYPE M17N_FLT LIBOTF XFT ZLIB

Important settings:
  value of $LANG: en_GB.UTF-8
  locale-coding-system: utf-8-unix

Major mode: Diff

Minor modes in effect:
  vc-parent-buffer: *vc-dir*
  whitespace-mode: t
  diff-auto-refine-mode: t
  show-paren-mode: t
  electric-pair-mode: t
  icomplete-mode: t
  delete-selection-mode: t
  display-battery-mode: t
  display-time-mode: t
  shell-dirtrack-mode: t
  server-mode: t
  tooltip-mode: t
  global-eldoc-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  buffer-read-only: t
  column-number-mode: t
  line-number-mode: t

Recent messages:
No changes between working revision and workfile
Finding changes in /usr/local/src/emacs/lisp/ChangeLog /usr/local/src/emacs/lisp/window.el...done
Type "q" in help window to restore its previous buffer, C-M-v to scroll help.
Mark set [2 times]
Saved text until " top)
 		  (const :tag "Middle" middle)
"
Quit
Mark set
Making completion list...

Load-path shadows:
~/org/elisp/org-mode/lisp/ob-latex hides /usr/local/src/emacs-25/lisp/org/ob-latex
~/org/elisp/org-mode/lisp/ob-exp hides /usr/local/src/emacs-25/lisp/org/ob-exp
~/org/elisp/org-mode/lisp/ox-md hides /usr/local/src/emacs-25/lisp/org/ox-md
~/org/elisp/org-mode/lisp/org-info hides /usr/local/src/emacs-25/lisp/org/org-info
~/org/elisp/org-mode/lisp/ob-keys hides /usr/local/src/emacs-25/lisp/org/ob-keys
~/org/elisp/org-mode/lisp/org-crypt hides /usr/local/src/emacs-25/lisp/org/org-crypt
~/org/elisp/org-mode/lisp/ob-perl hides /usr/local/src/emacs-25/lisp/org/ob-perl
~/org/elisp/org-mode/lisp/org-pcomplete hides /usr/local/src/emacs-25/lisp/org/org-pcomplete
~/org/elisp/org-mode/lisp/org-rmail hides /usr/local/src/emacs-25/lisp/org/org-rmail
~/org/elisp/org-mode/lisp/ob-asymptote hides /usr/local/src/emacs-25/lisp/org/ob-asymptote
~/org/elisp/org-mode/lisp/ob-makefile hides /usr/local/src/emacs-25/lisp/org/ob-makefile
~/org/elisp/org-mode/lisp/ob-calc hides /usr/local/src/emacs-25/lisp/org/ob-calc
~/org/elisp/org-mode/lisp/org-compat hides /usr/local/src/emacs-25/lisp/org/org-compat
~/org/elisp/org-mode/lisp/ob-css hides /usr/local/src/emacs-25/lisp/org/ob-css
~/org/elisp/org-mode/lisp/ob-ledger hides /usr/local/src/emacs-25/lisp/org/ob-ledger
~/org/elisp/org-mode/lisp/ob-screen hides /usr/local/src/emacs-25/lisp/org/ob-screen
~/org/elisp/org-mode/lisp/org-plot hides /usr/local/src/emacs-25/lisp/org/org-plot
~/org/elisp/org-mode/lisp/org-src hides /usr/local/src/emacs-25/lisp/org/org-src
~/org/elisp/org-mode/lisp/org-mhe hides /usr/local/src/emacs-25/lisp/org/org-mhe
~/org/elisp/org-mode/lisp/org-faces hides /usr/local/src/emacs-25/lisp/org/org-faces
~/org/elisp/org-mode/lisp/ob-js hides /usr/local/src/emacs-25/lisp/org/ob-js
~/org/elisp/org-mode/lisp/org-version hides /usr/local/src/emacs-25/lisp/org/org-version
~/org/elisp/org-mode/lisp/org-docview hides /usr/local/src/emacs-25/lisp/org/org-docview
~/org/elisp/org-mode/lisp/ox-beamer hides /usr/local/src/emacs-25/lisp/org/ox-beamer
~/org/elisp/org-mode/lisp/org-bbdb hides /usr/local/src/emacs-25/lisp/org/org-bbdb
~/org/elisp/org-mode/lisp/org-clock hides /usr/local/src/emacs-25/lisp/org/org-clock
~/org/elisp/org-mode/lisp/ob-sqlite hides /usr/local/src/emacs-25/lisp/org/ob-sqlite
~/org/elisp/org-mode/lisp/ob-sass hides /usr/local/src/emacs-25/lisp/org/ob-sass
~/org/elisp/org-mode/lisp/org-protocol hides /usr/local/src/emacs-25/lisp/org/org-protocol
~/org/elisp/org-mode/lisp/org-habit hides /usr/local/src/emacs-25/lisp/org/org-habit
~/org/elisp/org-mode/lisp/ob-lilypond hides /usr/local/src/emacs-25/lisp/org/ob-lilypond
~/org/elisp/org-mode/lisp/ob-dot hides /usr/local/src/emacs-25/lisp/org/ob-dot
~/org/elisp/org-mode/lisp/ob-comint hides /usr/local/src/emacs-25/lisp/org/ob-comint
~/org/elisp/org-mode/lisp/org-element hides /usr/local/src/emacs-25/lisp/org/org-element
~/org/elisp/org-mode/lisp/org-gnus hides /usr/local/src/emacs-25/lisp/org/org-gnus
~/org/elisp/org-mode/lisp/org-irc hides /usr/local/src/emacs-25/lisp/org/org-irc
~/org/elisp/org-mode/lisp/ob-sql hides /usr/local/src/emacs-25/lisp/org/ob-sql
~/org/elisp/org-mode/lisp/ox-odt hides /usr/local/src/emacs-25/lisp/org/ox-odt
~/org/elisp/org-mode/lisp/org-w3m hides /usr/local/src/emacs-25/lisp/org/org-w3m
~/org/elisp/org-mode/lisp/ob-R hides /usr/local/src/emacs-25/lisp/org/ob-R
~/org/elisp/org-mode/lisp/ob-plantuml hides /usr/local/src/emacs-25/lisp/org/ob-plantuml
~/org/elisp/org-mode/lisp/ob hides /usr/local/src/emacs-25/lisp/org/ob
~/org/elisp/org-mode/lisp/org-table hides /usr/local/src/emacs-25/lisp/org/org-table
~/org/elisp/org-mode/lisp/ob-shen hides /usr/local/src/emacs-25/lisp/org/ob-shen
~/org/elisp/org-mode/lisp/org-inlinetask hides /usr/local/src/emacs-25/lisp/org/org-inlinetask
~/org/elisp/org-mode/lisp/org-capture hides /usr/local/src/emacs-25/lisp/org/org-capture
~/org/elisp/org-mode/lisp/ob-table hides /usr/local/src/emacs-25/lisp/org/ob-table
~/org/elisp/org-mode/lisp/ob-ruby hides /usr/local/src/emacs-25/lisp/org/ob-ruby
~/org/elisp/org-mode/lisp/ob-ditaa hides /usr/local/src/emacs-25/lisp/org/ob-ditaa
~/org/elisp/org-mode/lisp/org-attach hides /usr/local/src/emacs-25/lisp/org/org-attach
~/org/elisp/org-mode/lisp/ob-eval hides /usr/local/src/emacs-25/lisp/org/ob-eval
~/org/elisp/org-mode/lisp/org-footnote hides /usr/local/src/emacs-25/lisp/org/org-footnote
~/org/elisp/org-mode/lisp/ob-octave hides /usr/local/src/emacs-25/lisp/org/ob-octave
~/org/elisp/org-mode/lisp/ob-gnuplot hides /usr/local/src/emacs-25/lisp/org/ob-gnuplot
~/org/elisp/org-mode/lisp/ob-org hides /usr/local/src/emacs-25/lisp/org/ob-org
~/org/elisp/org-mode/lisp/org-agenda hides /usr/local/src/emacs-25/lisp/org/org-agenda
~/org/elisp/org-mode/lisp/org-macro hides /usr/local/src/emacs-25/lisp/org/org-macro
~/org/elisp/org-mode/lisp/ox-icalendar hides /usr/local/src/emacs-25/lisp/org/ox-icalendar
~/org/elisp/org-mode/lisp/ox-latex hides /usr/local/src/emacs-25/lisp/org/ox-latex
~/org/elisp/org-mode/lisp/org-mouse hides /usr/local/src/emacs-25/lisp/org/org-mouse
~/org/elisp/org-mode/lisp/org-timer hides /usr/local/src/emacs-25/lisp/org/org-timer
~/org/elisp/org-mode/lisp/ob-haskell hides /usr/local/src/emacs-25/lisp/org/ob-haskell
~/org/elisp/org-mode/lisp/ob-matlab hides /usr/local/src/emacs-25/lisp/org/ob-matlab
~/org/elisp/org-mode/lisp/org-macs hides /usr/local/src/emacs-25/lisp/org/org-macs
~/org/elisp/org-mode/lisp/ox-publish hides /usr/local/src/emacs-25/lisp/org/ox-publish
~/org/elisp/org-mode/lisp/ox-html hides /usr/local/src/emacs-25/lisp/org/ox-html
~/org/elisp/org-mode/lisp/ob-java hides /usr/local/src/emacs-25/lisp/org/ob-java
~/org/elisp/org-mode/lisp/ob-clojure hides /usr/local/src/emacs-25/lisp/org/ob-clojure
~/org/elisp/org-mode/lisp/org-id hides /usr/local/src/emacs-25/lisp/org/org-id
~/org/elisp/org-mode/lisp/ob-fortran hides /usr/local/src/emacs-25/lisp/org/ob-fortran
~/org/elisp/org-mode/lisp/ob-python hides /usr/local/src/emacs-25/lisp/org/ob-python
~/org/elisp/org-mode/lisp/org-datetree hides /usr/local/src/emacs-25/lisp/org/org-datetree
~/org/elisp/org-mode/lisp/ox-man hides /usr/local/src/emacs-25/lisp/org/ox-man
~/org/elisp/org-mode/lisp/ob-lisp hides /usr/local/src/emacs-25/lisp/org/ob-lisp
~/org/elisp/org-mode/lisp/ox-texinfo hides /usr/local/src/emacs-25/lisp/org/ox-texinfo
~/org/elisp/org-mode/lisp/ob-ocaml hides /usr/local/src/emacs-25/lisp/org/ob-ocaml
~/org/elisp/org-mode/lisp/org-bibtex hides /usr/local/src/emacs-25/lisp/org/org-bibtex
~/org/elisp/org-mode/lisp/ob-maxima hides /usr/local/src/emacs-25/lisp/org/ob-maxima
~/org/elisp/org-mode/lisp/ob-picolisp hides /usr/local/src/emacs-25/lisp/org/ob-picolisp
~/org/elisp/org-mode/lisp/ox-org hides /usr/local/src/emacs-25/lisp/org/ox-org
~/org/elisp/org-mode/lisp/org-indent hides /usr/local/src/emacs-25/lisp/org/org-indent
~/org/elisp/org-mode/lisp/ob-lob hides /usr/local/src/emacs-25/lisp/org/ob-lob
~/org/elisp/org-mode/lisp/org-entities hides /usr/local/src/emacs-25/lisp/org/org-entities
~/org/elisp/org-mode/lisp/org-archive hides /usr/local/src/emacs-25/lisp/org/org-archive
~/org/elisp/org-mode/lisp/org-list hides /usr/local/src/emacs-25/lisp/org/org-list
~/org/elisp/org-mode/lisp/ob-awk hides /usr/local/src/emacs-25/lisp/org/ob-awk
~/org/elisp/org-mode/lisp/org-mobile hides /usr/local/src/emacs-25/lisp/org/org-mobile
~/org/elisp/org-mode/lisp/ox hides /usr/local/src/emacs-25/lisp/org/ox
~/org/elisp/org-mode/lisp/ob-mscgen hides /usr/local/src/emacs-25/lisp/org/ob-mscgen
~/org/elisp/org-mode/lisp/ob-C hides /usr/local/src/emacs-25/lisp/org/ob-C
~/org/elisp/org-mode/lisp/org-loaddefs hides /usr/local/src/emacs-25/lisp/org/org-loaddefs
~/org/elisp/org-mode/lisp/ob-ref hides /usr/local/src/emacs-25/lisp/org/ob-ref
~/org/elisp/org-mode/lisp/org-colview hides /usr/local/src/emacs-25/lisp/org/org-colview
~/org/elisp/org-mode/lisp/ob-emacs-lisp hides /usr/local/src/emacs-25/lisp/org/ob-emacs-lisp
~/org/elisp/org-mode/lisp/ob-tangle hides /usr/local/src/emacs-25/lisp/org/ob-tangle
~/org/elisp/org-mode/lisp/org hides /usr/local/src/emacs-25/lisp/org/org
~/org/elisp/org-mode/lisp/ob-scala hides /usr/local/src/emacs-25/lisp/org/ob-scala
~/org/elisp/org-mode/lisp/ob-io hides /usr/local/src/emacs-25/lisp/org/ob-io
~/org/elisp/org-mode/lisp/org-feed hides /usr/local/src/emacs-25/lisp/org/org-feed
~/org/elisp/org-mode/lisp/ob-scheme hides /usr/local/src/emacs-25/lisp/org/ob-scheme
~/org/elisp/org-mode/lisp/ob-core hides /usr/local/src/emacs-25/lisp/org/ob-core
~/org/elisp/org-mode/lisp/org-install hides /usr/local/src/emacs-25/lisp/org/org-install
~/org/elisp/org-mode/lisp/org-eshell hides /usr/local/src/emacs-25/lisp/org/org-eshell
~/org/elisp/org-mode/lisp/org-ctags hides /usr/local/src/emacs-25/lisp/org/org-ctags
~/org/elisp/org-mode/lisp/ox-ascii hides /usr/local/src/emacs-25/lisp/org/ox-ascii

Features:
(shadow emacsbug log-edit log-view pcvs-util vc-bzr vc-sccs vc-svn
vc-cvs vc-rcs vc-dir ewoc vc vc-dispatcher cus-start cus-load
bug-reference add-log dabbrev etags imenu woman man misearch
multi-isearch vc-git eieio-opt pp help-mode eww mailalias smtpmail
bbdb-message sendmail flyspell ispell nnir gnus-fun flow-fill term ehelp
shr-color color url-queue shr whitespace diff-mode sort smiley gnus-cite
mail-extr gnus-async gnus-bcklg gnus-dup gnus-ml disp-table url-file
url-dired qp mm-archive url-http url-gw url-cache url-auth url-handlers
utf-7 epa-file epa derived epg gnutls network-stream starttls gnus-topic
nnrss xml mm-url url url-proxy url-privacy url-expand url-methods
url-history url-cookie url-domsuf url-util nndraft nnmh nnfolder nnmbox
bbdb-gnus bbdb-mua nnagent nnml gnus-agent gnus-srvr gnus-score
score-mode nnvirtual gnus-msg gnus-art mm-uu mml2015 mm-view mml-smime
smime dig mailcap nntp gnus-cache gnus-sum gnus-group gnus-undo
gnus-start gnus-cloud nnimap nnmail mail-source tls utf7 netrc nnoo
parse-time gnus-spec gnus-int gnus-range message rfc822 mml mml-sec
mm-decode mm-bodies mm-encode mail-parse rfc2231 rfc2047 rfc2045
ietf-drums gmm-utils mailheader gnus-win gnus gnus-ems nnheader
mail-utils wid-edit package epg-config ffap url-parse url-vars paren
elec-pair icomplete delsel dired-x ob-maxima ob-latex ob-sh ob-calc
calc-store calc-trail calc-ext ob-R ob-python ox-koma-letter ox-rss
ox-latex ox-icalendar ox-html ox-ascii ox-publish ox calc calc-loaddefs
calc-macs view mule-util cal-china lunar solar cal-dst cal-bahai
cal-islam cal-hebrew holidays hol-loaddefs appt diary-lib diary-loaddefs
battery time bbdb-print bbdb-com crm mailabbrev bbdb bbdb-site timezone
bbdb-loaddefs org-element org-rmail org-mhe org-irc org-info org-gnus
org-docview doc-view jka-compr image-mode dired org-bibtex bibtex
org-bbdb org-w3m org org-macro org-footnote org-pcomplete org-list
org-faces org-entities noutline outline org-version ob-emacs-lisp ob
ob-tangle ob-ref ob-lob ob-table ob-exp org-src ob-keys ob-comint
ob-core ob-eval org-compat org-macs org-loaddefs find-func cal-menu
calendar cal-loaddefs gnugo maxima maxima-font-lock ido ess-toolbar
ess-mouse mouseme thingatpt browse-url ess-menu ess-swv ess-noweb
ess-noweb-font-lock-mode ess-bugs-l essd-els ess-sas-d ess-sas-l
ess-sas-a ess-sta-d ess-sta-l cc-vars cc-defs make-regexp ess-sp6-d
ess-sp3-d ess-julia ess-r-d ess-tracebug compile tramp tramp-compat
auth-source eieio byte-opt bytecomp byte-compile cl-extra cconv
eieio-core gnus-util mm-util mail-prsvr password-cache tramp-loaddefs
trampver shell pcomplete format-spec ess-roxy advice help-fns easy-mmode
hideshow ess-help info reporter ess-developer ess-r-args ess-s-l
speedbar sb-image ezimage dframe ess ess-inf cl-macs comint ansi-color
ring ess-mode ess-noweb-mode ess-utils cl gv ess-custom executable
easymenu ess-compat ess-site edmacro kmacro cl-loaddefs cl-lib server
time-date tooltip eldoc electric uniquify ediff-hook vc-hooks
lisp-float-type mwheel x-win x-dnd tool-bar dnd fontset image regexp-opt
fringe tabulated-list newcomment elisp-mode lisp-mode prog-mode register
page menu-bar rfn-eshadow timer select scroll-bar mouse jit-lock
font-lock syntax facemenu font-core frame cham georgian utf-8-lang
misc-lang vietnamese tibetan thai tai-viet lao korean japanese hebrew
greek romanian slovak czech european ethiopic indian cyrillic chinese
case-table epa-hook jka-cmpr-hook help simple abbrev minibuffer nadvice
loaddefs button faces cus-face macroexp files text-properties overlay
sha1 md5 base64 format env code-pages mule custom widget
hashtable-print-readable backquote make-network-process dbusbind
gfilenotify dynamic-setting system-font-setting font-render-setting
move-toolbar gtk x-toolkit x multi-tty emacs)

Memory information:
((conses 16 590247 86047)
 (symbols 48 54258 10)
 (miscs 40 742 2065)
 (strings 32 142280 11821)
 (string-bytes 1 4241770)
 (vectors 16 52792)
 (vector-slots 8 1755037 131575)
 (floats 8 1108 1072)
 (intervals 56 13592 366)
 (buffers 976 92)
 (heap 1024 591453 7424))

-- 
Best wishes
H. Dieter Wilhelm
Darmstadt, Germany

bug#19129: 25.0.50; recenter-positions is missing a reference to move-to-window-line-top-bottom

[Drew Adams]

> in the documentation for recenter-positions was forgotten that it is
> also used in move-to-window-line-top-bottom.  I added below patch as
> an illustration.

Actually no. The doc for a function should rarely, if ever, speak
about users (callers) of that function. It should simply say what
the function does, and perhaps what it can be used for if it is
intended for users.

But it should typically not try to list all of its callers, or even
the most important callers.

If this is no longer just a helper for `recenter-top-bottom'
then perhaps reference to even that function can be removed
from the `recenter-positions' doc.

bug#19129: 25.0.50; recenter-positions is missing a reference to move-to-window-line-top-bottom

[H. Dieter Wilhelm]

Drew Adams <drew.adams@oracle.com> writes:

>> in the documentation for recenter-positions was forgotten that it is
>> also used in move-to-window-line-top-bottom.  I added below patch as
>> an illustration.
>
> Actually no. The doc for a function should rarely, if ever, speak
> about users (callers) of that function. It should simply say what
> the function does, and perhaps what it can be used for if it is
> intended for users.
>
> But it should typically not try to list all of its callers, or even
> the most important callers.
>
> If this is no longer just a helper for `recenter-top-bottom'
> then perhaps reference to even that function can be removed
> from the `recenter-positions' doc.

I agree, my impulse went exactly into the opposite and wrong direction
:-/

Hope you'll remove the reference from recenter-positions and please
close the bug (or can I do this as well?)

Thanks for your explanations

       Dieter
-- 
Best wishes
H. Dieter Wilhelm
Darmstadt, Germany

bug#19129: 25.0.50; recenter-positions is missing a reference to move-to-window-line-top-bottom

[Eli Zaretskii]

> From: dieter@duenenhof-wilhelm.de (H. Dieter Wilhelm)
> Date: Thu, 20 Nov 2014 23:14:38 +0100
> 
> in the documentation for recenter-positions was forgotten that it is
> also used in move-to-window-line-top-bottom.  I added below patch as an
> illustration.

Nitpicking: In the future, please try to avoid unnecessarily changing
parts that are unrelated to the proposed patch.  This is especially
true for human-readable text (as opposed to code), because it makes it
very hard to determine where are you actually changing something.

In the case in point, I'm guessing you've filled the paragraphs of the
doc string, which wasn't really necessary, since the lines were of
reasonable length.

Thanks.

bug#19129: 25.0.50; recenter-positions is missing a reference to move-to-window-line-top-bottom

[Eli Zaretskii]

> From: dieter@duenenhof-wilhelm.de (H. Dieter Wilhelm)
> Date: Fri, 21 Nov 2014 00:28:42 +0100
> 
> please close the bug (or can I do this as well?)

Anyone can, by sending an email message to 19129-done@debbugs.gnu.org.
                                                ^^^^^

bug#19129: 25.0.50; recenter-positions is missing a reference to move-to-window-line-top-bottom

[H. Dieter Wilhelm]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: dieter@duenenhof-wilhelm.de (H. Dieter Wilhelm)
>> Date: Thu, 20 Nov 2014 23:14:38 +0100
>> 
>> in the documentation for recenter-positions was forgotten that it is
>> also used in move-to-window-line-top-bottom.  I added below patch as an
>> illustration.
>
> Nitpicking: In the future, please try to avoid unnecessarily changing
> parts that are unrelated to the proposed patch.  This is especially
> true for human-readable text (as opposed to code), because it makes it
> very hard to determine where are you actually changing something.

I understand, I'll try to avoid it.

> In the case in point, I'm guessing you've filled the paragraphs of the
> doc string, which wasn't really necessary, since the lines were of
> reasonable length.

Yes, that's right, but I did it mistakenly because I thought it was
forgotten and that filling a paragraph would be necessary to be in
accordance to Elisp coding conventions.

Now I learned that even though emacs-lisp-docstring-fill-column is 65 an
80 column filling might be acceptable!

Thanks for the pointer.

    Dieter
-- 
Best wishes
H. Dieter Wilhelm
Darmstadt, Germany

bug#19129: 25.0.50; recenter-positions is missing a reference to move-to-window-line-top-bottom

[H. Dieter Wilhelm]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: dieter@duenenhof-wilhelm.de (H. Dieter Wilhelm)
>> Date: Fri, 21 Nov 2014 00:28:42 +0100
>> 
>> please close the bug (or can I do this as well?)
>
> Anyone can, by sending an email message to 19129-done@debbugs.gnu.org.

I see, thanks, I'll do that for #19129.

Please tell me briefly what are you thinking of introducing an extra
defcustom for move-to-window-line-top-bottom?

diff --git a/lisp/window.el b/lisp/window.el
index 91a0e15..8b9c7f5 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -7475,6 +7475,27 @@ cycling order is middle -> top -> bottom."
   :version "23.2"
   :group 'windows)
 
+(defcustom move-to-window-line-positions '(middle top bottom)
+  "Cycling order for `move-to-window-line-top-bottom'.
+A list of elements with possible values `top', `middle', `bottom',
+integer or float numbers that define the cycling order for
+the command `move-to-window-line-top-bottom'.
+
+Top and bottom destinations are `scroll-margin' lines from the true
+window top and bottom.  Middle redraws the frame and centers point
+vertically within the window.  Integer number moves current line to
+the specified absolute window-line.  Float number between 0.0 and 1.0
+means the percentage of the screen space from the top.  The default
+cycling order is middle -> top -> bottom."
+  :type '(repeat (choice
+		  (const :tag "Top" top)
+		  (const :tag "Middle" middle)
+		  (const :tag "Bottom" bottom)
+		  (integer :tag "Line number")
+		  (float :tag "Percentage")))
+  :version "25.1"
+  :group 'windows)
+
 (defun recenter-top-bottom (&optional arg)
   "Move current buffer line to the specified window line.
 With no prefix argument, successive calls place point according
@@ -7515,16 +7536,16 @@ With a prefix argument ARG, acts like `move-to-window-line'.
 
 With no argument, positions point at center of window.
 Successive calls position point at positions defined
-by `recenter-positions'."
+by `move-to-window-line-positions'."
   (interactive "P")
   (cond
    (arg (move-to-window-line arg))	; Always respect ARG.
    (t
     (setq recenter-last-op
 	  (if (eq this-command last-command)
-	      (car (or (cdr (member recenter-last-op recenter-positions))
-		       recenter-positions))
-	    (car recenter-positions)))
+	      (car (or (cdr (member recenter-last-op move-to-window-line-positions))
+		       move-to-window-line-positions))
+	    (car move-to-window-line-positions)))
     (let ((this-scroll-margin
 	   (min (max 0 scroll-margin)
 		(truncate (/ (window-body-height) 4.0)))))

-- 
Best wishes
H. Dieter Wilhelm
Darmstadt, Germany

bug#19129: 25.0.50; recenter-positions is missing a reference to move-to-window-line-top-bottom

[Drew Adams]

> > In the case in point, I'm guessing you've filled the paragraphs of
> > the doc string, which wasn't really necessary, since the lines were
> > of reasonable length.
> 
> Yes, that's right, but I did it mistakenly because I thought it was
> forgotten and that filling a paragraph would be necessary to be in
> accordance to Elisp coding conventions.
> 
> Now I learned that even though emacs-lisp-docstring-fill-column is
> 65 an 80 column filling might be acceptable!

Uh, not really, IMHO.  80-column filling violates the spirit, if not
completely the letter, of the GNU Emacs coding conventions.

What you did, it sounds like (to me), is fix an additional bug: a
doc-string line that was too long.  I would say thank you (while
still letting you know what Eli said about gratuitous changes).
But I don't speak for Emacs Dev.

From (elisp) `Documentation Tips':

* Format the documentation string so that it fits in an Emacs window
  on an 80-column screen.  It is a good idea for most lines to be
                  ^^^^^^
  no wider than 60 characters.  The first line should not be wider
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  than 67 characters or it will look bad in the output of `apropos'.

  You can fill the text if that looks good.  Emacs Lisp mode fills
  documentation strings to the width specified by
  `emacs-lisp-docstring-fill-column'.  However, you can sometimes
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  make a documentation string much more readable by adjusting its
  line breaks with care.  Use blank lines between sections if the
  documentation string is long.

The default value of `emacs-lisp-docstring-fill-column' is 65.

80 is the absolute maximum for a line.  Anything longer than 60 is
to be avoided.  Longer than 65 (`emacs-lisp-docstring-fill-column')
should be justified with good reasons, specific to the particular
case at hand.

The part about filling by default but possibly manually adjusting
line breaks to make things more readable should, IMO, explicitly
call out that what is meant is that you can introduce line breaks
at columns **less** than `emacs-lisp-docstring-fill-column'.

bug#19129: 25.0.50; recenter-positions is missing a reference to move-to-window-line-top-bottom

[Eli Zaretskii]

> Date: Fri, 21 Nov 2014 07:14:15 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 19129@debbugs.gnu.org
> 
> What you did, it sounds like (to me), is fix an additional bug: a
> doc-string line that was too long.

No line of the original doc string was too long.  Please re-read the
patch.

bug#19129: 25.0.50; recenter-positions is missing a reference to move-to-window-line-top-bottom

[Eli Zaretskii]

> From: dieter@duenenhof-wilhelm.de (H. Dieter Wilhelm)
> Cc: 19129@debbugs.gnu.org
> Date: Fri, 21 Nov 2014 11:10:30 +0100
> 
> Please tell me briefly what are you thinking of introducing an extra
> defcustom for move-to-window-line-top-bottom?

I have no opinion about this.  But others might.

Thanks.

bug#19129: 25.0.50; recenter-positions is missing a reference to move-to-window-line-top-bottom

[Drew Adams]

> > What you did, it sounds like (to me), is fix an additional bug: a
> > doc-string line that was too long.
> 
> No line of the original doc string was too long.  Please re-read the
> patch.

I said "it sounds like".  Based on the description I was replying
to, it sounded like text was filled because some line was up to 80
columns wide.

bug#19129: 25.0.50; recenter-positions is missing a reference to move-to-window-line-top-bottom

[H. Dieter Wilhelm]

Drew Adams <drew.adams@oracle.com> writes:

...

> What you did, it sounds like (to me), is fix an additional bug: a
> doc-string line that was too long.  I would say thank you (while
> still letting you know what Eli said about gratuitous changes).
> But I don't speak for Emacs Dev.

...

> The part about filling by default but possibly manually adjusting
> line breaks to make things more readable should, IMO, explicitly
> call out that what is meant is that you can introduce line breaks
> at columns **less** than `emacs-lisp-docstring-fill-column'.

I see, I understand your point but also Elis'.

It makes sense to fill a new documentation and from this possibly
refining the text.  (By the way, the documentation of fill-paragraph has
a line with of 79 chars, please see below ;-).)  But also not to fill
unnecessarily *existing* documentation in patches for a better
readability (as long as there is no explicit directive for normalising
the documentation width for all existing doc strings).

Below is the last third of fill-paragraph's doc.:

⌜
 If `fill-paragraph-function' is nil, return the `fill-prefix' used for filling.

 The REGION argument is non-nil if called interactively; in that
 case, if Transient Mark mode is enabled and the mark is active,
 call `fill-region' to fill each of the paragraphs in the active
 region, instead of just filling the current paragraph.
                                                       ⌟

Thanks
        Dieter
-- 
Best wishes
H. Dieter Wilhelm
Darmstadt, Germany

bug#19129: 25.0.50; recenter-positions is missing a reference to move-to-window-line-top-bottom

[H. Dieter Wilhelm]

-- 
Best wishes
H. Dieter Wilhelm
Darmstadt, Germany