Lout 3.17.

git-svn-id: http://svn.savannah.nongnu.org/svn/lout/trunk@2 9365b830-b601-4143-9ba8-b4a8e2c3339c

1 files changed, 420 insertions, 0 deletions

diff --git a/READMEPDF b/READMEPDF
new file mode 100644
index 0000000..df03071
--- /dev/null
+++ b/READMEPDF
@@ -0,0 +1,420 @@
+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.
+
+
+