bug#23060: Elisp Manual: Appendix D.7, comment tips

[Tianxiang Xiong <tianxiang.xiong@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 9349 bytes --]

From: Tianxiang Xiong <tianxiang.xiong@gmail.com>
To: bug-gnu-emacs@gnu.org
Subject: 24.5.50; Elisp Manual: Appendix D.7, comment tips
Date: Fri, 18 Mar 2016 22:46:01 -0500
Message-ID: <87egb7yvt2.fsf@asus.eau.wi.charter.com>
--text follows this line--

---------------------------------------------------------------------------

== Problem ==

The Emacs Lisp Reference Manual's Appendix D.7 does not give a good
description of what triple and quadruple semicolon comments should be
used for.

For triple semicolons, the manual says:

    Comments that start with three semicolons, ‘;;;’, should start at
    the left margin. We use them for comments which should be considered
    a “heading” by Outline minor mode.

For quadruple semicolons, the manual says:

    Comments that start with four semicolons, ‘;;;;’, should be aligned
    to the left margin and are used for headings of major sections of a
    program. For example:

    ;;;; The kill ring

This does not make clear what the difference between the two are.

As it turns out, 3-and-more semi-colons stand for headings, where the
more semi-colons you put the deeper the nesting of the heading. E.g.

    ;;; Main heading
    ;;;; Sub heading
    ;;;;; Sub sub heading
    ;;;; Another sub heading
    ;;; Next main heading

See this Emacs StackExchange answer by Stefan for more information:
http://emacs.stackexchange.com/a/21061/10269

== Solution ==

I suggest that the description for three semicolons be changed to:

    Comments that start with three semicolons, ‘;;;’, are considered
    top-level headings by Outline minor mode.

    Four or more semicolons can be used as subheadings in hierarchical
    fashion. E.g.

    ;;; Main heading
    ;;;; Sub heading
    ;;;;; Sub sub heading
    ;;;; Another sub heading
    ;;; Next main heading

    These comments should be used to break Emacs Lisp code into sections.

A link to "Outline minor mode" in the Emacs manual would be useful:
https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html

The section for four semicolons can be elided.

---------------------------------------------------------------------------

In GNU Emacs 24.5.50.1 (x86_64-unknown-linux-gnu, GTK+ Version 3.14.6)
 of 2015-12-02 on asus
Repository revision: a27ae9d7650a1230d4359eaf0a949f827315a6d2
Windowing system distributor `Fedora Project', version 11.0.11602901
System Description: Fedora release 21 (Twenty One)

Important settings:
  value of $LANG: en_US.utf8
  value of $XMODIFIERS: @im=ibus
  locale-coding-system: utf-8-unix

Major mode: Org

Minor modes in effect:
  flyspell-mode: t
  recentf-mode: t
  yas-global-mode: t
  yas-minor-mode: t
  show-smartparens-global-mode: t
  show-smartparens-mode: t
  smartparens-global-mode: t
  smartparens-mode: t
  projectile-global-mode: t
  projectile-mode: t
  popwin-mode: t
  pdf-occur-global-minor-mode: t
  global-page-break-lines-mode: t
  page-break-lines-mode: t
  display-battery-mode: t
  display-time-mode: t
  global-linum-mode: t
  linum-mode: t
  helm-descbinds-mode: t
  helm-mode: t
  shell-dirtrack-mode: t
  async-bytecomp-package-mode: t
  global-edit-server-edit-mode: t
  company-quickhelp-mode: t
  global-company-mode: t
  company-mode: t
  tooltip-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  global-prettify-symbols-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  column-number-mode: t
  line-number-mode: t
  visual-line-mode: t
  transient-mark-mode: t

Recent messages:
[yas] Loading for `html-mode', just-in-time: (lambda nil
(yas--load-directory-1 (quote
/home/txx/.emacs.d/elpa/yasnippet-20160226.1359/snippets/html-mode) (quote
html-mode)))!
[yas] Loading snippet files from
/home/txx/.emacs.d/elpa/yasnippet-20160226.1359/snippets/html-mode
[yas] Loading for `html-mode', just-in-time: (lambda nil
(yas--load-directory-1 (quote /home/txx/.emacs.d/snippets/html-mode) (quote
html-mode)))!
[yas] Loading snippet files from /home/txx/.emacs.d/snippets/html-mode
[yas] Loading for `nxml-mode', just-in-time: (lambda nil
(yas--load-directory-1 (quote
/home/txx/.emacs.d/elpa/yasnippet-20160226.1359/snippets/nxml-mode) (quote
nxml-mode)))!
[yas] Loading snippet files from
/home/txx/.emacs.d/elpa/yasnippet-20160226.1359/snippets/nxml-mode
<mouse-7> is undefined
byte-code: Beginning of buffer [11 times]
Search failed. No matching tag found. [4 times]
(No changes need to be saved)
Quit

Load-path shadows:
/home/txx/.emacs.d/elpa/helm-20160303.1125/helm-multi-match hides
/home/txx/.emacs.d/elpa/helm-core-20160303.1321/helm-multi-match

Features:
(shadow sort emacsbug message rfc822 mml mml-sec mm-decode mm-bodies
mm-encode mailabbrev gmm-utils mailheader sendmail mail-utils
semantic/find helm-semantic helm-imenu smartparens-html sgml-mode
emmet-mode rainbow-mode color css-mode smie whitespace helm-command
mail-extr macrostep-c subr-x cmacexp cc-langs cc-mode cc-fonts cc-guess
cc-menus cc-cmds cc-styles cc-align cc-engine cc-vars cc-defs ido
helm-pages eieio-opt speedbar sb-image ezimage dframe helm-elisp
helm-eval edebug tabify vc-git flyspell ispell org-element org-rmail
org-mhe org-irc org-info org-gnus org-docview doc-view org-bibtex bibtex
org-bbdb org-w3m recentf tree-widget network-stream starttls image-file
winner server disp-table company-oddmuse company-keywords company-etags
company-gtags company-dabbrev-code company-dabbrev company-files
company-capf company-cmake company-xcode company-clang company-semantic
company-eclim company-template company-css company-nxml company-bbdb
company-tern s ucs-normalize dash-functional tern url-http tls url-auth
mail-parse rfc2231 rfc2047 rfc2045 ietf-drums url-gw json yasnippet
help-mode cl zenburn-theme smartparens-config smartparens
helm-projectile projectile grep dash popwin pdf-occur ibuf-ext ibuffer
tablist tablist-filter semantic/wisent/comp semantic/wisent
semantic/wisent/wisent semantic/util-modes semantic/util semantic
semantic/tag semantic/lex semantic/fw mode-local cedet pdf-isearch
let-alist pdf-misc imenu pdf-tools pdf-view mule-util jka-compr
pdf-cache pdf-info tq pdf-util image-mode page-break-lines toc-org ert
ewoc debug ob-scheme ob-lisp ob-clojure org org-macro org-footnote
org-pcomplete org-list org-faces org-entities 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 battery time linum helm-descbinds helm-mode
helm-files rx image-dired tramp tramp-compat tramp-loaddefs trampver
shell pcomplete format-spec dired-x dired-aux ffap helm-buffers
helm-elscreen helm-tags helm-bookmark helm-adaptive helm-info bookmark
helm-locate helm-grep helm-regexp helm-plugin helm-external helm-net xml
url url-proxy url-privacy url-expand url-methods url-history url-cookie
url-domsuf url-util url-parse auth-source gnus-util time-date mm-util
mail-prsvr password-cache url-vars mailcap helm-utils helm-help
helm-types helm helm-source eieio eieio-core helm-multi-match helm-lib
dired helm-config helm-easymenu cl-macs gv async-bytecomp async
edit-server company-quickhelp pos-tip slime-company company pcase
byte-opt slime-fancy slime-trace-dialog slime-fontifying-fu
slime-package-fu slime-references slime-compiler-notes-tree advice
slime-scratch slime-presentations bridge slime-macrostep macrostep
slime-mdot-fu slime-enclosing-context slime-fuzzy slime-fancy-trace
slime-fancy-inspector slime-c-p-c slime-editing-commands slime-autodoc
eldoc help-fns slime-repl slime-parse bytecomp byte-compile cconv slime
compile etags arc-mode archive-mode noutline outline easy-mmode pp
comint ansi-color hyperspec thingatpt browse-url cus-edit cus-start
cus-load wid-edit cl-extra edmacro kmacro hydra ring lv cl-loaddefs
cl-lib tex-site slime-autoloads info easymenu package epg-config tooltip
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
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 644748 319085)
 (symbols 48 56931 22)
 (miscs 40 9000 8309)
 (strings 32 145376 110188)
 (string-bytes 1 4061887)
 (vectors 16 80290)
 (vector-slots 8 2066368 392321)
 (floats 8 1407 2076)
 (intervals 56 10892 5139)
 (buffers 960 68)
 (heap 1024 161313 182332))

-- 
Tianxiang Xiong

[-- Attachment #2: Type: text/html, Size: 11948 bytes --]