Tuesday, June 10, 2008

Command-line PDF bookmarks editor

Hi all, i wrote a command line utility program called jpdfbookmarks to add bookmarks to an existing pdf file.
I could not find anything easy and free on the net for this simple task, so i decided to write my own and now i'm going to publish it here, for those who need the same functionality.

This is a java program and i have packaged it to an installer for linux users, but should work with any operating system as long as you have installed a java runtime environment version 5 or later. If you don't have it or you are unsure you have it go to sun java site and check.

It' is very simple and not features rich but is really straightforward to understand its usage. First you have to create a simple text file which will represent the structure of your bookmarks using your favorite plain text editor, each line of text is a bookmark item written in the form:

Chapter 1. The Beginning/3
Para 1.1 Child of first level/5
Para 1.1.2 Child of second level/9
Para 1.2 Another Child of first level/14
Chapter 2. The Continue/27

where the part on the left of the / is the title of the bookmark and the part on the right is the target page of the bookmark. Text indentation represents the hierarchy of the outlines and must be obtained with "tab characters" (spaces will not work). Each bookmark will point to the top of the page indicated in its line, there is no way to point to another position in the page at present time. Once you have the file, save it to the same folder where you have the pdf file it refers to with a name like bookmarks.txt, then assuming that the original pdf name is input.pdf and that we want to save modified pdf as output.pdf, launch the command:
jpdfbookmarks --apply input.pdf bookmarks.txt output.pdf

If output.pdf already exists or if you indicate input.pdf as ouput file, the program will print a warning and ask for confirmation before overwriting, i suggest that you never overwrite existing files to avoid loss of data as this program is not tested enough, so please be carefull and write always to a new file, i will not fill responsible for any data corruption you eventually will experience.
If your original pdf file already have bookmarks they will be erased and substituted by the new ones, if you want to preserve or use them as the base of your bookmarks.txt file you can use the command:

jpdfbookmarks --dump input.pdf > bookmarks.txt

After this command you can open bookmarks.txt with your editor to modify it before applying it again to the pdf.

If you need a quick help during your work use the command:

jpdfbookmarks --help

The esiest way to install the program on Linux should be to download the Linux installer from the link below and afer giving it execution permissions double click it in your desktop environment, the installer will prompt you for the root password and guide you through the installation, it works fine on my ubuntu laptop but if you have problems on your machines post here and hope for some help.
An alternative if you have problems on linux with the installer or if you want to use the program on other operating systems, is to download the zip archive, again from the link below, and extract it where you prefer. In this case to use the program you have to open a terminal inside the directory where you have extracted, copy there the files you are working on and launch the commands like the following example:

On Linux:

./jpdfbookmarks --apply input.pdf bookmarks.txt output.pdf

./jpdfbookmarks --dump input.pdf > bookmarks.txt

On all systems:

java -jar jpdfbookmarks.jar --apply input.pdf bookmarks.txt output.pdf
java -jar jpdfbookmarks.jar --dump input.pdf > bookmarks.txt
or if your desktop recognizes jar files as executables you may try:

jpdfbookmarks.jar --apply input.pdf bookmarks.txt output.pdf
jpdfbookmarks.jar --dump input.pdf > bookmarks.txt

The program is freeware and the license for it and for the libraries it uses are distributed and installed with it. If you find this program useful, want to suggest something or signal a bug please post here, i will appreciate your contribution.


Unknown said...

Congrats. It's an awesome work. It really helps me a lot.

flavianopetrocchi said...

Thank you, i'm working on a version with a graphical interface of this utility, stay tuned!

Anonymous said...

I've also downloaded it, and I don't mind not having GUI--after all, I use openbox! But I'll stay tuned :)

Anonymous said...

However, are you considering writing manpages for your bookmarking script? It'd help me out so much, though I'm also considering printing the first page of your blog to pdf and using that instead (or, for now) :)

flavianopetrocchi said...

Hi, thanks for your comments. I'm not planning to add manpages for now (code is my priority), but if you launch the command jpdfbookmarks --help the program already prints some help. The GUI version i am writing will continue to have the command-line functionality, i am happy you appreciate that approach.

m.ardito said...

hi, this could help me really a lot... it is exactly what i was looking for...

i got a java heap error, though, is there a maximum size? any hints?

Anonymous said...

Interesting to know.

flavianopetrocchi said...

Hi m.ardito, can you please report the size in MB of the PDF you are bookmarking and the number of pages it has. Also knowing the OS and the physical memory of your machine could help me.

m.ardito said...

well, forget it. it happened just with one file. all the others are fine...
i'm generating pdfs with HTMLdoc and something could have been wrong with that particular file.

i'm trying to mantain a pdf version of the wiki docs of a popular open source 3d package, blender.org.

for my particular job, it would be useful a feature to "shift" all bookmark pages from one point.
i try to explain.

maybe I have 1400 pages and 40 sections, each with its bookmark :)
then the 12th section grows by 20 pages.
what i have to do is edit all the remaining 28 section bookmarks to reflect their "20 pages" difference, now. i have to do it one by one. i actually do this pasting the bookmark.txt (tabbed) in a spreadsheet and playing with its formulas...

maybe gives you hints...


flavianopetrocchi said...

Thank you, I think the option to select multiple bookmarks in the gui program and shift all by a scpecific number of pages is another very good hint. Ciao.

m.ardito said...

another small tip: using "/" as a separator for the target page could be a bad choice, since it's often used in text: there are better separators...
In fact, the UI allows to insert a "/" in the bookmark text like:
eg targeted at page 2

dumping that file you get a text file containing the line

but you can't apply again such a line from the CLI, you get:
"Error: line 1 is not well formed. Will be skipped."

you could use a double "//" or a "@@" or "=>" which should far less useful in bookmark text :)


flavianopetrocchi said...

This could be a bug, in fact the program should parse the line from the end, find the page number after the first slash it encounters and ignoring the others. So "Pro/Cons/2" should be a valid line. Thanks for your report I will investigate it. Ciao.

flavianopetrocchi said...

I confirm the bug. I have already corrected it, in the next release Pro/Cons/2 will be accepted without problems. Thank you very much, I appreciate your reports.

Anonymous said...

Thanks, works fine, is very helfull!

The only thing about it that it writes a non linearized PDF file, even if the file was linearized, before. Would be great, if this got fixed!