[texhax] document broken under windows

[Heiko Oberdiek]

On Sat, Oct 09, 2010 at 01:58:31PM +0200, Uwe Lueck wrote:

> I tried many hours (several times) to understand what \pdfstringdef is good for 
> from manual.pdf (without success). What effect has 
> 
>     \pdfstringdef{macroname}{TeXstring} 

It converts a TeX string <TeXstring> into a PDF string
that is stored in macro <macroname>.

> for given macroname and TeXstring? I resorted to
> \pdfstringdefDisableCommands successfully, but still wonder if using
> \pdfstringdef could be more efficient.

\pdfstringdefDisableCommands is part of \pdfstringdef. It allows
the redefinition of TeX macros that are valid in TeX strings,
but unusable in PDF strings. Example: "\TeX" can be part of a
TeX string, in a PDF string "TeX" can be used instead.
  \pdfstringdefDisableCommands{%
    \def\TeX{TeX}%
  }%
However this is not necessary for \TeX, \LaTeX and some other
macros, because they are already known by \pdfstringdef.

> Now I see that hyperref.pdf is much clearer on \pdfstringdef. 
> However, I still don't understand if/how I could profit from using it. 
> 
> \texorpdfstring looked very interesting, too, but I don't know what PDF
> strings are.

See PDF specification about "text string":
* "3.2.3 String Objects"
* "3.8.1 String Types"

> May be the *macros* in the example can be generated with
> \pdfstringdef!?

The example uses:

  \pdfannot width 0pt height 0pt depth 0pt {
    /Subtype /Text
    ...
  }

The stuff beginning with "/Subtype" is raw PDF dictionary code
and reading section "3. Syntax" of PDF specification is
strongly recommended. A string object given there has
syntactical requirements. They are given, if the string
is passed through pdfTeX's \pdfescapestring or package
pdfescape's \EdefEscapeString, but I doubt that you want
to read TeX code as result. \pdfstringdef with \pdfstringdefDisableCommands
and \texorpdfstring helps in the conversion process from TeX code
to something more meaningful PDF string.

Yours sincerely
  Heiko Oberdiek