GNU bug report logs - #29373
24.5; doc string of `self-insert-uses-region-functions'

Previous Next

Full log

Message #13 received at 29373-done <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 29373-done <at> debbugs.gnu.org
Subject: RE: bug#29373: 24.5; doc string of `self-insert-uses-region-functions'
Date: Fri, 24 Nov 2017 08:43:05 -0800 (PST)

> -----Original Message-----
> From: Eli Zaretskii [mailto:eliz <at> gnu.org]
> Sent: Friday, November 24, 2017 2:51 AM
> To: Drew Adams <drew.adams <at> oracle.com>
> Cc: 29373-done <at> debbugs.gnu.org
> Subject: Re: bug#29373: 24.5; doc string of `self-insert-uses-region-
> functions'
> 
> > Date: Mon, 20 Nov 2017 18:56:15 -0800 (PST)
> > From: Drew Adams <drew.adams <at> oracle.com>
> >
> > Two lines of the doc string are too long.
> 
> Longer than 79 characters?  I didn't find any such lines.

Where do you see 79 as the recommended max length?
Traditionaly it has been 70, IIRC.

From (elisp) `Documentation Tips':

 Format the documentation string so that it fits in an Emacs window
 on an 80-column screen.  It is a good idea for most lines to be no
 wider than 60 characters.  The first line should not be wider than
 67 characters or it will look bad in the output of 'apropos'.

https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html

1 out of the 5 lines is less than 61 chars - not most.
But if you're happy with the lengths as is, fine.

> > The doc string is close to incomprehensible.
> 
> Such derogatory remarks are best kept out of bug reports.  The facts
> are grave enough to tell we should fix this.

Nothing derogatory intended.  That's a summary of the
problem - lack of clarity overall.  For me, at least,
the wording of this doc is not very understandable.

I have no idea who wrote it, nor do I care.  It's not
about blaming or attacking anyone.  It's about calling
your attention to what I, at least, think is a doc
string that needs some love (improvement).  And the
overall problem is not the technical content; it is
the lack of clarity - comprehensibility.  To me, at
least.

Anyway, I'm sure you made an improvement, whatever
change you made.  Thanks for that.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.