add ~@y truncated printing directive to format

* doc/ref/misc-modules.texi (Formatted Output): Add documentation for
  the new ~@y format directive.
  (Pretty Printing): Add documentation for truncated-write.

* module/ice-9/format.scm (format): Add ~@y, for doing a truncated
  print. Also, allow both ~y variants to take a width parameter.

doc/ref/misc-modules.texi

@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
-@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006
+@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2009
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
@@ -16,7 +16,7 @@ The module @code{(ice-9 pretty-print)} provides the procedure
 objects.  This is especially useful for deeply nested or complex data
 structures, such as lists and vectors.
 
-The module is loaded by simply saying.
+The module is loaded by entering the following:
 
 @lisp
 (use-modules (ice-9 pretty-print))
@@ -60,6 +60,65 @@ Print within the given @var{columns}.  The default is 79.
 @end deffn
 
 
+@cindex truncated printing
+Also exported by the @code{(ice-9 pretty-print)} module is
+@code{truncated-print}, a procedure to print Scheme datums, truncating
+the output to a certain number of characters. This is useful when you
+need to present an arbitrary datum to the user, but you only have one
+line in which to do so.
+
+@lisp
+(define exp '(a b #(c d e) f . g))
+(truncated-print exp #:width 10) (newline)
+@print{} (a b . #)
+(truncated-print exp #:width 15) (newline)
+@print{} (a b # f . g)
+(truncated-print exp #:width 18) (newline)
+@print{} (a b #(c ...) . #)
+(truncated-print exp #:width 20) (newline)
+@print{} (a b #(c d e) f . g)
+(truncated-print "The quick brown fox" #:width 10) (newline)
+@print{} "The quick brown..."
+(truncated-print (current-module) #:width 20) (newline)
+@print{} #<directory (gui...>
+@end lisp
+
+@code{truncated-print} will not output a trailing newline. If an
+expression does not fit in the given width, it will be truncated --
+possibly ellipsized, or in the worst case, displayed as @nicode{#}. 
+
+@deffn {Scheme Procedure} truncated-print obj [port] [keyword-options]
+Print @var{obj}, truncating the output, if necessary, to make it fit
+into @var{width} characters. By default, @var{x} will be printed using
+@code{write}, though that behavior can be overriden via the
+@var{display?} keyword argument.
+
+The default behaviour is to print depth-first, meaning that the entire
+remaining width will be available to each sub-expressoin of @var{x} --
+e.g., if @var{x} is a vector, each member of @var{x}. One can attempt to
+``ration'' the available width, trying to allocate it equally to each
+sub-expression, via the @var{breadth-first?} keyword argument.
+
+The further @var{keyword-options} are keywords and parameters as
+follows,
+
+@table @asis
+@item @nicode{#:display?} @var{flag}
+If @var{flag} is true then print using @code{display}.  The default is
+@code{#f} which means use @code{write} style.  (@pxref{Writing})
+
+@item @nicode{#:width} @var{columns}
+Print within the given @var{columns}.  The default is 79.
+
+@item @nicode{#:breadth-first?} @var{flag}
+If @var{flag} is true, then allocate the available width breadth-first
+among elements of a compound data structure (list, vector, pair,
+etc.). The default is @code{#f} which means that any element is
+allowed to consume all of the available width.
+@end table
+@end deffn
+
+
 @page
 @node Formatted Output
 @section Formatted Output
@@ -577,9 +636,17 @@ to help.  When using @code{gettext} to translate messages
 (@pxref{Internationalization}).
 
 @item @nicode{~y}
-Pretty print.  No parameters.
+Structured printing.  Parameters: @var{width}.
 
-Output an argument with @code{pretty-print} (@pxref{Pretty Printing}).
+@nicode{~y} outputs an argument using @code{pretty-print}
+(@pxref{Pretty Printing}). The result will be formatted to fit within
+@var{width} columns (79 by default), consuming multiple lines if
+necessary.
+
+@nicode{~@@y} outputs an argument using @code{truncated-print}
+(@pxref{Pretty Printing}). The resulting code will be formatted to fit
+within @var{width} columns (79 by default), on a single line. The
+output will be truncated if necessary.
 
 @item @nicode{~?}
 @itemx @nicode{~k}

module/ice-9/format.scm

@@ -13,7 +13,7 @@
 
 (define-module (ice-9 format)
   :use-module (ice-9 and-let-star)
-  :autoload (ice-9 pretty-print) (pretty-print)
+  :autoload (ice-9 pretty-print) (pretty-print truncated-print)
   :replace (format)
   :export (format:symbol-case-conv
 	   format:iobj-case-conv
@@ -482,10 +482,23 @@
 		      ((#\T)			; Tabulate
 		       (format:tabulate modifier params)
 		       (anychar-dispatch))
-		      ((#\Y)			; Pretty-print
-		       (pretty-print (next-arg) format:port)
-		       (set! format:output-col 0)
-		       (anychar-dispatch))
+		      ((#\Y)			; Structured print
+                       (let ((width (if (one-positive-integer? params)
+                                        (car params)
+                                        79)))
+                         (case modifier
+                           ((colon colon-at)
+                            (format:error "illegal modifier in ~~?"))
+                           ((at)
+                            (format:out-str
+                             (with-output-to-string 
+                               (lambda ()
+                                 (truncated-print (next-arg) #:width width)))))
+                           (else
+                            (pretty-print (next-arg) format:port
+                                          #:width width)
+                            (set! format:output-col 0))))
+                       (anychar-dispatch))
 		      ((#\? #\K)		; Indirection (is "~K" in T-Scheme)
 		       (cond
 			((memq modifier '(colon colon-at))