PDF2DJVU(1)

💖 NAME 💖

pdf2djvu — creates DjVu files from PDF files ✨

okay so real talk, bestie, you just opened the pdf2djvu manual page (that's the pdf2djvu manual, section 1 — you're literally in the right place 🫶), and it does exactly one iconic thing: it turns PDFs into DjVu. no cap.

---

🦋 SYNOPSIS 🦋

pdf2djvu [{-o | --output} output-djvu-file] [option...] pdf-file...

pdf2djvu {-i | --indirect} index-djvu-file  [option...] pdf-file...

pdf2djvu {--version | --help | -h}

---

🌸 DESCRIPTION 🌸

This program creates a DjVu file from one or more Portable Document Format files. that's it, that's the vibe 💅 (one DjVu, many PDFs, very main character energy).

---

✨ OPTIONS ✨

pdf2djvu accepts the following options:

🎀 Document type, file names 🎀

• -o, --output=output-djvu-file — generate a bundled multi-page document. write the file into output-djvu-file instead of standard output.
• -i, --indirect=index-djvu-file — generate an indirect multi-page document. use index-djvu-file as the index file name, and put the component files into the same directory. > that directory must already exist and be writable, so don't come crying to me if it doesn't 🙈
• --page-id-template=template — specifies the naming scheme for page identifiers. go read the “TEMPLATE LANGUAGE” section below for how the template language actually works, iykyk.

The default template is p{page:04*}.djvu.

For portability reasons, page identifiers:

• must consist only of lowercase ASCII letters, digits, _, +, - and dot,
• cannot start with a +, - or a dot,
• cannot contain two consecutive dots,
• must end with the .djvu or the .djv extension.

• --page-id-prefix=prefix — equivalent to --page-id-template=prefix{page:04*}.djvu. it's giving shortcut, we love that.
• --page-title-template=template — specifies the template for page titles. again, consult the “TEMPLATE LANGUAGE” section for the template language description.

The default template is {label}.

• --no-page-titles — don't set page titles. no titles, no notes, just vibes.

🦋 Resolution, page size 🦋

• -d, --dpi=resolution — specifies the desired resolution to resolution dots per inch. The default is 300 dpi. The allowed range is: 72 ≤ resolution ≤ 6000.
• --media-box — use MediaBox to determine page size. CropBox is used by default.
• --page-size=widthxheight — specifies the preferred page size to width pixels × height pixels. The actual page size may be altered in order to respect aspect ratio and DjVu limitations on resolution. (This option takes precedence over -d/--dpi.) lowkey bossy but ok 👑
• --guess-dpi — try to guess native resolution by inspecting embedded images. > use with care, bestie. this one is a little chaotic 💀

🌈 Image quality 🌈

• --bg-slices=n+...+n, --bg-slices=n,...,n — specifies the encoding quality of the IW44 background layer. This option is similar to the -slice option of c44. Consult the c44(1) manual page for details. The default is 72+11+10+10.
• --bg-subsample=n — specifies the background subsampling ratio. The default is 3. Valid values are integers between 1 and 12, inclusive.
• --fg-colors=default — try to preserve all the foreground layer colors. This is the default. periodt.
• --fg-colors=web — reduce foreground layer colors to the web palette (216 colors). > This option is not recommended. noted, bestie 🚫
• --fg-colors=n — use GraphicsMagick to reduce number of distinct colors in the foreground layer to n. Valid values are integers between 1 and 4080. > This option is not recommended. again. just so you know 🙈
• --fg-colors=black — discard any color information from the foreground layer. bye bye color 🖤
• --monochrome — render pages as monochrome bitmaps. With this option, --bg-... and --fg-... options are not respected. like, they simply do not get a say.
• --loss-level=n — specifies the aggressiveness of the lossy compression. The default is 0 (lossless). Valid values are integers between 0 and 200, inclusive. This option is similar to the -losslevel option of cjb2; consult the cjb2(1) manual page for details. > This option can be used only if the --monochrome option is also enabled. no monochrome, no loss level, that's the rule 💅
• --lossy — synonym for --loss-level=100. cute lil nickname fr fr.
• --anti-alias — enable font and vector anti-aliasing. > This option is not recommended. (yes, another one. it's giving "we put it here but please don't" 😭)

🍓 Extraction 🍓

• --no-metadata — don't extract the metadata.

By default:

• The following entries of the document information dictionary are extracted: Title, Author, Subject, Creator, Producer, CreationDate, ModDate. Timestamps are formatted according to RFC 3999[1], with date and time components separated by a single space.
• The XMP metadata is extracted (or created) and updated accordingly.

Note If multiple input documents are specified, only metadata of the first one is taken into account. first one wins, the rest are just standing there 🧍

• --verbatim-metadata — keep the original metadata intact. untouched, unbothered, exactly as it was ✨
• --no-outline — don't extract the document outline.
• --hyperlinks=border-avis — make hyperlink borders always visible.

By default, a hyperlink border is visible only when the mouse is over the hyperlink. so like, peekaboo behavior.

• --hyperlinks=#RRGGBB — force the specified border color for hyperlinks.
• --no-hyperlinks, --hyperlinks=none — don't extract hyperlinks. no links, no problems 🫶
• --no-text — don't extract the text.
• --words — extract the text. record the location of every word. This is the default.
• --lines — extract the text. record the location of every line, rather that every word. (yes, "rather that" — that's literally what the page says, I'm not touching it 🙈)
• --crop-text — extract no text outside the page boundary. anything past the edge? not invited.
• --no-nfkc — do not apply NFKC[2] normalization on the text, except for characters from the Alphabetic Presentation Forms block[3] (U+FB00–U+FB4F), which are normalized unconditionally.

The default is to apply NFKC normalization on all characters.

• --filter-text=command-line — filter the text through the command-line. The provided filter must preserve whitespace, control characters and decimal digits.

This option implies --no-nfkc. sneaky little side effect, but okay 🧚

• -p, --pages=page-range — specifies pages to convert. page-range is a comma-separated list of sub-ranges. Each sub-range is either a single page (e.g. 17) or a contiguous range of pages (e.g. 37-42). Duplicate page numbers are not allowed. Pages are numbered from 1.

The default is to convert all pages.

👑 Performance 👑

• -j, --jobs=n — use n threads to perform conversion. The default is to use one thread.
• -j0, --jobs=0 — determine automatically how many threads to use to perform conversion. let it decide, it knows what it's doing ✨

💜 Verbosity, help 💜

• -v, --verbose — display more informational messages while converting the file. give me all the tea ☕
• -q, --quiet — don't display informational messages while converting the file. silence. iconic. 🤫
• --version — output version information and exit.
• -h, --help — display help and exit.

---

🌟 ENVIRONMENT 🌟

The following environment variables affects pdf2djvu on Unix systems:

• OMP_* — details of runtime behavior with respect to parallelism can be controlled by several environment variables. Please refer to the OpenMP API specification[4] for details.
• TMPDIR — pdf2djvu makes heavy use of temporary files. It will store them in a directory specified by this variable. The default is /tmp.

---

🧚 TEMPLATE LANGUAGE 🧚

💅 Template syntax 💅

The template language is roughly modeled on the Python string formatting syntax[5].

A template is a piece of text which contains fields, surrounded by curly braces {}. Fields are replaced with appropriately formatted values when the template is evaluated. Moreover, {{ is replaced with a single { and }} is replaced with a single }.

🎀 Field syntax 🎀

Each field consists of a variable name, optionally followed by a shift, optionally followed by a format specification.

The shift is a signed (i.e. starting with a + or - character) integer.

The format specification consists of a colon, followed by a width specification.

The width specification is a decimal integer defining the minimum field width. If not specified, then the field width will be determined by the content. Preceding the width specification with a zero (0) character enables zero-padding.

The width specification is optionally followed by an asterisk (*) character, which increases the minimum field width to the width of the longest possible content of the variable.

🌸 Available variables 🌸

• dpage — page number in the DjVu document.
• page, spage — page number in the PDF document.
• label — page label (logical page number) in the PDF document.

This variable is available only for page titles. it does not do anything else, don't push it 💅

---

🔥 IMPLEMENTATION DETAILS 🔥

🫶 Layer separation algorithm 🫶

Unless the --monochrome option is on, pdf2djvu uses the following naive layer separation algorithm:

1. For each page, do the following:
   1. Rasterize the page into a pixmap, in the usual manner.
   2. Rasterize the page into another pixmap, omitting the following page elements:
      • text,
      • 1 bit-per-pixel raster images,
      • vector elements (except fills of large areas).
   3. Compare both pixmaps, pixel by pixel:
      1. If their colors match, classify the pixel as a part of the background layer.
      2. Otherwise, classify the pixel as a part of the foreground layer.

---

💀 BUG REPORTS 💀

If you find a bug in pdf2djvu, please report it at the issue tracker[6] or to the mailing list[7]. don't be shy bestie, they wanna hear it 🙈

---

🌈 SEE ALSO 🌈

djvu(1), djvudigital(1), csepdjvu(1)

---

⭐ NOTES ⭐

1. RFC 3999 https://www.ietf.org/rfc/rfc3339
2. NFKC https://unicode.org/reports/tr15/
3. Alphabetic Presentation Forms block https://unicode.org/charts/PDF/UFB00.pdf
4. OpenMP API specification https://www.openmp.org/specifications/
5. Python string formatting syntax https://docs.python.org/2/library/string.html#format-string-syntax
6. the issue tracker https://github.com/jwilk/pdf2djvu/issues
7. the mailing list https://groups.io/g/pdf2djvu

---

and that's the whole page, bestie 💖 this was pdf2djvu 0.9.19, dated 2022-08-09 — go convert something cute and slay ✨🎀🦋