[tex-eplain] [solved] Re: Outlines side panel without pdftex?

[Fusselman, Jerry]

Thanks so much for your work and explanation! 

-----Original Message-----
From: Karl Berry [mailto:karl at freefriends.org] 
Sent: Tuesday, May 31, 2016 1:01 PM
To: rodolfo.medina at gmail.com
Cc: tex-eplain at tug.org
Subject: Re: [tex-eplain] [solved] Re: Outlines side panel without pdftex?

    perhaps be useful just to let people know and realize that such a
    capability - to have bookmarks also without pdftex - exists.

Agreed.  I'll at least add something to the manual for next time.

    TeX code like dollar symbol for mathematical formulas 

If you mean getting a literal "$" into bookmarks, it turns out that works as-is, though it's more or less luck.  Most special TeX characters would get a TeX-level error due to their catcode.  Example below.

If you mean getting an actual math equation into a bookmark, like $e=mc^2$, in general, no.  Bookmark strings are text.  Although there is an exception, sort of: since Unicode now has lots of math chars and support, and you can have any Unicode char in the bookmark (see below), you could put some math that way.

Of course, how any bookmark text appears to going to be dependent on the font used, and that is specified as a system font to the PDF viewer,
*not* in the document in any way.  Unfortunately.

    and latin accents above vocals.  

PDF bookmarks use either a more-or-less-Latin-1 8-bit encoding called "PDFDocEncoding", or Unicode (UTF-16BE to be exact).  I'll attach the PDFDocEncoding pages from the PDF reference manual to save you the trouble of downloading it.

8-bit strings are specified using (...); Unicode strings are specified using <FEFF...>.  For example, <FEFF0041> is the same as (A).
(Because "A" is U+0041.)
    
    But I suppose this has to do with
    postscript language compatibility with TeX.
    
PostScript and PDF can support any Unicode character in the bookmarks (of course).  But don't mix up the levels.  TeX needs TeX input, PS needs PS input :).

There is no magic to fix catcodes.  So if you want to get a { char, say, into a bookmark, you have to change its catcode to (typically) 12 and output that, or you will get a TeX-level error.  As in:

  {\catcode`[=1 \catcode`]=2
   \catcode`{=\other \catcode`}=\other
   \gdef\lbracecharliteral[{]%
   \gdef\rbracecharliteral[}]%
  ]
  ...
  \pdfoutline goto name {sec1} count -1 {Mysec-pdf\lbracecharliteral}%

Typically, the bookmarks are generated by reading the .toc (or
equivalent) file at the beginning of the run, changing catcodes as needed for the purpose.  This is what texinfo.tex does, for example, though unfortunately its code is rather more complicated than it needs to be (my fault).  Though less complicated than hyperref's.

    Is \pdfescapestring - that you mention - perhaps about this?  

No.  \pdfescapestring is about making general strings "safe" at the PostScript syntax level.  It has nothing to do with TeX stuff.

Usual PS syntax for strings is to use parens: (foo) with C-style backslash escapes: (here is a newline\nand more text) and parens themselves have to be escaped: (a right paren:\))

which means that an input string where all characters are literal, like,
  "\node(arg1,arg2)"
has to become the PostScript string
 (\\node\(arg1,arg2\))
 
Characters outside visible ASCII [!-~] are also converted to octal, for the benefit of some viewers that don't (didn't) like real 8-bit chars.

That (simple) transformation what \pdfescapestring does.  It's also described in the pdftex manual :).

Unicode strings <FEFF...> have no escapes and no need of them since they are entirely uppercase hex.

    and only for pdftex?

Neither xetex nor (TL16) luatex has the primitive.  Whether they have easily-accessible equivalent functionality, I don't know.

etex is pdftex (with dvi output), so it has it.

All of this is a big topic.  I don't pretend to understand it all.  In fact, your question has led to me look into it more than I ever have before.  Adobe's PDF reference manual and pdfmark manual are the best ultimate sources I've found.

Hope this helps.  If you have problems or find other places where Eplain might be able to help with this, let me know ... --best, karl.