Add option text

[sim642]

This is a cleaner solution to overriding the PDF bookmark text for a sectioning command separately from its heading and its ToC entry. For example, https://tex.stackexchange.com/q/646491/383946.

Instead of something like

\section{\texorpdfstring{Section Name}{1.1.1.1.1}}

this allows

\bookmarksetupnext{text={1.1.1.1.1}}
\section{Section Name}

[davidcarlisle]

sorry I think the suggested syntax with a ..."next" is not an improvement. Using the embedded texorpdfstring seems more natural, and going forward the commands should have a keyval interface that will allow more separation such as

\section[bookmark=thing, toc=something else, page-head=that]{main text}

[sim642]

Sure, most people would just do it with \texorpdfstring and they can continue to do so.
But \bookmarksetupnext exists for a reason and if I already have to use it anyway to configure the PDF bookmark style (e.g. bold) of a sectioning entry, then it's more convenient and consistent to also choose the text for it with the same \bookmarksetupnext call, in order to have everything concerning the PDF bookmark together, rather than split between \bookmarksetupnext and \texorpdfstring in the middle of other stuff.

There's also a semantics issue with using \texorpdfstring for this purpose. Its purpose is to choose content based on where it's being expanded (in TeX or in PDF). It just happens that the PDF case is used in PDF bookmarks and TeX case is used otherwise. But that's in no way guaranteed. One might also want to access the PDF bookmark text within TeX.

And this isn't a hypothetical, it's a feature already supported by the bookmark package: \bookmarkget{text} is documented as "It returns the text of the outline entry." But if you actually want to use it in TeX and have defined the section heading via \texorpdfstring, then it will not expand to the text actually used in the PDF outline entry. It might seem like a bug to some but it's actually what \texorpdfstring is supposed to do.

Overriding the PDF bookmark text via the already-existing \bookmark@text command has the right semantics of only being about the PDF bookmark text without relying on the expansion context like this. And \bookmarkget{text} will give the right thing because that's probably why \bookmark@text exists at all in the first place.

[u-fischer]

I'm not really against the idea. Actually it could perhaps simplify the implementation of the new bookmark key.

The main problem I see is that the key would work only in \bookmarksetupnext and not also (like the other keys) in \bookmarksetup. That looks a bit a awkward and would need a clearer documentation.

It also doesn't play nicely with the numbered option as it removes also the \numberline so it must be also documented how to get around that.

it's a feature already supported by the bookmark package: \bookmarkget{text} is documented as "It returns the text of the outline entry."

I have seen uses of \bookmarkget{level} inside of addtohook to make some levels bold, but I don't quite see why you would want to retrieve the text there (as there is a group you wouldn't get it outside of the bookmark).