* [ELPA] New package: compact-docstrings
@ 2016-06-26 17:30 Clément Pit--Claudel
2016-06-29 13:31 ` Clément Pit--Claudel
0 siblings, 1 reply; 4+ messages in thread
From: Clément Pit--Claudel @ 2016-06-26 17:30 UTC (permalink / raw)
To: Emacs developers; +Cc: Stefan Monnier
[-- Attachment #1.1.1: Type: text/plain, Size: 893 bytes --]
Hi emacs-devel,
As a follow-up to the recent discussion on docstring styles (see https://lists.gnu.org/archive/html/emacs-devel/2016-05/msg00240.html), I just pushed the attached package to scratch/compact-docstrings (this is my first push to ELPA, so please excuse potential mistakes).
This very simple package defines a `compact-docstrings-mode' mode mode. When activated, empty lines in docstrings and doc comments are displayed in a different font (currently defaulting to half-height). In practice, this shrinks white space in docstrings to save space, while still clearly separating consecutive paragraphs. The development of this package was suggested by Stefan; I've been using it for about a week now, and it works pretty well for me.
The github page at https://github.com/cpitclaudel/compact-docstrings has a screenshot.
Opinions and advice welcome!
Cheers,
Clément.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.1.2: compact-docstrings.el --]
[-- Type: text/x-emacs-lisp; name="compact-docstrings.el", Size: 3501 bytes --]
;;; compact-docstrings.el --- Shrink blank lines in docstrings and doc comments
;; Copyright (C) 2016 Free Software Foundation, Inc.
;; Author: Clément Pit-Claudel <clement.pitclaudel@live.com>
;; Maintainer: Clément Pit-Claudel <clement.pitclaudel@live.com>
;; URL: https://github.com/cpitclaudel/compact-docstrings
;; Package-Version: 0.1
;; Keywords: convenience, faces, lisp, maint, c
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
;; along with this program. If not, see <http://www.gnu.org/licenses/>.
;;; Commentary:
;; Shrink blank lines in docstrings and doc comments
;;
;; Enable locally with `compact-docstrings-mode':
;; (add-hook 'some-mode-hook #'compact-docstrings-mode)
;;
;; Enable globally (in all programming modes) with
;; (add-hook 'after-init-hook #'global-compact-docstrings--mode)
;;; Code:
(defgroup compact-docstrings nil
"Shrink empty lines in docstrings and doc comments."
:group 'faces)
(defface compact-docstrings-face
'((t :height 0.5))
"Face applied to blank lines in docstrings."
:group 'compact-docstrings)
(defcustom compact-docstrings-only-doc-blocks t
"When nil, also shrink blank lines in regular strings and comments."
:group 'compact-docstrings
:type 'boolean)
(defun compact-docstrings--matcher (bound)
"Find blank line in docstring, looking in point .. BOUND."
(let ((found nil))
(while (and (not found) (re-search-forward "^\\s-*\n" bound t))
(let ((syntax (syntax-ppss)))
(when (and (or (nth 3 syntax) ;; In string
(nth 4 syntax)) ;; In comment
(or (not compact-docstrings-only-doc-blocks)
(let ((face (get-text-property (point) 'face)))
(or (eq face 'font-lock-doc-face)
(and (listp face) (memq 'font-lock-doc-face face))))))
(setq found t))))
found))
(defconst compact-docstrings--keywords
'((compact-docstrings--matcher 0 'compact-docstrings-face prepend)) 'append)
;;;###autoload
(define-minor-mode compact-docstrings-mode
"Shrink empty lines in docstrings and doc comments."
:lighter " compact"
(if compact-docstrings-mode
(font-lock-add-keywords nil compact-docstrings--keywords 'append)
(font-lock-remove-keywords nil compact-docstrings--keywords))
(if (fboundp #'font-lock-flush)
(font-lock-flush)
(with-no-warnings (font-lock-fontify-buffer))))
(defun compact-docstrings--mode-on ()
"Turn on `compact-docstrings-mode', if appropriate."
(when (derived-mode-p major-mode #'prog-mode)
(compact-docstrings-mode)))
;;;###autoload
(defalias 'shrink-docstrings #'compact-docstrings--mode-on)
;;;###autoload
(define-globalized-minor-mode global-compact-docstrings-mode compact-docstrings-mode
compact-docstrings--mode-on
:init-value nil)
(provide 'compact-docstrings)
;;; compact-docstrings.el ends here
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [ELPA] New package: compact-docstrings
2016-06-26 17:30 [ELPA] New package: compact-docstrings Clément Pit--Claudel
@ 2016-06-29 13:31 ` Clément Pit--Claudel
2016-06-29 15:00 ` Artur Malabarba
0 siblings, 1 reply; 4+ messages in thread
From: Clément Pit--Claudel @ 2016-06-29 13:31 UTC (permalink / raw)
To: emacs-devel
[-- Attachment #1.1: Type: text/plain, Size: 370 bytes --]
On 2016-06-26 13:30, Clément Pit--Claudel wrote:
> As a follow-up to the recent discussion on docstring styles (see
> https://lists.gnu.org/archive/html/emacs-devel/2016-05/msg00240.html),
> I just pushed the attached package to scratch/compact-docstrings
> (this is my first push to ELPA, so please excuse potential
> mistakes).
Just merged it into master.
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [ELPA] New package: compact-docstrings
2016-06-29 13:31 ` Clément Pit--Claudel
@ 2016-06-29 15:00 ` Artur Malabarba
2016-06-29 15:12 ` Clément Pit--Claudel
0 siblings, 1 reply; 4+ messages in thread
From: Artur Malabarba @ 2016-06-29 15:00 UTC (permalink / raw)
To: Clément Pit--Claudel, emacs-devel
[-- Attachment #1: Type: text/plain, Size: 957 bytes --]
On 2016-06-26 13:30, Clément Pit--Claudel wrote:
> As a follow-up to the recent discussion on docstring styles (see
> https://lists.gnu.org/archive/html/emacs-devel/2016-05/msg00240.html),
> I just pushed the attached package to scratch/compact-docstrings
> (this is my first push to ELPA, so please excuse potential
> mistakes).
> Just merged it into master.
Hi Clément,
Thanks for this package, it's pretty nice!
I couldn't get it to work on empty lines inside comments though. I set
compact-docstrings-only-doc-blocks to nil, and turned on the minor-mode,
but I don't see any effect on comments (docstrings and regular strings work
fine).
Maybe I misunderstand the scenario? Am I correct in thinking that it should
shrink the empty line in the following example?
```
;;; compact-docstrings.el --- Shrink blank lines in docstrings and doc
comments
;; Copyright (C) 2016 Free Software Foundation, Inc.
```
Cheers,
Artur
[-- Attachment #2: Type: text/html, Size: 1162 bytes --]
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [ELPA] New package: compact-docstrings
2016-06-29 15:00 ` Artur Malabarba
@ 2016-06-29 15:12 ` Clément Pit--Claudel
0 siblings, 0 replies; 4+ messages in thread
From: Clément Pit--Claudel @ 2016-06-29 15:12 UTC (permalink / raw)
To: Artur Malabarba, emacs-devel
[-- Attachment #1.1: Type: text/plain, Size: 1302 bytes --]
On 2016-06-29 11:00, Artur Malabarba wrote:
> Hi Clément,
> Thanks for this package, it's pretty nice!
:)
> I couldn't get it to work on empty lines inside comments though. I
> set compact-docstrings-only-doc-blocks to nil, and turned on the
> minor-mode, but I don't see any effect on comments (docstrings and
> regular strings work fine).
Hey Artur,
At the moment this option only affects languages with multiline comments, such as C++ or OCaml; in Emacs Lisp mode, that option is a no-op :/
> Maybe I misunderstand the scenario? Am I correct in thinking that it
> should shrink the empty line in the following example?
> ```
> ;;; compact-docstrings.el --- Shrink blank lines in docstrings and doc comments
>
> ;; Copyright (C) 2016 Free Software Foundation, Inc.
> ```
That would be a very nice addition, but it doesn't do it yet. The issue is that on that line (syntax-ppss) doesn't tell us that we're in a comment, so we'd need more advanced logic to handle this case properly.
A related question is how to handle the following:
;; Some comment:
;;
;; - a
;; - b
;; - c
In that case the line after "Some comment" isn't even empty; and yet it could be nice to shrink it. This case is probably easier to handle than your example though.
Clément.
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2016-06-29 15:12 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2016-06-26 17:30 [ELPA] New package: compact-docstrings Clément Pit--Claudel
2016-06-29 13:31 ` Clément Pit--Claudel
2016-06-29 15:00 ` Artur Malabarba
2016-06-29 15:12 ` Clément Pit--Claudel
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.