vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

print.txt (32833B)


      1 *print.txt*	For Vim version 9.2.  Last change: 2026 Sep 01
      2 
      3 
      4 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
      5 
      6 
      7 Printing						*printing*
      8 
      9 1. Introduction				|print-intro|
     10 2. Print options			|print-options|
     11 3. PostScript Printing			|postscript-printing|
     12 4. PostScript Printing Encoding		|postscript-print-encoding|
     13 5. PostScript CJK Printing		|postscript-cjk-printing|
     14 6. PostScript Printing Troubleshooting	|postscript-print-trouble|
     15 7. PostScript Utilities			|postscript-print-util|
     16 8. Pango Printing			|pango-printing|
     17 9. Formfeed Characters			|printing-formfeed|
     18 
     19 {only available when compiled with the |+printer| feature}
     20 
     21 ==============================================================================
     22 1. Introduction						*print-intro*
     23 
     24 On MS-Windows Vim can print your text on any installed printer.  On other
     25 systems a PostScript file is produced.  This can be directly sent to a
     26 PostScript printer.  For other printers a program like ghostscript needs to be
     27 used.
     28 
     29 Note: If you have problems printing with |:hardcopy|, an alternative is to use
     30 |:TOhtml| and print the resulting html file from a browser.
     31 
     32 					*:ha* *:hardcopy* *E237* *E238* *E324*
     33 :[range]ha[rdcopy][!] [arguments]
     34 			Send [range] lines (default whole file) to the
     35 			printer.
     36 
     37 			On MS-Windows or GTK4 GUI, a dialog is displayed to
     38 			allow selection of printer, paper size etc.  To skip
     39 			the dialog, use the [!].  In this case the printer
     40 			defined by 'printdevice' is used, or, if 'printdevice'
     41 			is empty, the system default printer.  Note that the
     42 			GTK4 GUI print dialog requires at least GTK 4.14.
     43 
     44 			For systems other than MS-Windows or Pango, PostScript
     45 			is written in a temp file and 'printexpr' is used to
     46 			actually print it.  Then [arguments] can be used by
     47 			'printexpr' through |v:cmdarg|.  Otherwise [arguments]
     48 			is ignored.  'printoptions' can be used to specify
     49 			paper size, duplex, etc.
     50 			Note: If you want PDF, there are tools such as
     51 			"ps2pdf" that can convert the PostScript to PDF.  If
     52 			the |+pango| feature is enabled, then emit PDF by
     53 			setting "format" to "pdf" in 'printoptions'.
     54 
     55 :[range]ha[rdcopy][!] >{filename}
     56 			As above, but write the resulting PostScript in file
     57 			{filename}.
     58 			Things like "%" are expanded |cmdline-special|
     59 			Careful: An existing file is silently overwritten.
     60 			{only available when compiled with the |+postscript|
     61 			or |+pango| feature}
     62 			On MS-Windows use the "print to file" feature of the
     63 			printer driver.
     64 
     65 Progress is displayed during printing as a page number and a percentage.  To
     66 abort printing use the interrupt key (CTRL-C or, on MS-systems, CTRL-Break).
     67 
     68 Printer output is controlled by the 'printfont' and 'printoptions' options.
     69 'printheader' specifies the format of a page header.
     70 
     71 The printed file is always limited to the selected margins, irrespective of
     72 the current window's 'wrap' or 'linebreak' settings.  The "wrap" item in
     73 'printoptions' can be used to switch wrapping off.
     74 The current highlighting colors are used in the printout, with the following
     75 considerations:
     76 1) The normal background is always rendered as white (i.e. blank paper).
     77 2) White text or the default foreground is rendered as black, so that it shows
     78    up!
     79 3) If 'background' is "dark", then the colours are darkened to compensate for
     80    the fact that otherwise they would be too bright to show up clearly on
     81    white paper.
     82 
     83 ==============================================================================
     84 2. Print options					*print-options*
     85 
     86 Here are the details for the options that change the way printing is done.
     87 For generic info about setting options see |options.txt|.
     88 
     89 							*pdev-option*
     90 'printdevice' 'pdev'	string	(default empty)
     91 			global
     92 This defines the name of the printer to be used when the |:hardcopy| command
     93 is issued with a bang (!) to skip the printer selection dialog.  On Win32, it
     94 should be the printer name exactly as it appears in the standard printer
     95 dialog.
     96 If the option is empty, then vim will use the system default printer for
     97 ":hardcopy!"
     98 
     99 							*penc-option* *E620*
    100 'printencoding' 'penc'	String	(default empty, except for:
    101 					MS-Windows: cp1252,
    102 					Macintosh: mac-roman,
    103 					VMS: dec-mcs,
    104 					HPUX: hp-roman8,
    105 					EBCDIC: ebcdic-uk)
    106 			global
    107 Sets the character encoding used when printing.  This option tells Vim which
    108 print character encoding file from the "print" directory in 'runtimepath' to
    109 use.
    110 
    111 This option will accept any value from |encoding-names|.  Any recognized names
    112 are converted to Vim standard names - see 'encoding' for more details.  Names
    113 not recognized by Vim will just be converted to lower case and underscores
    114 replaced with '-' signs.
    115 
    116 If 'printencoding' is empty or Vim cannot find the file then it will use
    117 'encoding' (if it is set an 8-bit encoding) to find the print character
    118 encoding file.  If Vim is unable to find a character encoding file then it
    119 will use the "latin1" print character encoding file.
    120 
    121 When 'encoding' is set to a multibyte encoding, Vim will try to convert
    122 characters to the printing encoding for printing (if 'printencoding' is empty
    123 then the conversion will be to latin1).  Conversion to a printing encoding
    124 other than latin1 will require Vim to be compiled with the |+iconv| feature.
    125 If no conversion is possible then printing will fail.  Any characters that
    126 cannot be converted will be replaced with upside down question marks.
    127 
    128 Four print character encoding files are provided to support default Mac, VMS,
    129 HPUX, and EBCDIC character encodings and are used by default on these
    130 platforms.  Code page 1252 print character encoding is used by default on
    131 MS-Windows platform.
    132 
    133 							*pexpr-option*
    134 'printexpr' 'pexpr'	String	(default: see below)
    135 			global
    136 Expression that is evaluated to print the PostScript or PDF produced with
    137 |:hardcopy|.
    138 The file name to be printed is in |v:fname_in|.
    139 The arguments to the ":hardcopy" command are in |v:cmdarg|.
    140 The expression must take care of deleting the file after printing it.
    141 When there is an error, the expression must return a non-zero number.
    142 If there is no error, return zero or an empty string.
    143 The default for non MS-Windows or VMS systems is to simply use "lpr" to print
    144 the file: >
    145 
    146     system('lpr' .. (&printdevice == '' ? '' : ' -P' .. &printdevice)
    147 	.. ' ' .. v:fname_in) .. delete(v:fname_in) + v:shell_error
    148 
    149 On MS-Windows machines the default is to copy the file to the currently
    150 specified printdevice: >
    151 
    152     system('copy' .. ' ' .. v:fname_in .. (&printdevice == ''
    153 		? ' LPT1:' : (' \"' .. &printdevice .. '\"')))
    154 		.. delete(v:fname_in)
    155 
    156 On VMS machines the default is to send the file to either the default or
    157 currently specified printdevice: >
    158 
    159     system('print' .. (&printdevice == '' ? '' : ' /queue=' ..
    160 		&printdevice) .. ' ' .. v:fname_in) .. delete(v:fname_in)
    161 
    162 If you change this option, using a function is an easy way to avoid having to
    163 escape all the spaces.  Example: >
    164 
    165 	:set printexpr=PrintFile()
    166 	:function PrintFile()
    167 	:  call system("ghostview " .. v:fname_in)
    168 	:  call delete(v:fname_in)
    169 	:  return v:shell_error
    170 	:endfunc
    171 
    172 It is more efficient if the option is set to just a function call,
    173 see |expr-option-function|.
    174 
    175 Be aware that some print programs return control before they have read the
    176 file.  If you delete the file too soon it will not be printed.  These programs
    177 usually offer an option to have them remove the file when printing is done.
    178 							*E365*
    179 If evaluating the expression fails or it results in a non-zero number, you get
    180 an error message.  In that case Vim will delete the file.  In the default
    181 value for non-MS-Windows a trick is used: Adding "v:shell_error" will result
    182 in a non-zero number when the system() call fails.
    183 
    184 If the expression starts with s: or |<SID>|, then it is replaced with the
    185 script ID (|local-function|).  Example: >
    186 		set printexpr=s:MyPrintFile()
    187 		set printexpr=<SID>SomePrintFile()
    188 Otherwise, the expression is evaluated in the context of the script where the
    189 option was set, thus script-local items are available.
    190 
    191 This option cannot be set from a |modeline| or in the |sandbox|, for security
    192 reasons.
    193 
    194 							*pfn-option* *E613*
    195 'printfont' 'pfn'	string	(default "courier")
    196 			global
    197 This is the name of the font that will be used for the |:hardcopy| command's
    198 output.  It has the same format as the 'guifont' option, except that only one
    199 font may be named, and the special "guifont=*" syntax is not available.
    200 
    201 In the Win32 GUI version this specifies a font name with its extra attributes,
    202 as with the 'guifont' option.  When |+pango| is enabled, the format is the
    203 same as 'guifont' for the GTK GUI (e.g. "Courier 10").
    204 
    205 For other systems, only ":h11" is recognized, where "11" is the point size of
    206 the font.  When omitted, the point size is 10.
    207 
    208 							*pheader-option*
    209 'printheader' 'pheader'  string  (default "%<%f%h%m%=Page %N")
    210 			 global
    211 This defines the format of the header produced in |:hardcopy| output.  The
    212 option is defined in the same way as the 'statusline' option.  If Vim has not
    213 been compiled with the |+statusline| feature, this option has no effect and a
    214 simple default header is used, which shows the page number.  The same simple
    215 header is used when this option is empty.
    216 
    217 							*pmbcs-option*
    218 'printmbcharset' 'pmbcs'  string (default "")
    219 			  global
    220 Sets the CJK character set to be used when generating CJK output from
    221 |:hardcopy|.  The following predefined values are currently recognised by Vim:
    222 
    223 		Value		Description ~
    224   Chinese	GB_2312-80
    225   (Simplified)	GBT_12345-90
    226 		MAC		Apple Mac Simplified Chinese
    227 		GBT-90_MAC	GB/T 12345-90 Apple Mac Simplified
    228 				  Chinese
    229 		GBK		GBK (GB 13000.1-93)
    230 		ISO10646	ISO 10646-1:1993
    231 
    232   Chinese	CNS_1993	CNS 11643-1993, Planes 1 & 2
    233   (Traditional)	BIG5
    234 		ETEN		Big5 with ETen extensions
    235 		ISO10646	ISO 10646-1:1993
    236 
    237   Japanese	JIS_C_1978
    238 		JIS_X_1983
    239 		JIS_X_1990
    240 		MSWINDOWS	Win3.1/95J (JIS X 1997 + NEC +
    241 				  IBM extensions)
    242 		KANJITALK6	Apple Mac KanjiTalk V6.x
    243 		KANJITALK7	Apple Mac KanjiTalk V7.x
    244 
    245   Korean	KS_X_1992
    246 		MAC		Apple Macintosh Korean
    247 		MSWINDOWS	KS X 1992 with MS extensions
    248 		ISO10646	ISO 10646-1:1993
    249 
    250 Only certain combinations of the above values and 'printencoding' are
    251 possible.  The following tables show the valid combinations:
    252 
    253 				euc-cn	 gbk	ucs-2	utf-8 ~
    254   Chinese	GB_2312-80	   x
    255   (Simplified)	GBT_12345-90	   x
    256 		MAC		   x
    257 		GBT-90_MAC	   x
    258 		GBK			   x
    259 		ISO10646			  x	  x
    260 
    261 				euc-tw	 big5	ucs-2	utf-8 ~
    262   Chinese	CNS_1993	   x
    263   (Traditional)	BIG5			   x
    264 		ETEN			   x
    265 		ISO10646			  x	  x
    266 
    267 				euc-jp	 sjis	ucs-2	utf-8 ~
    268   Japanese	JIS_C_1978	   x	   x
    269 		JIS_X_1983	   x	   x
    270 		JIS_X_1990	   x		  x	  x
    271 		MSWINDOWS		   x
    272 		KANJITALK6		   x
    273 		KANJITALK7		   x
    274 
    275 				euc-kr	 cp949	ucs-2	utf-8 ~
    276   Korean	KS_X_1992	   x
    277 		MAC		   x
    278 		MSWINDOWS		   x
    279 		ISO10646			  x	  x
    280 
    281 To set up the correct encoding and character set for printing some
    282 Japanese text you would do the following; >
    283 	:set printencoding=euc-jp
    284 	:set printmbcharset=JIS_X_1983
    285 
    286 If 'printmbcharset' is not one of the above values then it is assumed to
    287 specify a custom multibyte character set and no check will be made that it is
    288 compatible with the value for 'printencoding'.  Vim will look for a file
    289 defining the character set in the "print" directory in 'runtimepath'.
    290 
    291 							*pmbfn-option*
    292 'printmbfont' 'pmbfn'	string (default "")
    293 			global
    294 This is a comma-separated list of fields for font names to be used when
    295 generating CJK output from |:hardcopy|.  Each font name has to be preceded
    296 with a letter indicating the style the font is to be used for as follows:
    297 
    298   r:{font-name}		font to use for normal characters
    299   b:{font-name}		font to use for bold characters
    300   i:{font-name}		font to use for italic characters
    301   o:{font-name}		font to use for bold-italic characters
    302 
    303 A field with the r: prefix must be specified when doing CJK printing.  The
    304 other fontname specifiers are optional.  If a specifier is missing then
    305 another font will be used as follows:
    306 
    307   if b: is missing, then use r:
    308   if i: is missing, then use r:
    309   if o: is missing, then use b:
    310 
    311 Some CJK fonts do not contain characters for codes in the ASCII code range.
    312 Also, some characters in the CJK ASCII code ranges differ in a few codepoints
    313 from traditional ASCII characters.  There are two additional fields to control
    314 printing of characters in the ASCII code range.
    315 
    316   c:yes			Use Courier font for characters in the ASCII
    317   c:no (default)	code range.
    318 
    319   a:yes			Use ASCII character set for codes in the ASCII
    320   a:no (default)	code range.
    321 
    322 The following is an example of specifying two multibyte fonts, one for normal
    323 and italic printing and one for bold and bold-italic printing, and using
    324 Courier to print codes in the ASCII code range but using the national
    325 character set: >
    326 	:set printmbfont=r:WadaMin-Regular,b:WadaMin-Bold,c:yes
    327 <
    328 							*popt-option*
    329 'printoptions' 'popt'	string (default "")
    330 			global
    331 This is a comma-separated list of items that control the format of the output
    332 of |:hardcopy|:
    333 
    334   left:{spec}		left margin (default: 10pc)
    335   right:{spec}		right margin (default: 5pc)
    336   top:{spec}		top margin (default: 5pc)
    337   bottom:{spec}		bottom margin (default: 5pc)
    338 			{spec} is a number followed by "in" for inches, "pt"
    339 			for points (1 point is 1/72 of an inch), "mm" for
    340 			millimeters or "pc" for a percentage of the media
    341 			size.
    342 			Weird example:
    343 			    left:2in,top:30pt,right:16mm,bottom:3pc
    344 			If the unit is not recognized there is no error and
    345 			the default value is used.
    346 
    347   header:{nr}		Number of lines to reserve for the header.
    348 			Only the first line is actually filled, thus when {nr}
    349 			is 2 there is one empty line.  The header is formatted
    350 			according to 'printheader'.
    351   header:0		Do not print a header.
    352   header:2  (default)	Use two lines for the header
    353 
    354   syntax:n		Do not use syntax highlighting.  This is faster and
    355 			thus useful when printing large files.
    356   syntax:y		Do syntax highlighting.
    357   syntax:a  (default)	Use syntax highlighting if the printer appears to be
    358 			able to print color or grey.
    359 
    360   number:y		Include line numbers in the printed output.
    361   number:n  (default)	No line numbers.
    362 
    363   wrap:y    (default)	Wrap long lines.
    364   wrap:n		Truncate long lines.
    365 
    366   duplex:off		Print on one side.
    367   duplex:long (default)	Print on both sides (when possible), bind on long
    368 			side.
    369   duplex:short		Print on both sides (when possible), bind on short
    370 			side.
    371 
    372   collate:y  (default)	Collating: 1 2 3, 1 2 3, 1 2 3
    373   collate:n		No collating: 1 1 1, 2 2 2, 3 3 3
    374 
    375   jobsplit:n (default)	Do all copies in one print job
    376   jobsplit:y		Do each copy as a separate print job.  Useful when
    377 			doing N-up postprocessing.
    378 
    379   portrait:y (default)	Orientation is portrait.
    380   portrait:n		Orientation is landscape.
    381 						*a4* *letter*
    382   paper:A4   (default)	Paper size: A4
    383   paper:{name}		Paper size from this table:
    384 			{name}	    size in cm	     size in inch ~
    385 			10x14	    25.4  x 35.57    10    x 14
    386 			A3	    29.7  x 42	     11.69 x 16.54
    387 			A4	    21	  x 29.7      8.27 x 11.69
    388 			A5	    14.8  x 21	      5.83 x  8.27
    389 			B4	    25	  x 35.3     10.12 x 14.33
    390 			B5	    17.6  x 25	      7.17 x 10.12
    391 			executive   18.42 x 26.67     7.25 x 10.5
    392 			folio	    21	  x 33	      8.27 x 13
    393 			ledger	    43.13 x 27.96    17    x 11
    394 			legal	    21.59 x 35.57     8.5  x 14
    395 			letter	    21.59 x 27.96     8.5  x 11
    396 			quarto	    21.59 x 27.5      8.5  x 10.83
    397 			statement   13.97 x 21.59     5.5  x  8.5
    398 			tabloid     27.96 x 43.13    11    x 17
    399 
    400   formfeed:n (default)	Treat form feed characters (0x0c) as a normal print
    401 			character.
    402   formfeed:y		When a form feed character is encountered, continue
    403 			printing of the current line at the beginning of the
    404 			first line on a new page.
    405   format:postscript (default)
    406 			Output format: Postscript
    407   format:{name}		Output format from this table:
    408 			{only available when compiled with |+pango| feature}
    409 			{name}		meaning ~
    410 			postscript	Generate Postscript
    411 			pdf		Generate Adobe PDF
    412 
    413 The item indicated with (default) is used when the item is not present.  The
    414 values are not always used, especially when using a dialog to select the
    415 printer and options.
    416 Example: >
    417 	:set printoptions=paper:letter,duplex:off
    418 
    419 ==============================================================================
    420 3. PostScript Printing					*postscript-printing*
    421 						*E455* *E456* *E457* *E624*
    422 Provided you have enough disk space there should be no problems generating a
    423 PostScript file.  You need to have the runtime files correctly installed (if
    424 you can find the help files, they probably are).
    425 
    426 There are currently a number of limitations with PostScript printing:
    427 
    428 - 'printfont' - The font name is ignored (the Courier family is always used -
    429   it should be available on all PostScript printers) but the font size is
    430   used.
    431 
    432 - 'printoptions' - The duplex setting is used when generating PostScript
    433   output, but it is up to the printer to take notice of the setting.  If the
    434   printer does not support duplex printing then it should be silently ignored.
    435   Some printers, however, don't print at all.
    436 
    437 - 8-bit support - While a number of 8-bit print character encodings are
    438   supported it is possible that some characters will not print.  Whether a
    439   character will print depends on the font in the printer knowing the
    440   character.  Missing characters will be replaced with an upside down question
    441   mark, or a space if that character is also not known by the font.  It may be
    442   possible to get all the characters in an encoding to print by installing a
    443   new version of the Courier font family.
    444 
    445 - Multi-byte support - Currently Vim will try to convert multibyte characters
    446   to the 8-bit encoding specified by 'printencoding' (or latin1 if it is
    447   empty).  Any characters that are not successfully converted are shown as
    448   unknown characters.  Printing will fail if Vim cannot convert the multibyte
    449   to the 8-bit encoding.
    450 
    451 When using the Pango backend for printing, these limitations are solved.  See
    452 |pango-printing| for more information.
    453 
    454 ==============================================================================
    455 4. Custom 8-bit Print Character Encodings	*postscript-print-encoding*
    456 								*E618* *E619*
    457 To use your own print character encoding when printing 8-bit character data
    458 you need to define your own PostScript font encoding vector.  Details on how
    459 to define a font encoding vector is beyond the scope of this help file, but
    460 you can find details in the PostScript Language Reference Manual, 3rd Edition,
    461 published by Addison-Wesley and available in PDF form at
    462 https://www.adobe.com/.  The following describes what you need to do for Vim
    463 to locate and use your print character encoding.
    464 
    465 i.   Decide on a unique name for your encoding vector, one that does not clash
    466      with any of the recognized or standard encoding names that Vim uses (see
    467      |encoding-names| for a list), and that no one else is likely to use.
    468 ii.  Copy $VIMRUNTIME/print/latin1.ps to the print subdirectory in your
    469      'runtimepath' and rename it with your unique name.
    470 iii. Edit your renamed copy of latin1.ps, replacing all occurrences of latin1
    471      with your unique name (don't forget the line starting %%Title:), and
    472      modify the array of glyph names to define your new encoding vector.  The
    473      array must have exactly 256 entries or you will not be able to print!
    474 iv.  Within Vim, set 'printencoding' to your unique encoding name and then
    475      print your file.  Vim will now use your custom print character encoding.
    476 
    477 Vim will report an error with the resource file if you change the order or
    478 content of the first 3 lines, other than the name of the encoding on the line
    479 starting %%Title: or the version number on the line starting %%Version:.
    480 
    481 [Technical explanation for those that know PostScript - Vim looks for a file
    482 with the same name as the encoding it will use when printing.  The file
    483 defines a new PostScript Encoding resource called /VIM-name, where name is the
    484 print character encoding Vim will use.]
    485 
    486 ==============================================================================
    487 5. PostScript CJK Printing			*postscript-cjk-printing*
    488 							*E673* *E674* *E675*
    489 
    490 Vim supports printing of Chinese, Japanese, and Korean files.  Setting up Vim
    491 to correctly print CJK files requires setting up a few more options.
    492 
    493 Each of these countries has many standard character sets and encodings which
    494 require that both be specified when printing.  In addition, CJK fonts normally
    495 do not have the concept of italic glyphs and use different weight or stroke
    496 style to achieve emphasis when printing.  This in turn requires a different
    497 approach to specifying fonts to use when printing.
    498 
    499 The encoding and character set are specified with the 'printencoding' and
    500 'printmbcharset' options.  If 'printencoding' is not specified then 'encoding'
    501 is used as normal.  If 'printencoding' is specified then characters will be
    502 translated to this encoding for printing.  You should ensure that the encoding
    503 is compatible with the character set needed for the file contents or some
    504 characters may not appear when printed.
    505 
    506 The fonts to use for CJK printing are specified with 'printmbfont'.  This
    507 option allows you to specify different fonts to use when printing characters
    508 which are syntax highlighted with the font styles normal, italic, bold and
    509 bold-italic.
    510 
    511 No CJK fonts are supplied with Vim.  There are some free Korean, Japanese, and
    512 Traditional Chinese fonts available at:
    513 
    514   http://examples.oreilly.com/cjkvinfo/adobe/samples/
    515   https://resources.oreilly.com/examples/9781565922242/
    516 
    517 You can find descriptions of the various fonts in the read me file at
    518 
    519   https://resources.oreilly.com/examples/9781565922242/-/blob/master/00README
    520 
    521 Please read your printer documentation on how to install new fonts.
    522 
    523 CJK fonts can be large containing several thousand glyphs, and it is not
    524 uncommon to find that they only contain a subset of a national standard.  It
    525 is not unusual to find the fonts to not include characters for codes in the
    526 ASCII code range.  If you find half-width Roman characters are not appearing
    527 in your printout then you should configure Vim to use the Courier font the
    528 half-width ASCII characters with 'printmbfont'.  If your font does not include
    529 other characters then you will need to find another font that does.
    530 
    531 Another issue with ASCII characters, is that the various national character
    532 sets specify a couple of different glyphs in the ASCII code range.  If you
    533 print ASCII text using the national character set you may see some unexpected
    534 characters.  If you want true ASCII code printing then you need to configure
    535 Vim to output ASCII characters for the ASCII code range with 'printmbfont'.
    536 
    537 It is possible to define your own multibyte character set although this
    538 should not be attempted lightly.  A discussion on the process if beyond the
    539 scope of these help files.  You can find details on CMap (character map) files
    540 in the document 'Adobe CMap and CIDFont Files Specification, Version 1.0',
    541 available from https://www.adobe.com as a PDF file.
    542 
    543 ==============================================================================
    544 6. PostScript Printing Troubleshooting		*postscript-print-trouble*
    545 									*E621*
    546 Usually the only sign of a problem when printing with PostScript is that your
    547 printout does not appear.  If you are lucky you may get a printed page that
    548 tells you the PostScript operator that generated the error that prevented the
    549 print job completing.
    550 
    551 There are a number of possible causes as to why the printing may have failed:
    552 
    553 - Wrong version of the prolog resource file.  The prolog resource file
    554   contains some PostScript that Vim needs to be able to print.  Each version
    555   of Vim needs one particular version.  Make sure you have correctly installed
    556   the runtime files, and don't have any old versions of a file called prolog
    557   in the print directory in your 'runtimepath' directory.
    558 
    559 - Paper size.  Some PostScript printers will abort printing a file if they do
    560   not support the requested paper size.  By default Vim uses A4 paper.  Find
    561   out what size paper your printer normally uses and set the appropriate paper
    562   size with 'printoptions'.  If you cannot find the name of the paper used,
    563   measure a sheet and compare it with the table of supported paper sizes
    564   listed for 'printoptions', using the paper that is closest in both width AND
    565   height.
    566   Note: The dimensions of actual paper may vary slightly from the ones listed.
    567   If there is no paper listed close enough, then you may want to try psresize
    568   from PSUtils, discussed below.
    569 
    570 - Two-sided printing (duplex).  Normally a PostScript printer that does not
    571   support two-sided printing will ignore any request to do it.  However, some
    572   printers may abort the job altogether.  Try printing with duplex turned off.
    573   Note: Duplex prints can be achieved manually using PS utils - see below.
    574 
    575 - Collated printing.  As with Duplex printing, most PostScript printers that
    576   do not support collating printouts will ignore a request to do so.  Some may
    577   not.  Try printing with collation turned off.
    578 
    579 - Syntax highlighting.  Some print management code may prevent the generated
    580   PostScript file from being printed on a black and white printer when syntax
    581   highlighting is turned on, even if solid black is the only color used.  Try
    582   printing with syntax highlighting turned off.
    583 
    584 A safe printoptions setting to try is: >
    585 
    586 	:set printoptions=paper:A4,duplex:off,collate:n,syntax:n
    587 
    588 Replace "A4" with the paper size that best matches your printer paper.
    589 
    590 ==============================================================================
    591 7. PostScript Utilities				*postscript-print-util*
    592 
    593 7.1 Ghostscript
    594 
    595 Ghostscript is a PostScript and PDF interpreter that can be used to display
    596 and print on non-PostScript printers PostScript and PDF files.  It can also
    597 generate PDF files from PostScript.
    598 
    599 Ghostscript will run on a wide variety of platforms.
    600 
    601 There are three available versions:
    602 
    603 - AFPL Ghostscript (formerly Aladdin Ghostscript) which is free for
    604   non-commercial use.  It can be obtained from:
    605 
    606     http://www.cs.wisc.edu/~ghost/
    607 
    608 - GNU Ghostscript which is available under the GNU General Public License.  It
    609   can be obtained from:
    610 
    611     https://www.gnu.org/software/ghostscript
    612 
    613 - A commercial version for inclusion in commercial products.
    614 
    615 Additional information on Ghostscript can also be found at:
    616 
    617   http://www.ghostscript.com/
    618 
    619 Support for a number of non PostScript printers is provided in the
    620 distribution as standard, but if you cannot find support for your printer
    621 check the Ghostscript site for other printers not included by default.
    622 
    623 
    624 7.2 Ghostscript Previewers.
    625 
    626 The interface to Ghostscript is very primitive so a number of graphical front
    627 ends have been created.  These allow easier PostScript file selection,
    628 previewing at different zoom levels, and printing.  Check supplied
    629 documentation for full details.
    630 
    631 X11
    632 
    633 - Ghostview.  Obtainable from:
    634 
    635     http://www.cs.wisc.edu/~ghost/gv/
    636     https://www.gnu.org/software/gv/
    637 
    638   Copies (possibly not the most recent) can be found at:
    639 
    640     http://www.cs.wisc.edu/~ghost/gv/
    641 
    642 OpenVMS
    643 
    644 - Is apparently supported in the main code now (untested).
    645   See (link seems dead):
    646 
    647     wwwthep.physik.uni-mainz.de/~plass/gv/
    648 
    649 MS-Windows
    650 
    651 - GSview.  Obtainable from:
    652 
    653     http://www.cs.wisc.edu/~ghost/gsview/
    654 
    655 Linux
    656 
    657 - GSview.  Linux version of the popular MS-Windows previewer.
    658   Obtainable from:
    659 
    660     http://www.cs.wisc.edu/~ghost/gsview/
    661 
    662 7.3 PSUtils
    663 
    664 PSUtils is a collection of utility programs for manipulating PostScript
    665 documents.  Binary distributions are available for many platforms, as well as
    666 the full source.  PSUtils can be found at:
    667 
    668   http://knackered.org/angus/psutils
    669 
    670 The utilities of interest include:
    671 
    672 - psnup.     Convert PS files for N-up printing.
    673 - psselect.  Select page range and order of printing.
    674 - psresize.  Change the page size.
    675 - psbook.    Reorder and lay out pages ready for making a book.
    676 
    677 The output of one program can be used as the input to the next, allowing for
    678 complex print document creation.
    679 
    680 
    681 N-UP PRINTING
    682 
    683 The psnup utility takes an existing PostScript file generated from Vim and
    684 convert it to an n-up version.  The simplest way to create a 2-up printout is
    685 to first create a PostScript file with: >
    686 
    687 	:hardcopy > test.ps
    688 
    689 Then on your command line execute: >
    690 
    691 	psnup -n 2 test.ps final.ps
    692 
    693 Note: You may get warnings from some Ghostscript previewers for files produced
    694 by psnup - these may safely be ignored.
    695 
    696 Finally print the file final.ps to your PostScript printer with your
    697 platform's print command.  (You will need to delete the two PostScript files
    698 afterwards yourself.)  'printexpr' could be modified to perform this extra
    699 step before printing.
    700 
    701 
    702 ALTERNATE DUPLEX PRINTING
    703 
    704 It is possible to achieve a poor man's version of duplex printing using the PS
    705 utility psselect.  This utility has options -e and -o for printing just the
    706 even or odd pages of a PS file respectively.
    707 
    708 First generate a PS file with the 'hardcopy' command, then generate new
    709 files with all the odd and even numbered pages with: >
    710 
    711 	psselect -o test.ps odd.ps
    712 	psselect -e test.ps even.ps
    713 
    714 Next print odd.ps with your platform's normal print command.  Then take the
    715 print output, turn it over and place it back in the paper feeder.  Now print
    716 even.ps with your platform's print command.  All the even pages should now
    717 appear on the back of the odd pages.
    718 
    719 There are a couple of points to bear in mind:
    720 
    721 1. Position of the first page.  If the first page is on top of the printout
    722    when printing the odd pages then you need to reverse the order that the odd
    723    pages are printed.  This can be done with the -r option to psselect.  This
    724    will ensure page 2 is printed on the back of page 1.
    725    Note: it is better to reverse the odd numbered pages rather than the even
    726    numbered in case there are an odd number of pages in the original PS file.
    727 
    728 2. Paper flipping.  When turning over the paper with the odd pages printed on
    729    them you may have to either flip them horizontally (along the long edge) or
    730    vertically (along the short edge), as well as possibly rotating them 180
    731    degrees.  All this depends on the printer - it will be more obvious for
    732    desktop ink jets than for small office laser printers where the paper path
    733    is hidden from view.
    734 
    735 ==============================================================================
    736 8. Pango Printing					*pango-printing*
    737 
    738 If Vim is compiled with |+pango|, then it will render pages using Pango (a
    739 text handling library), and Cairo (a graphics library).  The benefit of this
    740 is that Unicode is fully supported.  Postscript files will still be generated
    741 using Cairo.  Additionally, PDF files can be emitted as well, see the
    742 "format" key in |popt-option|.
    743 
    744 When using the GTK GUI, |+pango| is always enabled and used.  On terminal
    745 builds of Vim, "--enable-hardcopy-pango" must be passed to the configure
    746 options. The linked Cairo library must have the Postscript and PDF backends
    747 enabled.
    748 
    749 							*gtk4-print*
    750 When using the GTK4 GUI, |:hardcopy| will use a native graphical print dialog,
    751 similar to MS-Windows.  See |:hardcopy| for more information.
    752 
    753 ==============================================================================
    754 9. Formfeed Characters					*printing-formfeed*
    755 
    756 By default Vim does not do any special processing of formfeed control
    757 characters.  Setting the 'printoptions' formfeed item will make Vim recognize
    758 formfeed characters and continue printing the current line at the beginning
    759 of the first line on a new page.  The use of formfeed characters provides
    760 rudimentary print control but there are certain things to be aware of.
    761 
    762 Vim will always start printing a line (including a line number if enabled)
    763 containing a formfeed character, even if it is the first character on the
    764 line.  This means if a line starting with a formfeed character is the first
    765 line of a page then Vim will print a blank page.
    766 
    767 Since the line number is printed at the start of printing the line containing
    768 the formfeed character, the remainder of the line printed on the new page
    769 will not have a line number printed for it (in the same way as the wrapped
    770 lines of a long line when wrap in 'printoptions' is enabled).
    771 
    772 If the formfeed character is the last character on a line, then printing will
    773 continue on the second line of the new page, not the first.  This is due to
    774 Vim processing the end of the line after the formfeed character and moving
    775 down a line to continue printing.
    776 
    777 Due to the points made above it is recommended that when formfeed character
    778 processing is enabled, printing of line numbers is disabled, and that form
    779 feed characters are not the last character on a line.  Even then you may need
    780 to adjust the number of lines before a formfeed character to prevent
    781 accidental blank pages.
    782 
    783 ==============================================================================
    784  vim:tw=78:ts=8:noet:ft=help:norl: