to do: manually created links


PDF backend instructions and notes
==================================

By Vincent Tan
vtan@ugrad.cs.usyd.edu.au

Usage
-----

To create a PDF file from your Lout files, use the -Z switch.

Example:

$ lout -Z < all > outfile.pdf

[lout -PDF is now an alternative - JeffK]
If the file has previously been processed by Lout, you should first
delete all the ".ld" and ".li" files generated by the previous runs
of Lout. Doing this will avoid spurious error messages from Lout.


General notes
-------------

The PDF backend automatically supports text output and has custom
handlers for graphics via the use of special @Graphic keywords.
All such keywords begin with "__" (double underscore). Anything
else is passed verbatim into the PDF output stream.

One of the best way of learning how to use the backend is to study
the standard Lout libraries, which have been converted to generate
PDF files as best as possible. Many of the trickier conversions
have comments next to them to help you.


Compatibility
=============


Standard packages
-----------------

The PDF backend implements a subset of the Lout packages. The PDF versions
of the standard Lout packages are described below.

All packages are "safe", in the sense that using them will not produce
any snippets of PostScript in the PDF file, which would otherwise cause
rendering errors.

Packages marked "complete" or "no change" will work fully and
correctly, with a few small provisos. Packages marked "incomplete" will
have problems when viewed or printed with a PDF rendering program.
The packages that are affected the worst are the figure, diagram and
graph packages. Most or all of the uses of these packages will not
produce any PDF output. In the basic document layout package, only
a few Lout commands are not implemented; they are listed below.

	fig    [ incomplete ]
	diag   [ incomplete ]
	dl     [ incomplete ]
		unimplemented definitions:
			@Background/LoutPageSet,
			@MargSet/LoutMargSet,
			@MargPut/LoutMargShift
	doc    [ no change ]
	eq     [ complete ]
	graph  [ incomplete ]
		unimplemented definitions:
			@GraphObj,
			@GraphSolid,
			@GraphDashed,
			@GraphDotted,
			@Graph
	report [ no change ]
	slides [ no change ]
	tab    [ complete ]
	tbl    [ complete - done by JeffK (not a guarantee of quality!) ]

Currently, there is no work-around for this lack of functionality.
[ ? add a mechanism to include external graphical files (such as
JPEG compressed images) into the PDF file ? ]

Minor point: surd characters in the 'eq' package will look slightly
odd when viewed in Adobe Acrobat Reader: the top of the surd
character will be "short" of the top. This seems to be a problem
with the way Acrobat renders surds (Lout typically requests that the
surd be rendered at a slightly larger than normal size but it appears
that Acrobat renders this enlarged surd incorrectly).


User-defined
------------

If you have used custom snippets of PostScript (usually with a
@Graphic command) then you will to modify it so that it produces a
PDF file that can be rendered. At the very least, you should suppress
the PostScript from appearing in the PDF file using a modification
like this:

from the original:

{ "0 0 moveto" xsize ysize "lineto stroke" } @Graphic { obj }

to the modified version:

@BackEnd @Case {
  PostScript @Yield {
    { "0 0 moveto" xsize ysize "lineto stroke" } @Graphic { obj }
  }
  PDF @Yield {
    # PDF version produces no output [ safe but useless ]
  }
}

better yet, translate the PostScript operators into PDF operators:

@BackEnd @Case {
  PostScript @Yield {
    { "0 0 moveto" xsize ysize "lineto stroke" } @Graphic { obj }
  }
  PDF @Yield {
    { "0 0 m" __xsize __ysize "l S" } @Graphic { obj }
  }
}

More information about how to do this is given below.


Text
====

PDF support for text is automatic. Text that would usually produce
marks on a page in PostScript will instead produce marks on a page
in PDF. Lout commands that change text location, size, font, style,
colour, etc. will work fine.


Graphic
=======

If you are using custom pieces of PostScript to generate rendering
marks, you will need to modify them for PDF output. These pieces of
PostScript typically occur within @Graphic commands. At the very
least, you should modify them so that the PostScript is not placed
into the PDF file, since this will produce errors when the PDF file
is rendered. A description of this is described in the Compatibility
section.

Since PDF is not a programming language whereas PostScript is one,
it will not be possible to translate all PostScript operators into
PDF operators which produce the same functionality. If the
PostScript is straight-forward (eg, move pen to a location, draw a
few lines, stroke and fill the shape) then it will be possible to
write equivalent PDF code. If the PostScript code is more
sophisticated, then it will probably not be possible to write
equivalent PDF. Currently there is no work-around for this
limitation.

The possible PostScript to PDF changes are now listed:

	PostScript			PDF

	xsize				__xsize
	ysize				__ysize
	xmark				__xmark
	ymark				__ymark
	<val>in				__mul(<val>, __in)
	<val>cm				__mul(<val>, __cm)
	<val>pt				__mul(<val>, __pt)
	<val>em				__mul(<val>, __em)
	<val>vs				__mul(<val>, __loutv)
	<val>ft				__mul(<val>, __loutf)
	<val>sp				__mul(<val>, __louts)

	setlinewidth			w
	stroke				S
	closepath stroke		s
	closepath			h
	moveto				m
	lineto				l
	fill				f
	stroke fill			B
	gsave				q
	grestore			Q
	setgray				g [fill]   G [stroke]
	setrgbcolor			rg [fill]  RG [stroke]
	setcmykcolor			k [fill]   K [stroke]
	setdash				d
	concat				cm
	curveto				c

It is also possible to convert arcs to curves but it is not a
straight-forward procedure because you need to calculate
Bezier control points.

There are also more PDF marking operators. See the PDF v1.2
specification, available from <http://www.adobe.com>, for
more information.


For expressions, the PDF backend supports a simple prefix
notation expression evaluator. The syntax is:

	<expr>		=	<operator> | <value>
	<operator>	=	__add(<subexpr>, <subexpr>) | __sub(<subexpr>, <subexpr>) |
				__mul(<subexpr>, <subexpr>) | __div(<subexpr>, <subexpr>) |
				__sin(<subexpr>) | __cos(<subexpr) |
				__pick(<cardinal number>, <list of expr>)
	<value>		=	__in | __cm | __pt | __em | __loutv | __loutf | __louts |
				__xsize | __ysize | __xmark | __ymark
	<subexpr>	=	<expr> | +<subexpr> | -<subexpr> | <constant>
	<constant>	=	0-9.[0-9]*

Note that expressions must start with an <operator> or a <value>. It cannot
start with a <subexpr> (or a <constant>) although negation is simple to do:
use __sub(0, <expr>).

Of the operators, add, sub, mul, div, sin and cos do as you would expect. The
pick operator picks the nth expression from the list of expressions where n
is the first parameter of the __pick() command: eg, __pick(2, 4, 5, 6) produces
5. The list in the __pick() command can also be whitespace delimited: eg,
__pick(2, 7 8 9) produces 8.

Example:

	"xmark ymark moveto xmark xsize add ymark ysize 2 mul add lineto stroke"

becomes:

	"__xmark __ymark m __add(__xmark, __xsize) __add(__ymark, __mul(2, __ysize)) l S"

For more examples, please look in the Lout library files (in the include
directory).


EPS files
=========

EPS files will not be included into PDF files. Currently, there is
no work-around for this lack of functionality.


Hyperlinks
==========

The PDF backend supports the creation of hyperlinks. Some hyperlinking is
automatic and it is possible to specify your own hyperlinks should you so
desire.

Hyperlinks can be specified to be either accessible from an external file
(either another PDF file or by external sources such as a hyperlink in an
HTML document) or which can only be accessed from within the same file.


Automatic links
---------------

Links are automatically generated for the following document layout items:

@Chapter and any other item that uses the @LargeScaleStructure item
@Index
@IndexA
@IndexB

The name of the link is the @Title parameter passed to these items.

Items in @Index entries are kept internal to the document (they cannot
be linked to from external documents) but items that use
@LargeScaleStructure can be externally linked.

Index entries are coloured blue. Clicking on the page number in Adobe
Acrobat Reader will take you to the page. Items that use the
@LargeScaleStructure item will have no visible indication that they
have been linked to but moving the mouse over them changes the cursor
to a pointing finger. For example, mousing over the Table of Contents
of a document will change the cursor. Clicking on an entry in the Table
takes you to the page that that entry lies on.


User-defined links
------------------

To create a link, you need to specify a starting (or source) location and
a destination (or target) location. Source locations often appear visually
distinctive - for example, hyperlinks appear as blue underlined text,
like what is seen in web browsers. Clicking on such links often produces
some kind of highlighting. Releasing the mouse button then transports
you to the destination location. For each source location, you can specify
a change in the document's zooming for the target location. Finally,
target locations can be "exported" so that you can link to them from
external documents.

Here are the possible link keywords available for the PDF backend:

(1) specifying a source location/link which targets a location internal
to the PDF document:

	syntax:  "__link_source=<<name_of_target_link [dest_link_option]>>"

	example: "__link_source=<<chapter6>>"
	example: "__link_source=<<part7 __FitH>>"

The possible destination link options are:

__FitNoChange	no change to the zoom state of the window
__Fit		change zoom to fit the page to the window
__FitH		change zoom to fit the width of the page to the window
__FitV		change zoom to fit the height of the page to the window
__FitR		change zoom to fit the rectangle of the target to the window
__FitB		change zoom to fit the page's bounding box to the window
__FitBH		change zoom to fit the width of the page's bounding box to the window
__FitBV		change zoom to fit the height of the page's bounding box to the window

The default option is __FitNoChange.


(2) specifying a source location/link which targets a location external
to the PDF document:

for external files:
	syntax:  "__link_external=<<name_of_target_link __link_to=file_spec>>"

	example: "__link_external=<<chapter6 __link_to=/usr/bin/file.pdf>>"

for URLs:
	syntax:  "__link_external=<<name_of_target_link __link_to=<< /FS /URL /F (url)>>>>"

	example: "__link_external=<<chapter6 __link_to=<< /FS /URL /F (ftp://ftp.cs.su.oz.au/jeff/lout/user.pdf) >>>>"

	**	note the special format required for URL links **
	**	note the need to have balanced "<<" and ">>" pairs! **


(3) specifying a source location/link which targets a URI:

	syntax:  "__link_URI=<<URL>>"

	example: "__link_URI=<<http://www.adobe.com>>"


(4) specifying a target location which cannot be linked to from external
documents:

	syntax:  "__link_target=<<name_of_target_link>>" where
			name_of_target_link is in the PDF file

	example: "__link_target=<<chap6.subsection2.paragraph3>>"


(5) specifying a target location which can be linked to from external
documents:

	syntax: "__link_target_for_export=<<name_of_target_link>>"
			where name_of_target_link is in the PDF file

	example: "__link_target_for_export=<<chapter5>>"


PDF Document Information
========================

PDF files can have some pieces of information such as author, keywords
included in them, to facilitate searching. The PDF backend supports
the ability to set these pieces of information, using special keywords:

__author=<author>

example: "__author=John Smith" @Graphic ""


__title=<document title>

example: "__title=PDF backend for Lout" @Graphic ""


__subject=<subject>

example: "__subject=Lout PDF support" @Graphic ""


__keywords=<list of keywords>

example: "__keywords=Lout PDF PostScript" @Graphic ""


Troubleshooting
===============

(1) strange error messages, esp. the PDF backend complaining about
    unresolved links. Did you delete the ".ld" and ".li" files from
    previous runs of Lout for PostScript output? Lout needs to
    create PDF-specific versions of these cross references. Do not
    mix the PostScript and PDF versions of these files!

(2) "left parameter of @Graphic is bad" - usually from @Title statements
    which include definitions. For example: "@Title { Using @Tex styles }"
    where @Tex is defined as: "def @Tex { @Onecol {TEX} }". When the PDF
    backend tries to create a target entry for a hyperlink, this error
    message will be generated. The PDF output will still work but the
    actual title of the link will be "Usingstyles".

(3) figures, diagrams and graphs don't appear in the PDF file. This is
    currently unimplemented.

(4) EPS files are ignored. EPS files cannot be included in PDF files.

(5) when viewing or printing the PDF file, the renderer complains that
    it is unable to properly render the page or that there were
    rendering errors. Solution: check that you are not accidentally
    including snippets of PostScript into the PDF file. See the
    Compatilibity section above.

(6) surd (square root) symbols look strange. This appears to be a
    rendering problem in Adobe Acrobat Reader.