bug#18652: 25.0.50; [PATCH] Add fresh-line

[Leo Liu <sdl.web@gmail.com>]

Thanks for your input.

On 2014-10-08 10:08 +0300, Eli Zaretskii wrote:
> I can't say I care much for this name.  How about add-newline, or
> ensure-newline or some such?

The name is taken from CL's fresh-line but that doesn't mean it is best
suited. add-newline sounds like an alias to terpri, so it is the least
favourable. `ensure-newline' is acceptable to me. But if we choose
ensure-newline I'd like to add an alias to it in cl-lib.el.

>> +@cindex fresh line in print
>> +This function outputs a newline to @var{stream} unless already at the
>> +beginning of a line. Return @code{t} if a newline is printed. Signal
>
> "At beginning of a line" needs explanation, I think.

Any suggestion on how to improve it?

> Also, our convention is to have 2 spaces between sentences.
>
> Finally, the style in the manual is to say "function returns" or "it
> returns" and "signals", instead of "return" and "signal".
>
> Thanks.

Indeed.

=== modified file 'doc/lispref/streams.texi'
--- doc/lispref/streams.texi	2014-03-18 01:19:03 +0000
+++ doc/lispref/streams.texi	2014-10-08 08:45:10 +0000
@@ -621,6 +621,14 @@
 for ``terminate print''.
 @end defun
 
+@defun fresh-line &optional stream
+@cindex fresh line in print
+This function outputs a newline to @var{stream} if it is not already
+at the beginning of a line.  It returns @code{t} if a newline is
+printed.  It can not take a function as @var{STREAM} and an error is
+signaled in this case.
+@end defun
+
 @defun write-char character &optional stream
 This function outputs @var{character} to @var{stream}.  It returns
 @var{character}.