22

Is it possible to create a new bookmark to a section heading that is not listed in the Table of Contents (i.e., using the starred form — \section*{A title})?

\pdfbookmark (part of hyperref.sty) or \bookmark (part of bookmark.sty) only appear to create a bookmark to the location to where the command is issued. However, placing this either before, within, or after the \section*{} command does not create the correct effect: clicking on the bookmark in a PDF viewer links to the the wrong place. Specifically, it doesn't link to the TEXT portion of the section heading, like a normal hyperref-ed section heading/bookmark but instead to the space above the heading (which can be the previous page if the section is on a new page), or immediately BELOW the section heading (thus hiding the heading!).

Using \phantomsection and then \protect\label{} issued within the \section*{} command works with the \hyperref{}{} command in linking to the section heading, bringing the user straight to the heading title. Great! It's just this same basic principle in PDF bookmarks that I couldn't figure out. If only I could issue a \pdfbookmark-like command that goes directly to this same \label, that would be just perfect!

Edit: I also need to be able to specify the bookmark name (i.e., the text that's displayed in the bookmarks section in a PDF viewer), rather than use the name of the section itself (which can be very long in my work).

Any help would be appreciated. I've literally spent days experimenting and nothing seems to be possible at the moment, but I'm sure there is a way! Thank you for your time.

stahmo
  • 265

1 Answers1

15

That really is some annoying behavior! I started writing "Oh, just put \pdfbookmark into the title" until I read the rest of your question. I dug into hyperref.sty and, eventually, hyperref.pdf (the version with the documented source) and found out that the whole thing is driven by \Hy@writebookmark in some way. Note: I don't know what \Hy@writebookmark actually does, except that it apparently writes a bookmark. Here is the solution I found (in the preamble of the following example code):

\documentclass{article}
\usepackage{hyperref}

\makeatletter
\def\munch#1{}
\newcommand{\bkmk}[4][0]{%
 #2#3{\phantomsection%
  \Hy@writebookmark%
   {}%
   {#4}%
   {\@currentHref}%
   {#1}%
   {toc}%
  #4}%
 }
\makeatother

\begin{document}

\section{Real section}

Stuff and things.

\bkmk[2]\subsection*{Bookmarked as a subsection}

More text.

\end{document}

Compile twice to make sure the bookmarks are in the PDF, and see that the link goes to the right place. What's going on here is that your links are one line off for the same reason as in this question of mine, because \pdfbookmark (erroneously?) doesn't use \Hy@raisedlink to place its target above the baseline. Conveniently, \phantomsection does use this facility, and names the link \@currentHref, so we just send the bookmark there. If you save (via \edef) this macro immediately, you can also produce links to the starred section from within the document.

The starting point for this solution was the following much simpler macro that I use to get starred sections into the TOC, which also has the effect (with hyperref) of putting them in the bookmarks with the right link location:

\def\munch#1{}
\newcommand{\toc}[3]{
 #1#2{\phantomsection\addcontentsline{toc}{\expandafter\munch\string#1}{#3}#3}
}

Same usage as above (without the optional argument). Since it works, it led me to investigate \addcontentsline, and so on.

Community
  • 1
Ryan Reich
  • 37,958
  • Thanks for your time, Ryan! I've tested your code, it works really well. Unfortunately, when I put this back into my very complex document it fails. I have within my \section{} command: '' \settowidth{\hangindent}{Special Section~~~} '' -- I want my heading indented in this way, so I have to use \settowidth within \subsection{}. Furthermore, I realised that I didn't mention one thing in my question (will update it now): I need to specify the bookmark's name, not just use the (sub)section name. (Namely, my section name expands with some TeX code: see http://tinyurl.com/22m9oem .) – stahmo Jan 08 '11 at 06:15
  • 1
    @stahmo: I tried putting that command in my example but it just gave some warnings about invalid commands in a PDF string. Could you put all the non-printable material inside a \texorpdfstring{<tex-only stuff>}{<pdf-only stuff>} and see if that helps? – Ryan Reich Jan 08 '11 at 07:21
  • 1
    @stahmo: Oops, I didn't notice your second requirement. To specify the bookmark name, just use \texorpdfstring and put the PDF name in the second argument, the TeX name in the first argument (including whatever formatting commands you need). – Ryan Reich Jan 08 '11 at 07:59
  • 1
    Wow, you did it, killing two flies with one pebble! Both the problem with '\settowidth' and the custom bookmark †ext was fixed/accomplished with '\texorpdfstring'. Specifically, I placed the '\settowidth' command within the first argument of '\texorpdfstring', which is where I wanted it anyway (who needs '\hangindent' within the bookmark text, hehe). Thanks a million! :) -stahmo – stahmo Jan 09 '11 at 11:15
  • Thanks! Is there an online reference that describes the second optional argument to \newcommand? – andrew Jul 23 '12 at 17:37
  • 1
    @andrew google "latex newcommand". The second optional arg makes the first arg of the new command optional and provides its default value. – Ryan Reich Jul 23 '12 at 17:45