A P documentation could be enhanced

A P documentation could be enhanced

[Kai Grossjohann]

The last sentence in the docstring for A P is, "If FILENAME is a
number, prompt the user for the name of the file to save in."

This caused me to try to process-mark an article, and then to say C-u
A P.  And indeed, it printed the marked article into a file.

But it needed wild guessing.  WIBNI the docstring was more explicit?

Kai

Re: A P documentation could be enhanced

[Lars Magne Ingebrigtsen]

Kai Grossjohann <kai@emptydomain.de> writes:

> The last sentence in the docstring for A P is, "If FILENAME is a
> number, prompt the user for the name of the file to save in."
>
> This caused me to try to process-mark an article, and then to say C-u
> A P.  And indeed, it printed the marked article into a file.

Hm...

Looking at the code, it doesn't really look like it does anything
with process-marked articles:

  (interactive (list (ps-print-preprint current-prefix-arg)))

(Unless the `ps-print-preprint' function does some magic here; I
haven't looked at it.)

-- 
(domestic pets only, the antidote for overdose, milk.)
  larsi@gnus.org * Lars Magne Ingebrigtsen

Re: A P documentation could be enhanced

[Kai Grossjohann]

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:

> Looking at the code, it doesn't really look like it does anything
> with process-marked articles:
>
>   (interactive (list (ps-print-preprint current-prefix-arg)))
>
> (Unless the `ps-print-preprint' function does some magic here; I
> haven't looked at it.)

Indeed, it is unlikely that ps-print-preprint is doing Gnus magic.

In that case, I think the docstring is confusingly worded.  (At least
it confused this lowly poster.)  It talks at length about the N arg,
and only mentions the FILENAME arg in passing.  Even though it was not
stated explicitly, I thought that N was the prefix arg.

(And the part that says if N is nil and some articles are
process-marked, print those instead, is probably wrong.)

Kai, who should be fixing instead of complaining

Re: A P documentation could be enhanced

[Lars Magne Ingebrigtsen]

Kai Grossjohann <kai@emptydomain.de> writes:

> In that case, I think the docstring is confusingly worded.  (At least
> it confused this lowly poster.)  It talks at length about the N arg,
> and only mentions the FILENAME arg in passing.  Even though it was not
> stated explicitly, I thought that N was the prefix arg.

Uhm...  looking at the code, I think that N always is nil when called
interactively.  So it's not a docstring confusion; it's just a bug.
:-)

-- 
(domestic pets only, the antidote for overdose, milk.)
  larsi@gnus.org * Lars Magne Ingebrigtsen

Re: A P documentation could be enhanced

[Kai Grossjohann]

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:

> Kai Grossjohann <kai@emptydomain.de> writes:
>
>> In that case, I think the docstring is confusingly worded.  (At least
>> it confused this lowly poster.)  It talks at length about the N arg,
>> and only mentions the FILENAME arg in passing.  Even though it was not
>> stated explicitly, I thought that N was the prefix arg.
>
> Uhm...  looking at the code, I think that N always is nil when called
> interactively.  So it's not a docstring confusion; it's just a bug.
> :-)

Please compare the docstring of B m with the one of A P.  Don't you
agree that the A P docstring suggests that C-u 42 A P will print 42
articles?

I still think that the docstring does not adequately describe the
behavior.

Kai

Re: A P documentation could be enhanced

[Kai Grossjohann]

Kai Grossjohann <kai@emptydomain.de> writes:

> I still think that the docstring does not adequately describe the
> behavior.

I mean, it might not be wrong, but misleading.

Kai

Re: A P documentation could be enhanced

[Kai Grossjohann]

Here is a suggestion for a docstring.  What do you think?  Does it
describe the behavior better?

--- gnus-sum.el.~6.373.~	Fri Jan  2 17:49:04 2004
+++ gnus-sum.el	Sun Jan  4 19:09:33 2004
@@ -8534,10 +8534,16 @@
 			  "[()]" "\\\\\\&"))
 
 (defun gnus-summary-print-article (&optional filename n)
-  "Generate and print a PostScript image of the N next (mail) articles.
+  "Generate and print a PostScript image of the process-marked (mail) articles.
 
-If N is negative, print the N previous articles.  If N is nil and articles
-have been marked with the process mark, print these instead.
+If used interactively, print the current article if none are
+process-marked.  With prefix arg, prompt the user for the name of the
+file to save in.
+
+When used from Lisp, accept two optional args FILENAME and N.  N means
+to print the next N articles.  If N is negative, print the N previous
+articles.  If N is nil and articles have been marked with the process
+mark, print these instead.
 
 If the optional first argument FILENAME is nil, send the image to the
 printer.  If FILENAME is a string, save the PostScript image in a file with

Re: A P documentation could be enhanced

[Lars Magne Ingebrigtsen]

Kai Grossjohann <kai@emptydomain.de> writes:

> Here is a suggestion for a docstring.  What do you think?  Does it
> describe the behavior better?

Yes.  Applied.

-- 
(domestic pets only, the antidote for overdose, milk.)
  larsi@gnus.org * Lars Magne Ingebrigtsen