From: Tianxiang Xiong 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 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