PDFtk Bookmarks Editor

Latest Version: 1.1.0
Date: 17 Jan 2020
Platform: Windows 32-bit application
Website: pdftk-bookmarks-editor.sourceforge.io
Developer: David King (dking02)
Compiler: Delphi 10.2 (Tokyo)
License: GNU General Public License (GPL), version 3
Dependencies: PDFtk Server v2.02; installed PDF viewer

Description

PDFtk Bookmarks Editor is a free, graphical user interface (GUI) for the Windows version of the PDF ToolKit (PDFtk) command line tool, PDFtk Server, specifically designed to simplify the creation and updating of PDF bookmarks (aka PDF outlines). The program uses PDFtk Server to extract existing bookmark data from the source PDF and to update the bookmarks in the output PDF. It also invokes the user's external text editor and PDF reader to display and edit the bookmark data and to view the source and output PDFs from the program's GUI.

This project is a companion application to my general-purpose GUI for PDFtk Server, PDFTK Builder Enhanced.

Operation

The process for creating or updating bookmarks with the PDFtk Bookmarks Editor involves the user editing a simple text file in which each bookmark is specified with one line of text containing the page number, bookmark level, and bookmark title separated by tabs. The corresponding bookmark data file will have the same name as the source PDF file, but with the extension changed from ".pdf" to '_bookmarks.txt" and will normally be saved in the same folder as the source PDF.

When the user selects a source PDF file, the program will automatically open a bookmark data file in the user's chosen text editor. The program will populate the file with data for any existing bookmarks in the source PDF unless a corresponding bookmark data file already exists in the source PDF folder, in which case the program will open that file instead. After editing and saving the bookmark data file, the user can have the program generate an output PDF with updated (replaced) bookmarks. Options are also available to view the source and output PDF documents and to re-open the bookmark data file for additional text editing.

Details

The program uses three text files in its process of updating the bookmarks in a PDF document. While any of the three text files can be edited, it is strongly recommended that bookmark data only be edited in file 1 which uses a concise, 1-line, tab-delimited data format.

File 1: Bookmark data in 1-line format (tab-delimited page number, level, and title). (File ext: _bookmarks.txt; e.g., for source PDF file myfile.pdf, file 1 is named myfile_bookmarks.txt and saved in the same folder.)
File 2: Bookmark data in PDFtk 4-line format. Normally not user-edited. (File ext: _bookmarks_data.txt)
File 3: Metadata, 4-line bookmark data, and page media data in format compatible with PDFtk dump_data & update_info commands. (File ext: _data.txt) Note: PDF metadata can also be updated by editing file 3 before generating the output PDF.

Example of PDFtk 4-line bookmark data (format used in files 2 & 3)
BookmarkBegin
BookmarkTitle: Related documentation
BookmarkLevel: 2
BookmarkPageNumber: 4

Same Data in 1-line format (format used in file 1; tab-delimited page number, level, title)
4        2        Related documentation

The PDFtk Bookmarks Editor's GUI can be configured in the program's .ini file to run in either "Full" or "Simple" mode. Screenshots of the two modes are provided on the project's Summary page. "Simple" mode is recommended for most users since it updates files 2 and 3 automatically, hiding the optional manual controls for those files in the GUI (see Method A). "Full" mode allows user access to all data files and controls. It supports both automated (Method A) and manual (Method B) operation but manual operation requires some understanding of the details of how bookmarks and optionally metadata are updated using PDFtk Server commands (described below).

Method A (Automated): Bookmarks can be updated automatically in either "Full" or "Simple" mode as follows:

(A1) Select the source PDF document by dragging and dropping the file onto the Editor's form from Windows Explorer (or by clicking the Source PDF Document button and responding to the open file dialog).
(A2) Open text file 1 by clicking the Open-1 or Edit Bookmark Data button, edit the bookmark data, and save the file.
(A3) To automatically update text files 2 & 3 and generate the output PDF with updated bookmarks, hold the Shift key down and click the Update Info or Update PDF button. Alternatively, click the PDFtk logo at the center of the form.

The program operates as follows: After the user has selected the source PDF document, the program will automatically issue a PDFtk dump_data command to extract metadata, bookmark data, and page media data from the PDF file to text file 3. It will then extract the 4-line bookmark data from file 3 and copy it to file 2 and convert it to 1-line format in file 1. Note that if a file with the required name of file 1 already exists in the same folder as the source PDF, the Bookmarks Editor will use that file rather than initializing file 1 with bookmark data from the source PDF.

After the program has prepared the starting versions of text files 1-3, the bookmark data in the files will be updated in the reverse order, starting with file 1. After the user edits and saves file 1, the updated data must be converted to 4-line format in file 2 and then copied from file 2 to file 3 to replace the original bookmark data in that file. The updated file 3 can then be used to update the PDF via a PDFtk update_info command. When the Update Info button is clicked, the Editor will strip the existing bookmarks from the PDF file (to minimize the size of the output PDF) and then issue the update_info command to update the stripped PDF with the data in file 3.

Method B (Manual): The process can be manually controlled by the user in "Full" mode as follows:

(B1) Select the source PDF document --- see step (A1) above.
(B2) Update the 1-line bookmark data in file 1 --- see step (A2) above.
(B3) Click Convert button to convert 1-line bookmark data in file 1 to 4-line format in file 2. (Optional: Check resulting file 2 by clicking Open-2 button.)
(B4) Click 2 > 3 button to copy bookmark data from file 2 to file 3. (Optional: Can also edit metadata in file 3 at this point by clicking 'Open-3' button.)
(B5) Click Update Info button to update the PDF with the data from file 3. Click View Output button to display output PDF.

Note that if the user does not plan to inspect or edit files 2 and 3, the manual button clicks in steps B3-B5 above can be bypassed by substituting step A3. The program will then issue virtual button clicks to automatically complete the process.

In "Full" mode, the Editor also supports updating of PDF metadata. After propagating the updated bookmark data to file 3, open file 3, edit the metadata and save/close the file before clicking the "Update Info" button.

The program supports physical page offsets (so-called "level 0" bookmarks) in file 1. This allows logical page numbers to be used in file 1 instead of physical page numbers for documents which restart page numbering at page 1 for each section/chapter. In such cases, file 1 should be saved along with the output PDF file when resetting or exiting the program since a data file which includes page offsets cannot be regenerated automatically from the output PDF. See the User Guide for further information and examples.

When using the Editor, it is recommended that the user accept the default file names for saving text files and the output PDF. The defaults will overwrite any existing files.

When done working with a source PDF, click the program's Reset button or Exit button rather than simply closing the program's window. This will allow the program to clean up the three text data files and source PDF .bak file generated during the process. The program will automatically delete files 2 and 3 (since they can always be regenerated from the output PDF) but will prompt for confirmation to delete file 1 and the source PDF .bak file.

Getting Started

This project is distributed as a portable 32-bit application for Windows and is licensed under terms of the GNU GPL, version 3.

Two downloads are available:

Executables and User Documentation (includes PDFtk Server v2.02)
PDFtkBookmarks-1.1.0-portable.zip

Source code (Delphi 10.2)
PDFtkBookmarks-1.1.0-source.zip

Download file PDFtkBookmarks-1.1.0-portable.zip and extract it to a folder of your choice. Launch PDFtk Bookmarks Editor by double-clicking file PDFtkBookmarks.exe. As delivered, the program will run in "Simple" mode and use the applications associated with .pdf and .txt file types in Windows (e.g., Adobe Reader and Notepad) for opening .pdf and .txt files. Different .pdf and .txt applications and the GUI mode can be specified via settings in the configuration (.ini) file which is accessible from the program's "File" menu.

Documentation

The distribution includes a copy of the PDFtk Bookmarks Editor User Guide (.pdf). It is accessible from the Help menu of the program. Please consult the guide for an explanation of button functions and examples of updating various PDFs.

Acknowledgements

• Steward & Lee, LLC (for GPL PDFtk Server v2.02 executable included in the distribution)
• Embarcadero Inc. (for free license of Delphi 10.2 Tokyo Starter Edition used for this FOSS project)

---

Version History

1.1.0, 17 Jan 2020

• Added "Simple" mode that hides controls for files 2 and 3 and supports automated updating only. Mode is a setting in the .ini file (0="Full", 1="Simple). The download file has the Mode setting initialized to "Simple" (Mode=1).

1.0.1, 08 Sep 2019

• Added Shift-Update Info to automate button clicks required to complete the update process.
• Modified View Source to use .bak file instead of the actual source PDF file. Allows simultaneous displays of before and after versions of the PDF file when the source PDF file has been overwritten by the output PDF (default behavior).
• Added ability to pass the source PDF file name to Bookmarks Editor as a command line argument.
• Updated tab order of buttons.
• Added (4 Nov 2019): File libiconv2.dll added to download file PDFtkBookmarks-1.0.1-portable.zip. This GNU Win32 dll is used by pdftk.exe to convert between character encodings in international environments. No changes made to PDFtk Bookmarks Editor 1.0.1 code.

1.0.0, 21 Aug 2019

• Initial public release.