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 in __mul(, __in) cm __mul(, __cm) pt __mul(, __pt) em __mul(, __em) vs __mul(, __loutv) ft __mul(, __loutf) sp __mul(, __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 , for more information. For expressions, the PDF backend supports a simple prefix notation expression evaluator. The syntax is: = | = __add(, ) | __sub(, ) | __mul(, ) | __div(, ) | __sin() | __cos(, ) = __in | __cm | __pt | __em | __loutv | __loutf | __louts | __xsize | __ysize | __xmark | __ymark = | + | - | = 0-9.[0-9]* Note that expressions must start with an or a . It cannot start with a (or a ) although negation is simple to do: use __sub(0, ). 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=<>" example: "__link_source=<>" example: "__link_source=<>" 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=<>" example: "__link_external=<>" for URLs: syntax: "__link_external=<>>>" example: "__link_external=<>>>" ** 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=<>" example: "__link_URI=<>" (4) specifying a target location which cannot be linked to from external documents: syntax: "__link_target=<>" where name_of_target_link is in the PDF file example: "__link_target=<>" (5) specifying a target location which can be linked to from external documents: syntax: "__link_target_for_export=<>" where name_of_target_link is in the PDF file example: "__link_target_for_export=<>" 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= example: "__author=John Smith" @Graphic "" __title= example: "__title=PDF backend for Lout" @Graphic "" __subject= example: "__subject=Lout PDF support" @Graphic "" __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.