GNU bug report logs -
#30998
27.0.50; The Help for defclass with multiline documentation is very hard to read
Previous Next
Reported by: Xu Chunyang <mail <at> xuchunyang.me>
Date: Fri, 30 Mar 2018 19:39:01 UTC
Severity: minor
Tags: confirmed
Found in version 27.0.50
Fixed in version 28.1
Done: Lars Ingebrigtsen <larsi <at> gnus.org>
Bug is archived. No further changes may be made.
To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 30998 in the body.
You can then email your comments to 30998 AT debbugs.gnu.org in the normal way.
Toggle the display of automated, internal messages from the tracker.
Report forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#30998
; Package
emacs
.
(Fri, 30 Mar 2018 19:39:01 GMT)
Full text and
rfc822 format available.
Acknowledgement sent
to
Xu Chunyang <mail <at> xuchunyang.me>
:
New bug report received and forwarded. Copy sent to
bug-gnu-emacs <at> gnu.org
.
(Fri, 30 Mar 2018 19:39:01 GMT)
Full text and
rfc822 format available.
Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):
I don't know if defclass requires that :documentation must occupies just
a single line. Helm uses many multiple lines string for that slot, please see
https://github.com/emacs-helm/helm/blob/6a34d57f416e4194e6d3207b558d3a00cdf2b955/helm-source.el#L54
'C-h f helm-source' is very hard to read, the following is a part of *Help*
#+BEGIN_EXAMPLE
Instance Allocated Slots:
Name Type Default Doc
———— ———— ——————— ———
name t nil The name of the source.
A string which is also the heading which appears
above the list of matches from the source. Must be unique.
header-name t nil A function returning the display string of the header.
Its argument is the name of the source. This attribute is useful to
add an additional information with the source name.
It doesn't modify the name of the source.
init t nil Function called with no parameters when helm is started.
It is useful for collecting current state information which can be
used to create the list of candidates later.
Initialization of `candidates-in-buffer' is done here
with `helm-init-candidates-in-buffer'.
#+END_EXAMPLE
It seems Emacs is trying to show everything within a table without
considering :documentation can be long.
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#30998
; Package
emacs
.
(Sun, 14 Jul 2019 13:36:01 GMT)
Full text and
rfc822 format available.
Message #8 received at 30998 <at> debbugs.gnu.org (full text, mbox):
Xu Chunyang <mail <at> xuchunyang.me> writes:
> I don't know if defclass requires that :documentation must occupies just
> a single line. Helm uses many multiple lines string for that slot, please see
>
> https://github.com/emacs-helm/helm/blob/6a34d57f416e4194e6d3207b558d3a00cdf2b955/helm-source.el#L54
>
> 'C-h f helm-source' is very hard to read, the following is a part of *Help*
For a build-in example, see `C-h f registry-db' (included below).
So the problem here is with the :documentation strings for the slots:
They can be multi-line, and `C-h f' should format that situation
different.
But even with single-line descriptions, it's unreadable, really, unless
you have an Emacs window that's 150 characters wide.
Perhaps this should be reformatted completely, with the :documentation
string on a separate line?
----
Class description:
registry-db is a type (of kind ‘eieio--class’) in ‘registry.el’.
Inherits from ‘eieio-persistent’.
Instance Allocated Slots:
Name Type Default Doc
———— ———— ——————— ———
file string unbound The save file for this persistent object.
This must be a string, and must be specified when the new object is
instantiated.
version (or null float) nil The registry version.
max-size integer (symbol-value 'most-positive-fixnum) The maximum number of registry entries.
prune-factor float 0.1 Prune to (:max-size * :prune-factor) less
than the :max-size limit. Should be a float between 0 and 1.
tracked t nil The tracked (indexed) fields, a list of symbols.
precious t nil The precious fields, a list of symbols.
tracker hash-table unbound The field tracking hash table.
data hash-table unbound The data hash table.
----
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog: http://lars.ingebrigtsen.no
Added tag(s) confirmed.
Request was from
Lars Ingebrigtsen <larsi <at> gnus.org>
to
control <at> debbugs.gnu.org
.
(Sun, 14 Jul 2019 13:36:02 GMT)
Full text and
rfc822 format available.
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#30998
; Package
emacs
.
(Thu, 24 Jun 2021 18:26:02 GMT)
Full text and
rfc822 format available.
Message #13 received at 30998 <at> debbugs.gnu.org (full text, mbox):
Lars Ingebrigtsen <larsi <at> gnus.org> writes:
> But even with single-line descriptions, it's unreadable, really, unless
> you have an Emacs window that's 150 characters wide.
>
> Perhaps this should be reformatted completely, with the :documentation
> string on a separate line?
I've now done this in Emacs 28.
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog: http://lars.ingebrigtsen.no
bug marked as fixed in version 28.1, send any further explanations to
30998 <at> debbugs.gnu.org and Xu Chunyang <mail <at> xuchunyang.me>
Request was from
Lars Ingebrigtsen <larsi <at> gnus.org>
to
control <at> debbugs.gnu.org
.
(Thu, 24 Jun 2021 18:26:02 GMT)
Full text and
rfc822 format available.
bug archived.
Request was from
Debbugs Internal Request <help-debbugs <at> gnu.org>
to
internal_control <at> debbugs.gnu.org
.
(Fri, 23 Jul 2021 11:24:09 GMT)
Full text and
rfc822 format available.
This bug report was last modified 2 years and 248 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.