pdfoutline(1)

💖 pdfoutline(1) — the fntsample girlies' bookmark maker 💖

okay bestie, so this is pdfoutline, a lil tool from the fntsample fam that slides outlines (aka bookmarks, the lil clicky sidebar thing 👑) into your PDFs. she's simple, she's iconic, she has zero options, and honestly? slay.

---

✨ NAME ✨

pdfoutline — add outlines (aka bookmarks) to PDF files 🎀

---

🌸 SYNOPSIS 🌸

pdfoutline input.pdf outlines.txt output.pdf

---

🦋 DESCRIPTION 🦋

so here's the vibe: pdfoutline reads the input file you hand it as the first argument, sprinkles in the outlines from the text file you give as the second argument, and saves the whole glow-up to the file named in the third argument. three files, no drama, no cap 💅

the outlines file has to be built out of lines that look exactly like this:

<level> <page> Outline text

okay so breaking it down:

• <level> and <page> are both integers, bestie. no decimals, no vibes-based numbers.
• each field has to be separated by exactly one space — one. single. space. not two, not a tab, not a whole paragraph of space. the way that one space matters is lowkey wild 😭
• every <level> value has to be greater than or equal to the <level> of the first line. (so if line one is level 0, everything after lives at 0 or deeper, got it? 🫶)
• page numbering starts with 1. not 0. we're not doing zero-indexed here, periodt.

your outlines file can also have comments — those start with a # in the first column. comments and empty lines just get ignored, they're background characters fr fr. 🙈

and the text is expected to be in UTF-8 encoding. keep it cute, keep it UTF-8. ✨

---

✨ OPTIONS ✨

• none. pdfoutline accepts no options. that's it. that's the whole list. she's a minimalist, she's a main character, she does one thing 💅

---

🍓 EXAMPLES 🍓

here's an example outlines data file, in all her glory:

0 1 Document title
1 1 Chapter 1
2 1 Chapter 1.1
2 2 Chapter 1.2
1 3 Chapter 2

and using that file gives you outlines like this, look at the lil tree structure go 🌈:

Document title
+-Chapter 1
| +-Chapter 1.1
| +-Chapter 1.2
+-Chapter 2

it's giving organized. it's giving navigable. we're obsessed 🫶

---

💀 BUGS 💀

okay so listen, there's a known issue and I need you to pay attention because it's messy:

due to a bug in the Perl library PDF::API2 v2.039 and earlier, some Unicode characters get handled incorrectly and cause outline string corruptions. 😭

the example that lives in the docs rent-free: everything after the CJK character U+4E0A (上) will get corrupted in the PDF output, because its UTF-16 encoding contains the byte 0x0A, which just so happens to be an ASCII newline character. so the poor thing gets read as "newline" and the rest of your string is gone. absolutely tragic 💀

good news though, bestie: for user convenience, this pdfoutline version ships with a workaround that should let it run flawlessly all the way down to PDF::API2 v2.034. if you're on anything even older than that, please upgrade PDF::API2 — no excuses, it's for your own good 🙏

---

👑 AUTHOR 👑

pdfoutline's author is Ievgenii Meshcheriakov <eugen@debian.org> 💜

pdfoutline is part of fntsample and can be downloaded from <https://github.com/eugmes/fntsample>.

---

and that's the whole page, babe ✨ this was fntsample version 5.4, dated 2024-04-01 — go forth and bookmark your PDFs responsibly, mwah 💖🎀