Help:Creating an outline for PDF and DjVu

This page will explain how to create, modify or transfer an outline (table of contents, also called bookmarks) for PDF and DjVu books, which is obviously very useful. Navigating in a digital book isn't as easy as flipping pages of a paper book. Without an outline, it's hard to find something in a scanned book and requires a lot of scrolling around, especially if there's no searchable text, which is often the case. The outline allows to

• always have at hand a list of chapters and headings of a book
• quickly navigate to chapter beginnings or other important places in a book.

Outlining in graphical user interface programs is not technically hard, but requires time and patience.

Outlines in PDF

Visual editing

• The free versions of PDF-XChange Viewer or PDF-XChange Editor can be used to directly work with outlines in PDF files and save them. (The developers of PDF-XChange Editor offer free license to those who would help translate it into other languages: https://www.tracker-software.com/languages/pdf-xchange-editor)
• Pdf & DjVu Bookmarker allows to visually edit the outlines in both PDF and DjVu formats. Windows Only. Open source. Unfortunately this software is buggy and in some cases fails to do its job properly. It is desirable that someone corrects the errors in this program.
• STDU Viewer can maintain an outline in PDF books, but not embed it. Proprietary, Windows only.
• HandyOutliner can be used to embed the STDUViewer outline into PDF files. Windows only, open source.
• The well-known Adobe Acrobat can be used to edit and save PDF outlines, but unfortunately, as of today, the free version of Adobe Reader can only view outlines.
• PDFtk Bookmarks Editor, which is a graphical interface for Pdftk allows user-friendly editing of PDF bookmarks.
• jpdfbookmarks by Flaviano Petrocchi is an open source tool for adding an outline to a PDF document in Linux. This program is written in Java.

Textual editing

• The cpdf, Pdftk and other command line tools allow to read and write PDF outlines in a special text form, on which you can do find-and-replace or even use regular expressions (in a text editor that supports them, like Edit Pad Lite, which is free for personal use.)
• The following cpdf command line options are used to work with outlines:
  • -add-bookmarks (from a file)
  • -list-bookmarks (can be redirected to a file)
  • -remove-bookmarks

Outlines in DjVu

Visual editing

• PDF & DjVu Bookmarker allows to visually edit the outlines in DjVu. Windows only. Open source. But as already said above, this program contains bugs and sometimes fails to work properly.
• WinDjView (Windows only) can show an outline in a DjVu file. It can be exported as text.
• STDU Viewer can maintain an outline in DjVu books and export it. HandyOutliner can be used to embed the STDUViewer outline into djvu files. Windows only. Open source.
• Djvusmooth by Jakub Wilk is an open source tool for adding, displaying and editing outline in DjVu files. Based on Python 2. Linux.
• To visually edit an already present outline in a DjVu, extract it first with HandyOutliner, then import it into STDU Viewer. Windows only.
• In Windows, there is a software called Document Express Editor that can both visually edit djvu outlines and save them into the files.

Textual editing

• DjVuOutline allows some very basic textual editing of DjVu outlines.
• DjVuLibre has command line tool djvused that can embed outlines into DjVu files. It requires a text file of a certain format for input, described in the documentation. You can get the idea of the format by printing the existing outline of some book:
  • djvused -e print-outline book.djvu > bookmarks.txt.

To incorporate bookmarks from a text file to a DjVu file, use the following code template:

• • djvused -e 'set-outline bookmarks.txt' -s book.djvu.
• HandyOutliner can be used to write outlines to DjVu files. Windows only.

(Windows only) Writing WinDjView outlines into the book files

• WinDjView is convenient for viewing DjVu files and making outlines for them, but it can't write them into the files.
• To write a WinDjView outline directly into a DjVu file, it is necessary to export it and convert it to a form that is readable by HandyOutliner (which accepts STDU Viewer outline file format) or PDF & DjVu Bookmarker or DjVuLibre djvused utility.* The WinDjView format is not very different from STDU Viewer table of contents (TOC) format. It can be converted manually using some replaces in a text editor that supports regular expressions, like Edit Pad Lite.
• It would be good if someone created a program that could write WinDjView outlines to DjVu files or at least convert them to STDU Viewer format for passing to HandyOutliner or PDF & DjVu Bookmarker.

Searchable index for WinDjView (Windows only)

• WinDjView supports a certain kind of searchable index, especially useful for dictionaries. Example of a Greek dictionary with it: File:Вейсман_А._Д._Греческо-русский_словарь_(1899).djvu This index is stored in a quite intuitive XML format as an annotation for the first page, which can be read and written with DjVuLibre djvused tool:
  • djvused -e output-ant book.djvu
  • djvused -e set-ant annotation-file.txt book.djvu

Transferring outlines

• HandyOutliner and PDF & DjVu Bookmarker can transfer outlines between different PDF and DjVu books.
• The free version of PDF-XChange Editor can copy/paste and export/import outlines between different PDF files.
• STDU Converter allows not only to convert DjVu and some other formats to PDF, but also to transfer and edit outlines of the output document.

Joining outlines

• It may happen that you have a book with a partially completed outline, and there is another copy of this book that has in it another part of the outline done. In this case, joining the outlines may be needed.
• PDF-XChange Editor can be used to join the outlines in PDF files by copying (or exporting) them from one file and pasting (or importing) them into another.
• Outlines can be joined by extracting them with HandyOutliner and manually joining the outline files in a text editor, then writing them back with that program. This works for both PDF and DjVu formats.

Changing the zoom level

PDF format allows to specify the zoom level for each bookmark, like 'Fit width', 'Fit page' or 'Inherit'. It is used by viewers to open the required page with a certain zoom. It should be noted that some programs reset this to some default value. As of today, there don't seem to be free programs that could set a given zoom level for all bookmarks at once.

On smartphones or tablets

If you can't spend enough time on a computer making outlines, it is possible to do it on a smartphone or a tablet.

Keeping the outlines when overwriting files on Commons

When overwriting (uploading new versions of) PDF and DjVu files on Wikimedia Commons, we should keep in mind that the old version may have outlines in it. So we need to be sure that the new version has the same or better outlines than the old one, so that the outlines won't be lost.

Requesting outlines to be made by volunteers

If you have ideas for books that need to have outlines, but for some reason you can't do them yourself, you can leave a request at the page Category:Commons requests. (Not to be confused with the similar page, Commons:Requests, which is for images only.)