GNU bug report logs - #30998
27.0.50; The Help for defclass with multiline documentation is very hard to read

Previous Next

Package: emacs;

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.

View this report as an mbox folder, status mbox, maintainer mbox


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):

From: Xu Chunyang <mail <at> xuchunyang.me>
To: bug-gnu-emacs <at> gnu.org
Subject: 27.0.50;
 The Help for defclass with multiline documentation is very hard to
 read
Date: Sat, 31 Mar 2018 03:38:29 +0800
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):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Xu Chunyang <mail <at> xuchunyang.me>
Cc: 30998 <at> debbugs.gnu.org
Subject: Re: bug#30998: 27.0.50; The Help for defclass with multiline
 documentation is very hard to read
Date: Sun, 14 Jul 2019 15:35:19 +0200
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):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Xu Chunyang <mail <at> xuchunyang.me>
Cc: 30998 <at> debbugs.gnu.org
Subject: Re: bug#30998: 27.0.50; The Help for defclass with multiline
 documentation is very hard to read
Date: Thu, 24 Jun 2021 20:25:02 +0200
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.