bug#28998: 27.0.50; Man--sections is in reverse order

[Basil L. Contovounesios]

0001-lisp-man.el-Man-build-section-alist-Reverse-sections.patch
Description: Text Data

0002-Rename-Man-build-section-alist.patch
Description: Text Data

# Current behaviour

The inline function Man-build-section-alist in lisp/man.el
populates the buffer-local list Man--sections with the
section names of the current manpage in reverse natural
order (i.e. the common section headers NAME and SEE ALSO end
up somewhere near the end and beginning of Man--sections,
respectively).

# Discussion

In the function Man-goto-section, Man--sections is passed as
a collection to completing-read.  The order of candidates is
irrelevant in a default Emacs configuration, as the
minibuffer help buffer sorts candidates lexicographically by
default.  There is, however, at least one completion
frontend (in my case, ivy.el[1] from ELPA) which displays
candidates in the received order.

AFAICT there is no purpose or benefit to keeping
Man--sections reversed, other than avoiding a call to
nreverse, which AFAIK is quite an efficient operation.

Conversely, keeping the sections in their natural order
(i.e. from (point-min) to (point-max)) both seems more
natural and is more convenient for users of completion
frontends like ivy.el.

Footnotes: 
[1]  https://github.com/abo-abo/swiper

# Patch

I attach two patches.

The first patch implements my suggested reversing of the
reversed Man--sections at the end of
Man-build-section-alist.

The second patch is purely aesthetic in removing some
redundant syntax from Man-build-section-alist and renaming
it to the more apt Man-build-section-list, seeing as
Man--sections is never a list of cons cells.

# Environment

In GNU Emacs 27.0.50 (build 1, x86_64-pc-linux-gnu, X toolkit, Xaw3d scroll 
bars)
 of 2017-10-25 built on thunk
Repository revision: 090f4f157eea6f0d0d13963520f5e05706de142f
Windowing system distributor 'The X.Org Foundation', version 11.0.11905000
System Description:     Debian GNU/Linux testing (buster)

Configured using:
 'configure --prefix=/home/blc/.local
 --enable-locallisppath= --with-mailutils --with-sound=yes
 --with-x-toolkit=lucid --with-xpm --with-jpeg --with-tiff
 --with-gif --with-png --with-rsvg --with-libsystemd
 --with-xml2 --with-imagemagick --with-xft --with-libotf
 --with-m17n-flt --with-toolkit-scroll-bars --with-xaw3d
 --with-xim --with-gpm --with-dbus --with-gsettings
 --with-selinux --with-gnutls --with-zlib --with-modules
 --with-threads --with-file-notification=yes --with-x
 --without-gconf --with-lcms2 'CFLAGS=-flto
 -fomit-frame-pointer -march=native -maes -mavx -mcrc32
 -mf16c -mfpmath=sse -mfsgsbase -mfxsr
 -minline-all-stringops -mmmx -mpclmul -mpopcnt -msahf
 -msse4.2 -mxsave -mxsaveopt -mvzeroupper -O3 -pipe'
 LDFLAGS=-flto'

Configured features:
XAW3D XPM JPEG TIFF GIF PNG RSVG IMAGEMAGICK SOUND GPM DBUS
GSETTINGS NOTIFY ACL LIBSELINUX GNUTLS LIBXML2 FREETYPE
M17N_FLT LIBOTF XFT ZLIB TOOLKIT_SCROLL_BARS LUCID X11
MODULES LIBSYSTEMD LCMS2

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

Major mode: IBuffer

Minor modes in effect:
  projectile-mode: t
  ibuffer-auto-mode: t
  hl-line-mode: t
  magit-wip-before-change-mode: t
  magit-wip-after-apply-mode: t
  magit-wip-after-save-mode: t
  magit-auto-revert-mode: t
  async-bytecomp-package-mode: t
  diff-auto-refine-mode: t
  recentf-mode: t
  ace-window-display-mode: t
  shell-dirtrack-mode: t
  counsel-mode: t
  global-paren-face-mode: t
  xterm-mouse-mode: t
  winner-mode: t
  global-whitespace-mode: t
  display-time-mode: t
  global-subword-mode: t
  subword-mode: t
  save-place-mode: t
  global-hi-lock-mode: t
  hi-lock-mode: t
  engine-mode: t
  delete-selection-mode: t
  display-battery-mode: t
  override-global-mode: t
  blc-dropbox-mode: t
  tooltip-mode: t
  global-eldoc-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  window-divider-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
  transient-mark-mode: t
  auto-save-visited-mode: t

Features:
(dabbrev counsel-projectile projectile grep compile ibuf-ext
ibuffer ibuffer-loaddefs view hl-line git-rebase
magit-bookmark magit-obsolete magit-blame magit-stash
magit-bisect magit-remote magit-commit magit-sequence
magit-notes magit-worktree magit-branch magit-files
magit-refs magit-status magit magit-repos magit-apply
magit-wip magit-log magit-diff smerge-mode magit-core
magit-autorevert autorevert filenotify magit-process
magit-margin magit-mode magit-git magit-section magit-popup
git-commit magit-utils log-edit pcvs-util add-log
with-editor async-bytecomp async dash unfill executable
tramp tramp-compat tramp-loaddefs trampver ucs-normalize
vc-git diff-mode recentf tree-widget bookmark pp shadow sort
footnote face-remap mail-extr gnus-msg gnus-art mm-uu
mml2015 mm-view mml-smime smime dig mailcap gnus-sum
gnus-group gnus-undo gnus-start gnus-cloud nnimap nnmail
mail-source tls gnutls utf7 netrc nnoo parse-time gnus-spec
gnus-int gnus-range gnus-win gnus nnheader emacsbug
eudcb-bbdb bbdb-com crm bbdb bbdb-site timezone eudc
eudc-options-file cus-edit eudc-vars wid-edit message rmc
puny git-annex dired-x dired dired-loaddefs format-spec
rfc822 mml mml-sec epa derived epg gnus-util rmail
rmail-loaddefs xdg mm-decode mm-bodies mm-encode mail-parse
rfc2231 mailabbrev gmm-utils mailheader sendmail rfc2047
rfc2045 ietf-drums mm-util mail-prsvr mail-utils ace-window
avy cl-print debug shell pcomplete comint ansi-color
cus-start cus-load colir color counsel jka-compr esh-util
etags xref project swiper ivy flx ivy-overlay ffap thingatpt
server bug-reference fic-mode fill-column-indicator
paren-face elec-pair xt-mouse winner ring disp-table
whitespace time cap-words superword subword saveplace paren
ibuf-macs highlight-escape-sequences hi-lock time-date
engine-mode delsel battery edmacro kmacro cl-extra help-mode
delight advice zenburn-theme browse-url use-package diminish
bind-key finder-inf tex-site info package easymenu
epg-config url-handlers url-parse auth-source cl-seq eieio
eieio-core cl-macs eieio-loaddefs password-cache url-vars
blc-macs blc-lib easy-mmode rx pcase thunk subr-x map seq
byte-opt gv bytecomp byte-compile cconv cl-loaddefs cl-lib
realpath mule-util tooltip eldoc electric uniquify
ediff-hook vc-hooks lisp-float-type mwheel term/x-win x-win
term/common-win x-dnd tool-bar dnd fontset image regexp-opt
fringe tabulated-list replace newcomment text-mode
elisp-mode lisp-mode prog-mode register page menu-bar
rfn-eshadow isearch timer select scroll-bar mouse jit-lock
font-lock syntax facemenu font-core term/tty-colors frame
cl-generic cham georgian utf-8-lang misc-lang vietnamese
tibetan thai tai-viet lao korean japanese eucjp-ms cp51932
hebrew greek romanian slovak czech european ethiopic indian
cyrillic chinese composite charscript charprop case-table
epa-hook jka-cmpr-hook help simple abbrev obarray minibuffer
cl-preloaded 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 dbusbind inotify lcms2 dynamic-setting
system-font-setting font-render-setting x-toolkit x
multi-tty make-network-process emacs)

Memory information:
((conses 16 545111 235884)
 (symbols 48 46611 7)
 (miscs 40 3990 14356)
 (strings 32 124523 28431)
 (string-bytes 1 3875163)
 (vectors 16 75843)
 (vector-slots 8 2064942 434084)
 (floats 8 566 2272)
 (intervals 56 2459 2469)
 (buffers 992 55))

Thanks,

-- 
Basil