GNU bug report logs - #23060
Elisp Manual: Appendix D.7, comment tips

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 23060 in the body.
You can then email your comments to 23060 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Tianxiang Xiong <tianxiang.xiong <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Elisp Manual: Appendix D.7, comment tips
Date: Fri, 18 Mar 2016 22:47:13 -0500

[Message part 1 (text/plain, inline)]

From: Tianxiang Xiong <tianxiang.xiong <at> gmail.com>
To: bug-gnu-emacs <at> 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 <at> 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

[Message part 2 (text/html, inline)]

Message #8 received at 23060 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Tianxiang Xiong <tianxiang.xiong <at> gmail.com>
Cc: 23060 <at> debbugs.gnu.org
Subject: Re: bug#23060: Elisp Manual: Appendix D.7, comment tips
Date: Mon, 29 Jul 2019 14:47:27 +0200

Tianxiang Xiong <tianxiang.xiong <at> gmail.com> writes:

> 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.

(I'm going through old Emacs bug reports that haven't received any
response.)

I've now added some clarification to the manual in Emacs 27 on this
point.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.