[tex-eplain] eplain manual source (was: Problems hyperlinking two pdf files)

[Oleg Katsitadze]

On Tue, Feb 17, 2009 at 12:52:43PM +0000, Rodolfo Medina wrote:
> With dvips(k) 5.96.1 the problems with eplain hyperlinks seem to be solved.  I
> also managed to achieve cross-file references putting together explicit
> hyperlinks with \definexref and \refn.

Glad to hear you've succeeded.

> Now, the fine tuning: the hyperlink target is reached quite exactly but not
> `exactly'.  When choosing the `Continuosu view' in xpdf, they are very bad.

I'm afraid that better precision is not possible with hypertex, it
just doesn't provide enough knobs to tweak (and that is by design).  I
believe it's possible in principle in the PS -> PDF conversion using
the so-called PDF marks, but Eplain doesn't provide a driver for PDF
marks.

> Instead, in the eplain.pdf file that comes with eplain package I see a
> beautiful side pan, and besides the links are performed absolutely exactly, in
> both page-by-page and continuous view.
> 
> How can I obtain that?

For that you'd have to use pdftex or dvipdfmx, but then you lose the
ability to use PS code.  There is a package for LaTeX which allows to
use PS in pdftex, but I have no idea whether it supports plain TeX.

> I couldn't find the source file of eplain.pdf

It's in the source distribution:

  http://tug.org/eplain/eplain-3.2.tar.gz

It's written in Texinfo, the sources are all the .texi files in doc/.

> explanation of how to get that kind of side pan and that kind of perfection.

Eplain doesn't provide any facilities for PDF bookmarks.  Texinfo does
them automatically, but while excellent for typesetting manuals and
simple books, Texinfo is practically useless when fine-grained control
is required.  Of course, you can look at how Texinfo implements
bookmarks and do something similar:

    http://ftp.gnu.org/gnu/texinfo

PDF reference will also be useful:

    http://www.adobe.com/devnet/pdf/pdf_reference_archive.html

But again, I'm pretty sure hypertex doesn't support bookmarks, you'd
have to use pdftex/dvipdfmx.

I wrote some macros and an external (Python) command-line tool to
encode and collate the bookmarks.  It's messy so I'd rather not
recommend it, unless you are completely stumped:

    http://geolsoft.freeshell.org/elsgolts.diff.ur.var.is/elsgolts_diff_ur_var_is.tar.gz

You probably can easily do without any external scripts unless you
need non-ASCII characters -- I needed bookmarks in Cyrillic so I used
Python to convert strings from document encoding (KOI8-R) into UTF-16.
But ASCII strings can be written as-is.

See PDF Reference 1.4, Section 3.2.3 "String Objects", Section 3.8.1
"Text Strings" and Section 8.2.2 "Document Outline".

HTH,
Oleg