Subject: 24.5.50; Elisp Manual: Appendix D.7, comment tips
Date: Fri, 18 Mar 2016 22:46:01 -0500
--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:
== 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:
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