ps-print doc fixes

[Dave Love]

A user complained that some of the doc strings in the ps-print Custom
group didn't make sense.  It probably needs more serious fixing than
this, but here's a start at fixing things (against 21.2).

By the way, I think the paper size should default to the contents of
/etc/papersize if that exists (Debian).

Index: ps-print.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/ps-print.el,v
retrieving revision 1.124
diff -u -p -c -r1.124 ps-print.el
cvs server: conflicting specifications of output style
*** ps-print.el 19 Sep 2001 14:54:19 -0000      1.124
--- ps-print.el 6 Sep 2002 16:01:04 -0000
*************** Emacs without changes to the version num
*** 22,29 ****
  report the version of Emacs, if any, that ps-print was distributed with.
  
  Please send all bug fixes and enhancements to
!       Vinicius Jose Latorre <vinicius@cpqd.com.br>.
! ")
  
  ;; This file is part of GNU Emacs.
  
--- 22,28 ----
  report the version of Emacs, if any, that ps-print was distributed with.
  
  Please send all bug fixes and enhancements to
!       Vinicius Jose Latorre <vinicius@cpqd.com.br>.")
  
  ;; This file is part of GNU Emacs.
  
*************** As an example for `ps-user-defined-prolo
*** 1653,1660 ****
     ;; Setting for HP PostScript printer
     (setq ps-user-defined-prologue
         (concat \"<</DeferredMediaSelection true /PageSize [612 792] \"
!                \"/MediaPosition 2 /MediaType (Plain)>> setpagedevice\"))
! "
    :type '(choice :menu-tag "User Defined Prologue"
                 :tag "User Defined Prologue"
                 (const :tag "none" nil) string symbol)
--- 1652,1658 ----
     ;; Setting for HP PostScript printer
     (setq ps-user-defined-prologue
         (concat \"<</DeferredMediaSelection true /PageSize [612 792] \"
!                \"/MediaPosition 2 /MediaType (Plain)>> setpagedevice\"))"
    :type '(choice :menu-tag "User Defined Prologue"
                 :tag "User Defined Prologue"
                 (const :tag "none" nil) string symbol)
*************** more requirements put them first in `ps-
*** 1673,1679 ****
  \"%%+\" comment.  For example, if you need to set numcopies to 3 and jog on
  requirements and set %%LanguageLevel: to 2, do:
  
! (setq ps-print-prologue-header
        \"%%+ numcopies(3) jog\\n%%LanguageLevel: 2\\n\")
  
  The duplex requirement is inserted by ps-print (see `ps-spool-duplex').
--- 1671,1677 ----
  \"%%+\" comment.  For example, if you need to set numcopies to 3 and jog on
  requirements and set %%LanguageLevel: to 2, do:
  
!  (setq ps-print-prologue-header
        \"%%+ numcopies(3) jog\\n%%LanguageLevel: 2\\n\")
  
  The duplex requirement is inserted by ps-print (see `ps-spool-duplex').
*************** See also `ps-printer-name-option' for do
*** 1729,1744 ****
         "-P" ))
    "*Option for `ps-printer-name' variable (see it).
  
! On Unix-like systems, if it's been used lpr utility, it should be the string
! \"-P\"; if it's been used lp utility, it should be the string \"-d\".
  
! On MS-DOS and MS-Windows systems, if it's been used print utility, it should 
be
  the string \"/D:\".
  
! For any other printing utility, see the proper manual or documentation.
  
  Set to \"\" or nil, if the utility given by `ps-lpr-command' needs an empty
! option printer name option.
  
  Any other value is treated as nil, that is, an empty printer name option.
  
--- 1727,1742 ----
         "-P" ))
    "*Option for `ps-printer-name' variable (see it).
  
! On Unix-like systems, if `lpr' is in use, it should be the string
! \"-P\"; if `lp' is in use, it should be the string \"-d\".
  
! On MS-DOS and MS-Windows systems, if `print' is in use, it should be
  the string \"/D:\".
  
! For any other printing utility, see its documentation.
  
  Set to \"\" or nil, if the utility given by `ps-lpr-command' needs an empty
! printer name option.
  
  Any other value is treated as nil, that is, an empty printer name option.
  
*************** It's used when `ps-spool-config' is set 
*** 1858,1864 ****
    :group 'ps-print-page)
  
  (defcustom ps-print-upside-down nil
!   "*Non-nil means print upside-down (that is, it's rotated by 180 grades)."
    :type 'boolean
    :version "21.1"
    :group 'ps-print-page)
--- 1856,1862 ----
    :group 'ps-print-page)
  
  (defcustom ps-print-upside-down nil
!   "*Non-nil means print upside-down (that is, rotated by 180 degrees)."
    :type 'boolean
    :version "21.1"
    :group 'ps-print-page)
*************** It's used when `ps-spool-config' is set 
*** 1866,1884 ****
  (defcustom ps-selected-pages nil
    "*Specify which pages to print.
  
! If it's nil, all pages are printed.
  
! If it's a list, the list element may be an integer or a cons cell (FROM . TO)
  designating FROM page to TO page; any invalid element is ignored, that is, an
! integer lesser than one or if FROM is greater than TO.
  
  Otherwise, it's treated as nil.
  
! After ps-print processing `ps-selected-pages' is set to nil.  But the latest
! `ps-selected-pages' is saved in `ps-last-selected-pages' (see it for
! documentation).  So you can restore the latest selected pages by using
! `ps-last-selected-pages' or by calling `ps-restore-selected-pages' command 
(see
! it for documentation).
  
  See also `ps-even-or-odd-pages'."
    :type '(repeat :tag "Selected Pages"
--- 1864,1882 ----
  (defcustom ps-selected-pages nil
    "*Specify which pages to print.
  
! If nil, print all pages.
  
! If a list, the lists element may be an integer or a cons cell (FROM . TO)
  designating FROM page to TO page; any invalid element is ignored, that is, an
! integer less than one or if FROM is greater than TO.
  
  Otherwise, it's treated as nil.
  
! After ps-print processing `ps-selected-pages' is set to nil.  But the
! latest `ps-selected-pages' is saved in `ps-last-selected-pages' (which
! see).  So you can restore the latest selected pages by using
! `ps-last-selected-pages' or with the `ps-restore-selected-pages'
! command (which see).
  
  See also `ps-even-or-odd-pages'."
    :type '(repeat :tag "Selected Pages"
*************** Any other value is treated as `left-top'
*** 2035,2041 ****
    :group 'ps-print-n-up)
  
  (defcustom ps-number-of-columns (if ps-landscape-mode 2 1)
!   "*Specify the number of columns"
    :type 'number
    :group 'ps-print-miscellany)
  
--- 2033,2039 ----
    :group 'ps-print-n-up)
  
  (defcustom ps-number-of-columns (if ps-landscape-mode 2 1)
!   "*Specify the number of columns."
    :type 'number
    :group 'ps-print-miscellany)
  
*************** page.
*** 2195,2201 ****
  If PAGES is nil, print background image on all pages.
  
  X, Y, XSCALE, YSCALE and ROTATION may be a floating point number, an integer
! number or a string. If it is a string, the string should contain PostScript
  programming that returns a float or integer value.
  
  For example, if you wish to print an EPS image on all pages do:
--- 2193,2199 ----
  If PAGES is nil, print background image on all pages.
  
  X, Y, XSCALE, YSCALE and ROTATION may be a floating point number, an integer
! number or a string.  If it is a string, the string should contain PostScript
  programming that returns a float or integer value.
  
  For example, if you wish to print an EPS image on all pages do:
*************** page.
*** 2245,2251 ****
  If PAGES is nil, print background text on all pages.
  
  X, Y, FONTSIZE, GRAY and ROTATION may be a floating point number, an integer
! number or a string. If it is a string, the string should contain PostScript
  programming that returns a float or integer value.
  
  For example, if you wish to print text \"Preliminary\" on all pages do:
--- 2243,2249 ----
  If PAGES is nil, print background text on all pages.
  
  X, Y, FONTSIZE, GRAY and ROTATION may be a floating point number, an integer
! number or a string.  If it is a string, the string should contain PostScript
  programming that returns a float or integer value.
  
  For example, if you wish to print text \"Preliminary\" on all pages do:
*************** For example, if you wish to print text \
*** 2320,2327 ****
    :group 'ps-print-vertical)
  
  (defcustom ps-header-line-pad 0.15
!   "*Portion of a header title line height to insert between the header frame
! and the text it contains, both in the vertical and horizontal directions."
    :type 'number
    :group 'ps-print-vertical)
  
--- 2318,2326 ----
    :group 'ps-print-vertical)
  
  (defcustom ps-header-line-pad 0.15
!   "*Portion of a header title line height to insert.
! The insertion is done between the header frame and the text it contains,
! both in the vertical and horizontal directions."
    :type 'number
    :group 'ps-print-vertical)
  
*************** and the text it contains, both in the ve
*** 2331,2338 ****
    :group 'ps-print-vertical)
  
  (defcustom ps-footer-line-pad 0.15
!   "*Portion of a footer title line height to insert between the footer frame
! and the text it contains, both in the vertical and horizontal directions."
    :type 'number
    :group 'ps-print-vertical)
  
--- 2330,2338 ----
    :group 'ps-print-vertical)
  
  (defcustom ps-footer-line-pad 0.15
!   "*Portion of a footer title line height to insert.
! The insertion is done between the footer frame and the text it contains,
! both in the vertical and horizontal directions."
    :type 'number
    :group 'ps-print-vertical)
  
*************** WARNING: The setpagedevice PostScript op
*** 2582,2588 ****
         specified by setpagedevice, your printing will be aborted.
         So, if you need to use setpagedevice, set `ps-spool-config' to
         `setpagedevice', generate a test file and send it to your printer; if
!        the printed file isn't ok, set `ps-spool-config' to nil."
    :type '(choice :menu-tag "Spool Config"
                 :tag "Spool Config"
                 (const lpr-switches) (const setpagedevice)
--- 2582,2588 ----
         specified by setpagedevice, your printing will be aborted.
         So, if you need to use setpagedevice, set `ps-spool-config' to
         `setpagedevice', generate a test file and send it to your printer; if
!        the printed file isn't OK, set `ps-spool-config' to nil."
    :type '(choice :menu-tag "Spool Config"
                 :tag "Spool Config"
                 (const lpr-switches) (const setpagedevice)
*************** It has effect only when `ps-spool-duplex
*** 2718,2724 ****
       (space-width . 2.2)
       (avg-char-width . 4.10811))
      )
!   "*Font info database: font family (the key), name, bold, italic, 
bold-italic,
  reference size, line height, space width, average character width.
  To get the info for another specific font (say Helvetica), do the following:
  - create a new buffer
--- 2718,2725 ----
       (space-width . 2.2)
       (avg-char-width . 4.10811))
      )
!   "*Font info database.
! Each element comprises: font family (the key), name, bold, italic, 
bold-italic,
  reference size, line height, space width, average character width.
  To get the info for another specific font (say Helvetica), do the following:
  - create a new buffer
*************** There are the following basic functions 
*** 3040,3046 ****
     `ps-time-stamp-mon-dd-yyyy'                Return date as \"Jun 18 2001\".
  
  You can also create your own time stamp function by using `format-time-string'
! (which see)."
    :type '(repeat (choice :menu-tag "Right Header"
                         :tag "Right Header"
                         string symbol))
--- 3041,3047 ----
     `ps-time-stamp-mon-dd-yyyy'                Return date as \"Jun 18 2001\".
  
  You can also create your own time stamp function by using `format-time-string'
! \(which see)."
    :type '(repeat (choice :menu-tag "Right Header"
                         :tag "Right Header"
                         string symbol))
*************** There are the following basic functions 
*** 3087,3093 ****
     `ps-time-stamp-mon-dd-yyyy'                Return date as \"Jun 18 2001\".
  
  You can also create your own time stamp function by using `format-time-string'
! (which see)."
    :version "21.1"
    :type '(repeat (choice :menu-tag "Right Footer"
                         :tag "Right Footer"
--- 3088,3094 ----
     `ps-time-stamp-mon-dd-yyyy'                Return date as \"Jun 18 2001\".
  
  You can also create your own time stamp function by using `format-time-string'
! \(which see)."
    :version "21.1"
    :type '(repeat (choice :menu-tag "Right Footer"
                         :tag "Right Footer"
*************** See `ps-begin-cut-regexp' for more infor
*** 3247,3253 ****
  (defun ps-print-buffer (&optional filename)
    "Generate and print a PostScript image of the buffer.
  
! Interactively, when you use a prefix argument (C-u), the command prompts the
  user for a file name, and saves the PostScript image in that file instead of
  sending it to the printer.
  
--- 3248,3254 ----
  (defun ps-print-buffer (&optional filename)
    "Generate and print a PostScript image of the buffer.
  
! Interactively, when you use a prefix argument (\\[universal-argument]), the 
command prompts the
  user for a file name, and saves the PostScript image in that file instead of
  sending it to the printer.
  
*************** Use the command `ps-despool' to send the
*** 3334,3340 ****
  (defun ps-despool (&optional filename)
    "Send the spooled PostScript to the printer.
  
! Interactively, when you use a prefix argument (C-u), the command prompts the
  user for a file name, and saves the spooled PostScript image in that file
  instead of sending it to the printer.
  
--- 3335,3341 ----
  (defun ps-despool (&optional filename)
    "Send the spooled PostScript to the printer.
  
! Interactively, when you use a prefix argument (\\[universal-argument]), the 
command prompts the
  user for a file name, and saves the spooled PostScript image in that file
  instead of sending it to the printer.
  
*************** image in a file with that name."
*** 3346,3353 ****
  
  ;;;###autoload
  (defun ps-line-lengths ()
!   "Display the correspondence between a line length and a font size, using the
! current ps-print setup.
  Try: pr -t file | awk '{printf \"%3d %s\n\", length($0), $0}' | sort -r | 
head"
    (interactive)
    (ps-line-lengths-internal))
--- 3347,3354 ----
  
  ;;;###autoload
  (defun ps-line-lengths ()
!   "Display the correspondence between a line length and a font size.
! Done using the current ps-print setup.
  Try: pr -t file | awk '{printf \"%3d %s\n\", length($0), $0}' | sort -r | 
head"
    (interactive)
    (ps-line-lengths-internal))
*************** It can be retrieved with `(ps-get ALIST-
*** 3727,3733 ****
  
  
  (defun ps-prologue-file (filenumber)
!   "If prologue FILENUMBER exists and is readable, returns contents as string.
  
  Note: No major/minor-mode is activated and no local variables are evaluated 
for
        FILENUMBER, but proper EOL-conversion and character interpretation is
--- 3728,3734 ----
  
  
  (defun ps-prologue-file (filenumber)
!   "If prologue FILENUMBER exists and is readable, return contents as string.
  
  Note: No major/minor-mode is activated and no local variables are evaluated 
for
        FILENUMBER, but proper EOL-conversion and character interpretation is
*************** This is in units of points (1/72 inch)."
*** 3843,3849 ****
  (defvar ps-black-white-faces-alist nil
    "Alist of symbolic faces used for black/white PostScript printers.
  An element of this list has the same form as `ps-print-face-extension-alist'
! (which see).
  
  Don't change this list directly; instead,
  use `ps-extend-face' and `ps-extend-face-list'.
--- 3844,3850 ----
  (defvar ps-black-white-faces-alist nil
    "Alist of symbolic faces used for black/white PostScript printers.
  An element of this list has the same form as `ps-print-face-extension-alist'
! \(which see).
  
  Don't change this list directly; instead,
  use `ps-extend-face' and `ps-extend-face-list'.
*************** which long lines wrap around."
*** 4138,4145 ****
    (get font-sym 'avg-char-width))
  
  (defun ps-line-lengths-internal ()
!   "Display the correspondence between a line length and a font size,
! using the current ps-print setup.
  Try: pr -t file | awk '{printf \"%3d %s\n\", length($0), $0}' | sort -r | 
head"
    (let* ((ps-font-size-internal
          (or ps-font-size-internal
--- 4139,4146 ----
    (get font-sym 'avg-char-width))
  
  (defun ps-line-lengths-internal ()
!   "Display the correspondence between a line length and a font size.
! Done using the current ps-print setup.
  Try: pr -t file | awk '{printf \"%3d %s\n\", length($0), $0}' | sort -r | 
head"
    (let* ((ps-font-size-internal
          (or ps-font-size-internal