pstotext(1)

📦 version 1.9, in ubuntu jammy

✨ pstotext(1) ✨

okay bestie, sit down, we're doing the pstotext page from General Commands Manual and it's honestly such a useful little gremlin 💖

🌸 NAME 🌸

pstotext — pull ASCII text out of a PostScript or PDF file, no cap

🎀 SYNTAX 🎀

pstotext [option|pathname]...

and the option situation includes, in no particular order of slay:

  • -cork
  • -landscape
  • -landscapeOther
  • -portrait
  • -
  • -output file
  • -gs command
  • -debug
  • -bboxes

💅 DESCRIPTION 💅

so pstotext reads one or more PostScript or PDF files, and it writes to standard output a representation of the plain text that would be displayed if the PostScript file were printed. and like… is that representation perfect? no babes, it's an approximation — the DETAILS section below is literally going to explain why. but it's still lowkey iconic, because it's super useful for information retrieval (think running grep(1), or building a whole full-text index) or for recovering the text from a PostScript file where the source is just… gone. lost. vanished. we've all been there 😭

pstotext calls Ghostscript, and it requires Aladdin Ghostscript version 3.51 or newer. Ghostscript has to be invokable on the current search path as gs. OR — if that's not giving, you can use the -gs option to specify the command (pathname and options) to run Ghostscript. for example, on Windows you might do:

-gs "c:\gs\gswin32c.exe -Ic:\gs;c:\gs\fonts"

pstotext reads and processes its command line from left to right, and it ignores the case of options (so don't stress about caps, bestie). when it hits a pathname, it opens the file and expects to find a PostScript job or PDF document to process. the option - means read and process a PostScript job from standard input. and if there are no - or pathname arguments at all? it just reads a PostScript job from standard input anyway. (PDF documents require random access, hence they cannot be read from standard input — that's just the rules 🫶) you can use the -output option to specify an output file, and remember to invoke it before the input file, okay? otherwise pstotext writes to standard output.

the -cork option is only relevant for PostScript files produced by dvips from TeX or LaTeX documents. what it does is tell pstotext to use the Cork encoding (known as T1 in LaTeX) rather than the old TeX text encoding (known as OT1 in LaTeX). unfortunately — and this is the annoying part — files produced by dvips don't distinguish which font encodings were used. tragic. 💀

the -landscape and -landscapeOther options should be used for documents that must be rotated 90 degrees clockwise or counterclockwise, respectively, in order to be readable. one's clockwise, one's counterclockwise, pick your fighter.

the -debug and -bboxes options are mostly of use for the maintainers of pstotext (hi kings 👑). -debug shows Ghostscript output and error messages. -bboxes outputs one word per line with bounding box information.

🔥 DETAILS 🔥

here's the tea on how it actually works. pstotext does its thing by telling Ghostscript to load a PostScript library that makes it write to its standard output information about each string rendered by a PostScript job or PDF document. that info includes the characters of the string, plus enough additional information to approximate the string's bounding rectangle. then pstotext post-processes all of that and outputs a sequence of words delimited by space, newline, and formfeed.

pstotext outputs words in the same sequence as they are rendered by the document. that usually — but not always — follows the order a human would read the words on a page. within this sequence, words get separated by either space or newline depending on whether or not they fall on the same line. each page is terminated with a formfeed. and if you use the incorrect option from the set {-portrait, -landscape, -landscapeOther}, pstotext is likely to substitute newline for space. so like… choose wisely 💅

a PostScript job or PDF document often renders one word as several strings, in order to get correct spacing between particular pairs of characters. pstotext does its best to assemble these strings back into words, using a simple heuristic: strings separated by a distance of less than 0.3 times the minimum of the average character widths in the two strings are considered to be part of the same word. note that this typically causes leading and trailing punctuation characters to be included with a word. so yeah, punctuation tags along like it's in the group chat whether you invited it or not 🙈

the PostScript language provides a flexible encoding scheme by which character codes in strings select specific characters (symbols), so a PostScript job is free to use any character code. on the other hand, pstotext always translates to the ISO 8859-1 (Latin-1) character code, which is an extension to ASCII covering most of the Western European languages. when a character isn't present in ISO 8859-1, pstotext uses a sequence of characters, e.g. "---" for em dash or "A\226" for Abreve. pstotext can be fooled by a font whose Encoding vector doesn't follow Adobe's conventions, but it contains heuristics allowing it to handle a wide variety of misbehaving fonts. misbehaving fonts stay misbehaving, but we cope ✨

(pstotext no longer translates hyphen (\255) to minus (\055).) — yes that's a real note, it's in the original, we're keeping it, periodt.

💜 AUTHOR 💜

  • Andrew Birrell (PostScript libraries)
  • Paul McJones (application)
  • Russell Lang (Windows and OS/2 adaptation)
  • Hunter Goatley (VMS adaptation)

🦋 SEE ALSO 🦋

pstotext incorporates technology originally developed for the Virtual Paper project at SRC; see http://www.research.digital.com/SRC/virtualpaper/.

as mentioned above, pstotext invokes Ghostscript. see gs(1) or http://www.cs.wisc.edu/~ghost/.

Copyright 1995-8 Digital Equipment Corporation. Distributed only by permission. See file /usr/share/doc/pstotext/copyright for details.

Last modified on Sat Feb  5 21:00:00 AEST 2000 by rjl
     modified on Fri Jun  5 14:02:37 PDT 1998 by mcjones
     modified on Wed Jun  7 17:47:56 PDT 1995 by birrell

This file was generated automatically by mtex software; see the mtex home page at http://www.research.digital.com/SRC/mtex/.

and that's the whole page bestie 🫶 go forth and extract that text. this was pstotext(1), part of the General Commands Manual, and the version/date lore at the bottom says last modified Sat Feb 5 21:00:00 AEST 2000 by rjl. slay 💖

📦 where this page comes from