* bug#7521: 24.0.50; doc for `delimit-columns-*'
@ 2010-11-30 19:34 Drew Adams
2011-07-02 13:44 ` Lars Magne Ingebrigtsen
0 siblings, 1 reply; 10+ messages in thread
From: Drew Adams @ 2010-11-30 19:34 UTC (permalink / raw)
To: 7521
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'
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#7521: 24.0.50; doc for `delimit-columns-*'
2010-11-30 19:34 bug#7521: 24.0.50; doc for `delimit-columns-*' Drew Adams
@ 2011-07-02 13:44 ` Lars Magne Ingebrigtsen
2011-07-02 15:21 ` Drew Adams
0 siblings, 1 reply; 10+ messages in thread
From: Lars Magne Ingebrigtsen @ 2011-07-02 13:44 UTC (permalink / raw)
To: Drew Adams; +Cc: 7521
"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/
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#7521: 24.0.50; doc for `delimit-columns-*'
2011-07-02 13:44 ` Lars Magne Ingebrigtsen
@ 2011-07-02 15:21 ` Drew Adams
2011-07-02 15:34 ` Lars Magne Ingebrigtsen
2011-07-04 1:08 ` Stefan Monnier
0 siblings, 2 replies; 10+ messages in thread
From: Drew Adams @ 2011-07-02 15:21 UTC (permalink / raw)
To: 'Lars Magne Ingebrigtsen'; +Cc: 7521
> > 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.
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#7521: 24.0.50; doc for `delimit-columns-*'
2011-07-02 15:21 ` Drew Adams
@ 2011-07-02 15:34 ` Lars Magne Ingebrigtsen
2011-07-02 15:59 ` Drew Adams
2011-07-04 1:08 ` Stefan Monnier
1 sibling, 1 reply; 10+ messages in thread
From: Lars Magne Ingebrigtsen @ 2011-07-02 15:34 UTC (permalink / raw)
To: Drew Adams; +Cc: 7521
"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/
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#7521: 24.0.50; doc for `delimit-columns-*'
2011-07-02 15:34 ` Lars Magne Ingebrigtsen
@ 2011-07-02 15:59 ` Drew Adams
2011-07-02 16:10 ` Lars Magne Ingebrigtsen
0 siblings, 1 reply; 10+ messages in thread
From: Drew Adams @ 2011-07-02 15:59 UTC (permalink / raw)
To: 'Lars Magne Ingebrigtsen'; +Cc: 7521
> > 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.
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#7521: 24.0.50; doc for `delimit-columns-*'
2011-07-02 15:59 ` Drew Adams
@ 2011-07-02 16:10 ` Lars Magne Ingebrigtsen
2011-07-02 16:28 ` Drew Adams
0 siblings, 1 reply; 10+ messages in thread
From: Lars Magne Ingebrigtsen @ 2011-07-02 16:10 UTC (permalink / raw)
To: Drew Adams; +Cc: 7521
"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/
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#7521: 24.0.50; doc for `delimit-columns-*'
2011-07-02 16:10 ` Lars Magne Ingebrigtsen
@ 2011-07-02 16:28 ` Drew Adams
2011-07-02 16:30 ` Lars Magne Ingebrigtsen
0 siblings, 1 reply; 10+ messages in thread
From: Drew Adams @ 2011-07-02 16:28 UTC (permalink / raw)
To: 'Lars Magne Ingebrigtsen'; +Cc: 7521
> 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).
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#7521: 24.0.50; doc for `delimit-columns-*'
2011-07-02 15:21 ` Drew Adams
2011-07-02 15:34 ` Lars Magne Ingebrigtsen
@ 2011-07-04 1:08 ` Stefan Monnier
1 sibling, 0 replies; 10+ messages in thread
From: Stefan Monnier @ 2011-07-04 1:08 UTC (permalink / raw)
To: Drew Adams; +Cc: 7521, 'Lars Magne Ingebrigtsen'
>> > 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
^ permalink raw reply [flat|nested] 10+ messages in thread
end of thread, other threads:[~2011-07-04 1:08 UTC | newest]
Thread overview: 10+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2010-11-30 19:34 bug#7521: 24.0.50; doc for `delimit-columns-*' Drew Adams
2011-07-02 13:44 ` Lars Magne Ingebrigtsen
2011-07-02 15:21 ` Drew Adams
2011-07-02 15:34 ` Lars Magne Ingebrigtsen
2011-07-02 15:59 ` Drew Adams
2011-07-02 16:10 ` Lars Magne Ingebrigtsen
2011-07-02 16:28 ` Drew Adams
2011-07-02 16:30 ` Lars Magne Ingebrigtsen
2011-07-02 16:32 ` Drew Adams
2011-07-04 1:08 ` Stefan Monnier
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).