PAPS(1)

📦
version 0.8.0 · 4 versions
, in centos-stream 10, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu stonking

💖 PAPS — section 1, General Commands Manual 💖

okay bestie, sit down, hydrate, and let me tell you about paps — she's a text-to-PostScript converter and she is THAT girl. 🫶

✨ NAME ✨

paps — text to PostScript converter using Pango 🌸

🎀 SYNOPSIS 🎀

paps [options] files...

🦋 DESCRIPTION 🦋

paps reads an input file and writes a PostScript language or user specified format rendering of that file to standard output. She takes international text in any locale, no cap, and she does internationalized text layout — that means text shaping and bidirectional text rendering. 💅

If you don't hand her a filename argument, paps reads the standard input. And if standard input happens to be a terminal, your input is terminated by an EOF signal, usually Control-d. (iykyk 😌)

✨ OPTIONS ✨

paps follows the usual GNU command line syntax, and long options start with two dashes. Here's the full rundown, bestie — nothing skipped, everything's here. 💖

  • -h, --help — shows a summary of the options. your little cheat sheet 🎀
  • --landscape — landscape output. default is portrait.
  • --columns=cl — format the output into cl columns. default is 1.
heads up: this option is not related to terminal length the way people mean when they say "80 columns terminal". different thing entirely, don't get it twisted 💀
  • --font=desc — use a font based on the description desc. default is "Monospace 12". the format of the string representation is:
"[family-list] [style-options] [size]"

where family-list is a comma separated list of families, optionally terminated by a comma; style-options is a whitespace separated list of words where each word describes one of style, variant, weight, or stretch; and size is a decimal number for size in points, e.g. "Courier,Monospace Bold Italic 10". slay ✨

  • -o, --output=file — output file. default is stdout. the output format gets set based on the file's extension when --format isn't provided. 👑
  • --rtl — do right-to-left (RTL) text layout and align the text to the right. text direction is detected automatically. use this option when you want explicit RTL layout and right alignment.
  • --justify — justify the layout. stretches complete lines to fill the entire width. main character energy, filling the whole page fr fr.
  • --wrap=wm — use line wrapping mode wm. default is word-char.
    • word — wrap lines at word boundaries
    • char — wrap lines at character boundaries
    • word-char — wrap lines at word boundaries, but fall back to character boundaries if there isn't enough space for a full word
  • --show-wrap — mark wrapped lines with special characters. 🎀
  • --paper=ps — choose the paper size. accepted paper sizes are 'legal', 'letter', 'A3' and 'A4'. default is A4.
  • --gravity=gr — set the base glyph orientation. default is auto.
    • south — glyphs stand upright
    • east — glyphs are rotated 90 degrees clockwise
    • north — glyphs are upside-down
    • west — glyphs are rotated 90 degrees counter-clockwise
    • auto — gravity is resolved from the context
  • --gravity-hint=gh — set how horizontal scripts behave in a vertical context. default is natural.
    • natural — scripts will take their natural gravity based on the base gravity and the script
    • strong — always use the base gravity, regardless of the script
    • line — for scripts not in their natural direction (e.g. Latin in East gravity), choose per-script gravity such that every script respects the line progression. this means Latin and Arabic will take opposite gravities and both flow top-to-bottom, for example.
  • --format=fmt — choose the output format. default is ps.
    • ps — PostScript
    • pdf — Portable Document Format
    • svg — Scalable Vector Graphics

📏 Postscript points

Each postscript point equals to 1/72 of an inch. 36 points are 1/2 of an inch. (math girlies stay winning 🧮✨)

  • --bottom-margin=bm — set the bottom margin. default is 36 postscript points.
  • --top-margin=tm — set the top margin. default is 36 postscript points.
  • --left-margin=lm — set the left margin. default is 36 postscript points.
  • --right-margin=rm — set the right margin. default is 36 postscript points.
  • --gutter-width=gw — set the gutter width. default is 40 postscript points.
  • --header — draw a page header with the document name, date and page number for each page. the header is not printed by default.
  • --header-left=fmt — sets the formatting for the left side of the header. see FORMAT for an explanation of the header and footer formatting. default is the current localized date.
  • --header-center=fmt — sets the formatting for the center of the header. see FORMAT for an explanation of the header and footer formatting. default is the filename.
  • --header-right=fmt — sets the formatting for the center of the header. see FORMAT for an explanation of the header and footer formatting. default is the Page number.
  • --footer — draw a page footer with the document name, date and page number for each page. the footer is not printed by default.
  • --footer-left=fmt — sets the formatting for the left side of the footer. see FORMAT for an explanation of the footer and footer formatting. the default formatting is an empty string.
  • --footer-center=fmt — sets the formatting for the center of the footer. see FORMAT for an explanation of the footer and footer formatting. the default formatting is an empty string.
  • --footer-right=fmt — sets the formatting for the center of the footer. see FORMAT for an explanation of the footer and footer formatting. the default formatting is an empty string.
  • --title="text" — use text as the title string for the page header. by default the input filename or "stdin" is used.
  • --markup — interpret the input as pango markup. the Pango Text Attribute Markup Language lets you mark parts of the text with tags that define additional attributes such as font face, size, weight, colors, or text decoration like underline or strikethrough. ✨
  • --encoding=enc — assume the encoding of the input text is enc. by default the encoding of the current locale is used (e.g. UTF-8).
  • --lpi=lines — set the number of lines per inch. this determines the line spacing.
  • --cpi=chars — set the number of characters per inch. this is an alternative method of specifying the font size.
  • --g-fatal-warnings — make all glib warnings fatal. 💀

🚦 EXIT STATUS 🚦

the following exit values are returned:

  1. 0 — successful completion.
  2. 1 — an error occurred.

the header and footers may be formatted by a mini language based on the python f-strings. 🐍

text outside of squiggly brackets is entered literally in the output. text inside squiggly brackets contains one of the following predefined list of variables:

  • now — the current time
  • mtime — the modification time of the file being printed
  • page_idx — the page index of the page
  • num_pages — the total number of pages in the document
  • filename — the filename (basename) of the document
  • path — the full path of the document

🌈 EXAMPLES 🌈

Example 1 — Printing UTF-8 text file

the following command can be used to print a file in any of the UTF-8 based locales, if the file is in UTF-8 or a compatible codeset.

$ paps en_US_UTF-8.txt

by default paps will print a PostScript rendering to standard output. send the output to a printer using lp:

$ paps en_US_UTF-8.txt | lp

or to a file using redirection or the -o option:

$ paps en_US_UTF-8.txt > out.ps
$ paps -o out.ps en_US_UTF-8.txt

Example 2 — Specify encoding

to print a file in a specific encoding regardless of the current locale setting, use the --encoding option. here's an example for a Japanese EUC encoded input file:

$ paps --encoding eucjp ja_JP_eucjp.txt > out.ps

paps will still use the current locale setting to prioritize the available fonts for the current language. 🎀

Example 3 — Specify locale

override the LC_ALL environment variable to run paps in a different locale.

$ LC_ALL=ja_JP.eucjp paps ja_JP_eucjp.txt > out.ps

here paps will assume the input is in Japanese EUC encoding and will use the Japanese eucjp locale to render the output. if --header is added, the date is printed in Japanese. 🇯🇵

override the header and the footer to show only the page in the middle of the footer.

$ paps --separation-lines -o /tmp/foo.pdf --header --header-left='' \
  --header-center='{path}' --header-right='' --footer \
  --footer-left='Printed {now:%c}' \
  --footer-right='Page {page_idx}/{num_pages}' \
  `pwd`/paps.ccx

and here's the paragraph that comes with this example, word for word, because we keep everything around here:

here paps will assume the input is in Japanese EUC encoding and will use the Japanese eucjp locale to render the output. if --header is added, the date is printed in Japanese.

🌸 ENVIRONMENT VARIABLES 🌸

paps uses locale environment variables to determine her behavior. the following categories are used:

  • LC_CTYPE — to assume the encoding of the input. this can be overridden by --encoding.
  • LC_TIME — to format the date for the header.

font selection is also affected by the current locale. Example 3 describes how to run paps in a different locale. 💅

👀 SEE ALSO 👀

fc-match(1), setlocale(3C)

👑 AUTHOR 👑

paps was written by Dov Grobgeld <dov.grobgeld@gmail.com>.

this manual page was written by Lior Kaplan <kaplan@debian.org>, for the Debian project (but may be used by others).

okay that's the whole page, bestie, and here's your cute little sign-off: this one comes from the General Commands Manual and it's dated December 20, 2022. 💖 go print something pretty, you've got this 🫶✨🎀

📦 where this page comes from