bug#7521: 24.0.50; doc for `delimit-columns-*'

bug#7521: 24.0.50; doc for `delimit-columns-*'

[Drew Adams]

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'

bug#7521: 24.0.50; doc for `delimit-columns-*'

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@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/

bug#7521: 24.0.50; doc for `delimit-columns-*'

[Drew Adams]

> > 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.

bug#7521: 24.0.50; doc for `delimit-columns-*'

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@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/

bug#7521: 24.0.50; doc for `delimit-columns-*'

[Drew Adams]

> > 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.

bug#7521: 24.0.50; doc for `delimit-columns-*'

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@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/

bug#7521: 24.0.50; doc for `delimit-columns-*'

[Drew Adams]

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

bug#7521: 24.0.50; doc for `delimit-columns-*'

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@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/

bug#7521: 24.0.50; doc for `delimit-columns-*'

[Drew Adams]

> > 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.

bug#7521: 24.0.50; doc for `delimit-columns-*'

[Stefan Monnier]

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