From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Stefan Monnier Newsgroups: gmane.emacs.devel Subject: Indenting docstrings Date: Thu, 10 Mar 2022 15:01:55 -0500 Message-ID: Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="13759"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) Cc: Dominique Unruh To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu Mar 10 21:03:00 2022 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1nSOzz-0003L8-A2 for ged-emacs-devel@m.gmane-mx.org; Thu, 10 Mar 2022 21:02:59 +0100 Original-Received: from localhost ([::1]:41178 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nSOzx-0001yR-Kr for ged-emacs-devel@m.gmane-mx.org; Thu, 10 Mar 2022 15:02:57 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:37212) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nSOz8-0000yZ-LY for emacs-devel@gnu.org; Thu, 10 Mar 2022 15:02:06 -0500 Original-Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]:26527) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nSOz3-0003qc-Ii for emacs-devel@gnu.org; Thu, 10 Mar 2022 15:02:05 -0500 Original-Received: from pmg1.iro.umontreal.ca (localhost.localdomain [127.0.0.1]) by pmg1.iro.umontreal.ca (Proxmox) with ESMTP id C201B10020C; Thu, 10 Mar 2022 15:01:59 -0500 (EST) Original-Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg1.iro.umontreal.ca (Proxmox) with ESMTP id 978DD100182; Thu, 10 Mar 2022 15:01:57 -0500 (EST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1646942517; bh=6cPBrSWIrqMyLYyu4q5vbCkusBCAeplgxrLvCLzFS+c=; h=From:To:Cc:Subject:Date:From; b=JtNjN5TOVNgpdPFXhb1hK/FuGoLO+XHJgk6oJ/uodcM5Sk3y8yWuZTn7H1iKIMLOq gfzHpFmsK8cNKirefhPPuaDobSym2lXjrjyoOfWfnQWQsI4OGOq0w46WjPF37e5+ps r04ywavlPa3iOZq4kbiWMfPw4EZdB4asPx7IBj5DTOZu22Tms9YSVC88kduoBpXg6f LANmHGRWNo5vy0eTiqOJGwWAypr9YAqG8TOCJkQeDugQrVsXxo/ayizgMKewy/EgE1 Zd7pto/bcPHP+oCSxuEmjXprPNwnKdnNT5uQcLhon6aJyi8bRlTY8FhIuLobKUrQsj jOG+MZD7duVUw== Original-Received: from pastel (unknown [45.72.221.51]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id 57BA01203B5; Thu, 10 Mar 2022 15:01:57 -0500 (EST) Received-SPF: pass client-ip=132.204.25.50; envelope-from=monnier@iro.umontreal.ca; helo=mailscanner.iro.umontreal.ca X-Spam_score_int: -42 X-Spam_score: -4.3 X-Spam_bar: ---- X-Spam_report: (-4.3 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, RCVD_IN_DNSWL_MED=-2.3, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:287007 Archived-At: As you probably know, the convention in ELisp is to write the content of docstrings "flush left", since any leading space will be considered part of the actual docstring which then typically leads to ugly results when the docstring is displayed *Help* by `C-h o`. See for example: https://emacs.stackexchange.com/questions/2887/is-there-a-better-way-to-handle-multiline-docstrings-in-elisp For those who can't get used to it, here's a minor mode which will indent the content of docstrings but only on the display, without affecting the actual buffer. Stefan (define-minor-mode elisp-indent-docstrings-mode "If non-nil, docstrings are displayed with extra indentation." :global t (funcall (if elisp-indent-docstrings-mode #'add-hook #'remove-hook) 'emacs-lisp-mode-hook #'elisp--add-indent-docstring-font-lock-rule) (when elisp-indent-docstrings-mode (dolist (buf (buffer-list)) (with-current-buffer buf (when (derived-mode-p 'emacs-lisp-mode) (elisp--add-indent-docstring-font-lock-rule)))))) (defun elisp--add-indent-docstring-font-lock-rule () (font-lock-add-keywords nil '((elisp--indent-docstrings)) 'append) (font-lock-flush) (push 'line-prefix font-lock-extra-managed-props)) (defun elisp--indent-docstrings (limit) (when elisp-indent-docstrings-mode (let ((pos nil)) (while (and (< (point) limit) (setq pos (text-property-any (point) limit 'face 'font-lock-doc-face))) (goto-char pos) (let* ((ppss (syntax-ppss)) (start (or (nth 8 ppss) pos)) (indent (save-excursion (goto-char start) (when (and (eq (char-after) ?\") (not (eq (char-after (1+ (point))) ?\\))) (1+ (current-column))))) (display (when indent (concat ;; "\n" (make-string indent ?\s)))) (end (or (text-property-not-all (point) limit 'face 'font-lock-doc-face) limit))) (if (not display) (goto-char end) (while (re-search-forward "^." end 'move) (put-text-property (match-beginning 0) (1+ (match-beginning 0)) 'line-prefix display))))))) nil)