GNU bug report logs - #7521
24.0.50; doc for `delimit-columns-*'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 7521 in the body.
You can then email your comments to 7521 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.0.50; doc for `delimit-columns-*'
Date: Tue, 30 Nov 2010 11:34:37 -0800

emacs -Q

You cannot understand a thing about commands `delimit-columns-region'
and `delimit-columns-rectangle' without reading the commentary in Lisp
file delim-col.el.  In sum, there is no help for users - no doc.

Not only that, if you are tempted to try these commands on a regular
region of text, you will likely see no change at all - the buffer isn't
even modified.  This is because these commands only affect regions and
rectangles that contain text formatted in a certain way.

This is all explained in detail in the source file commentary,
`delim-col.el'.  But none of it is available to users via *Help*.

Similarly, the defcustoms are little help.  They explain nothing.  Users
must consult the source file to understand _anything_ about this feature.

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2010-11-22 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4) --no-opt --cflags
-Ic:/imagesupport/include'

Message #8 received at 7521 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 7521 <at> debbugs.gnu.org
Subject: Re: bug#7521: 24.0.50; doc for `delimit-columns-*'
Date: Sat, 02 Jul 2011 15:44:29 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

> You cannot understand a thing about commands `delimit-columns-region'
> and `delimit-columns-rectangle' without reading the commentary in Lisp
> file delim-col.el.  In sum, there is no help for users - no doc.

I suspect that the workings of delim-col.el are too complicated to be
explained in a doc string for any of the commands.  If these commands
are to be useful to users, I think the proper solution is to document
them in the elisp manual.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #11 received at 7521 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Lars Magne Ingebrigtsen'" <larsi <at> gnus.org>
Cc: 7521 <at> debbugs.gnu.org
Subject: RE: bug#7521: 24.0.50; doc for `delimit-columns-*'
Date: Sat, 2 Jul 2011 08:21:40 -0700

> > You cannot understand a thing about commands 
> > `delimit-columns-region' and `delimit-columns-rectangle'
> > without reading the commentary in Lisp
> > file delim-col.el.  In sum, there is no help for users - no doc.
> 
> I suspect that the workings of delim-col.el are too complicated to be
> explained in a doc string for any of the commands.  If these commands
> are to be useful to users, I think the proper solution is to document
> them in the elisp manual.

You might be right; I really don't know.  My take is that these things are
explained in the source-code comments, and that this info needs to be made
available to users via help/doc.  If the details get transferred to the manual,
OK.

But even then the doc strings of the various functions (these are user
_commands_, after all) need to give some explanation.  If we cannot explain
these commands at all then maybe that's a sign that the commands themselves are
overly complex.

A user should be able to get some idea of what to expect from a command by
reading its doc string.  That s?he might need to consult the manual for more
detail is fine.  But that's not a reason to have incomprehensible or vacuous doc
strings.

Message #14 received at 7521 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 7521 <at> debbugs.gnu.org
Subject: Re: bug#7521: 24.0.50; doc for `delimit-columns-*'
Date: Sat, 02 Jul 2011 17:34:30 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

> But even then the doc strings of the various functions (these are user
> _commands_, after all) need to give some explanation.  If we cannot
> explain these commands at all then maybe that's a sign that the
> commands themselves are overly complex.

There are oodles of commands tied to various modes/packages that presume
that you're aware of what the general gist of the package is.  It
wouldn't be very productive to explain the concept of a Message buffer
in each message-mode command, for instance.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #17 received at 7521 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Lars Magne Ingebrigtsen'" <larsi <at> gnus.org>
Cc: 7521 <at> debbugs.gnu.org
Subject: RE: bug#7521: 24.0.50; doc for `delimit-columns-*'
Date: Sat, 2 Jul 2011 08:59:20 -0700

> > But even then the doc strings of the various functions 
> > (these are user _commands_, after all) need to give some
> > explanation.  If we cannot explain these commands at all
> > then maybe that's a sign that the
> > commands themselves are overly complex.
> 
> There are oodles of commands tied to various modes/packages 
> that presume that you're aware of what the general gist of
> the package is.

There is certainly no need and no use in describing the general gist of a
package in the doc for each of the packages commands.  That's not the point at
all.

> It wouldn't be very productive to explain the concept of a
> Message buffer in each message-mode command, for instance.

Of course, but that's not the request.  I don't use `message-mode', but I would
guess (hope) that the doc for each of its _commands_ describes that command.

If there were a `message-mode' command `msg-delete' (fictitious example) that
deleted the current message then I would hope its doc string would say that's
what it does.

Message #20 received at 7521 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 7521 <at> debbugs.gnu.org
Subject: Re: bug#7521: 24.0.50; doc for `delimit-columns-*'
Date: Sat, 02 Jul 2011 18:10:23 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

> If there were a `message-mode' command `msg-delete' (fictitious
> example) that deleted the current message then I would hope its doc
> string would say that's what it does.

It should, and I think the `delimit-*' functions do, too:

-------
delimit-columns-rectangle is an interactive compiled Lisp function in
`delim-col.el'.

(delimit-columns-rectangle START END)

Prettify all columns in a text rectangle.

START and END delimits the corners of text rectangle.
-------

If you know what this package considers a "column", then I think it's a
pretty clear doc string.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #23 received at 7521 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Lars Magne Ingebrigtsen'" <larsi <at> gnus.org>
Cc: 7521 <at> debbugs.gnu.org
Subject: RE: bug#7521: 24.0.50; doc for `delimit-columns-*'
Date: Sat, 2 Jul 2011 09:28:41 -0700

> It should, and I think the `delimit-*' functions do, too:
> 
> delimit-columns-rectangle
> Prettify all columns in a text rectangle.
> START and END delimits the corners of text rectangle.
> 
> If you know what this package considers a "column", then I 
> think it's a pretty clear doc string.

I'm OK with it if you have documented what's going on in the manual.  Thanks.

It's the info that is in the commentary of delim-col.el that I wanted added to
the doc.  If that's available in the manual then it's appropriate that the
command doc string just says that it prettifies etc. - that's TRT.

It's what "prettify" means that needed to be explained, and I agree that this
need not be done in the command doc strings (if it is done in the manual).

Message #26 received at 7521 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 7521 <at> debbugs.gnu.org
Subject: Re: bug#7521: 24.0.50; doc for `delimit-columns-*'
Date: Sat, 02 Jul 2011 18:30:25 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

> I'm OK with it if you have documented what's going on in the manual.
> Thanks.

No, I haven't.  I was hoping that someone who uses delim-col would write
the manual entry for it.  :-)

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #29 received at 7521 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Lars Magne Ingebrigtsen'" <larsi <at> gnus.org>
Cc: 7521 <at> debbugs.gnu.org
Subject: RE: bug#7521: 24.0.50; doc for `delimit-columns-*'
Date: Sat, 2 Jul 2011 09:32:56 -0700

> > I'm OK with it if you have documented what's going on in the manual.
> > Thanks.
> 
> No, I haven't.  I was hoping that someone who uses delim-col 
> would write the manual entry for it.  :-)

(I don't use it either.)  OK, let's hope so.  Fortunately, the Lisp file
commentary is pretty good.

Message #32 received at 7521 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 7521 <at> debbugs.gnu.org, 'Lars Magne Ingebrigtsen' <larsi <at> gnus.org>
Subject: Re: bug#7521: 24.0.50; doc for `delimit-columns-*'
Date: Sun, 03 Jul 2011 21:08:23 -0400

>> > You cannot understand a thing about commands 
>> > `delimit-columns-region' and `delimit-columns-rectangle'
>> > without reading the commentary in Lisp
>> > file delim-col.el.  In sum, there is no help for users - no doc.
>> I suspect that the workings of delim-col.el are too complicated to be
>> explained in a doc string for any of the commands.  If these commands
>> are to be useful to users, I think the proper solution is to document
>> them in the elisp manual.
> You might be right; I really don't know.  My take is that these things
> are explained in the source-code comments, and that this info needs to
> be made available to users via help/doc.  If the details get
> transferred to the manual, OK.

The Elisp manual does not document all Elisp features and packages.
Some packages come with their own manual, and others put their
documentation in the Commentary section.

IOW, I think the current situation where the doc for delim-col.el is in
the Commentary section is "about right".  I know that the commentary
section may seem "hidden away in the source", but the solution is not to
move it elsewhere, but to make it easier to access the Commentary section.


        Stefan

Previous Next

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