I have an existing PDF (without any corresponding source file), and a text file which is a list of items referencing sections within the PDF file, along with a page number for each item. I would like to generate a new PDF which starts with a generated table of contents index, followed by the contents of the original PDF. The generated index needs to be hyperlinked so that clicking on any item will automatically jump to the page containing the referenced section.

I'm looking for a suitable set of tools (preferably CLI-oriented) to accomplish this on Linux; all the tools I've looked at so far don't seem to offer a solution. I'm an experienced programmer, and am more than happy to write code if required (preferably in Ruby/Python/Perl/shell) to parse my text file and convert it into a hyperlinked index, but I can't find the right tools to solve it. I think part of the problem is that the hyperlinks need to point to within the same file, but their targets won't exist until later when the ToC is joined with the original PDF.

I'm also familiar with various markup languages, e.g. Markdown, reStructuredText, TeX, LaTeX, org-mode, and an ideal solution would use one of these as an intermediate step for generating the hyperlinked ToC.

-
Check out this very similar question on the TeX StackExchange: Adding Table of Contents to existing PDF –  rickhg12hs Oct 26 '13 at 13:41
@rickhg12hs - why not write this up as an answer here? –  slm Oct 26 '13 at 22:00
This worked great, many many thanks!! –  Adam Spiers Oct 27 '13 at 1:16
Answer written. Hopefully @Terdon will un-mark it for deletion soon. –  rickhg12hs Oct 27 '13 at 22:56
Actually @terdon marked it for deletion. Maybe he can unmark it –  rickhg12hs Oct 28 '13 at 17:00
show 1 more comment

This is taken in whole from @Herbert answering a very similar question on the TeX StackExchange:

use package pdfpages and then:

\documentclass{article}
\usepackage{pdfpages}
\usepackage{hyperref}

\begin{document}

\tableofcontents
\clearpage\phantomsection
\addcontentsline{toc}{section}{The first section name}% or chapter
\clearpage\phantomsection
\addcontentsline{toc}{section}{The second section name}% or chapter
\clearpage\phantomsection
\addcontentsline{toc}{section}{The third section name}% or chapter