WPLaTeX: A simple Amiga WordPerfect to LaTeX translator REQUIREMENTS Should work on any Amiga running AmigaOS version 2.0 (V36) or higher. To make meaningful use of this program, you will need a working installation of Donald E. Knuth's TeX typesetting software plus the LaTeX macro package (version 2e). COPYRIGHT This program is Freeware. Distribute it at will; its intended use is free for all. Otherwise, full copyright applies. INTRODUCTION WPLaTeX converts Amiga WordPerfect files to LaTeX (version 2e). If you are not familiar with LaTeX, this is probably not the tool for you. If you are, it lets you typeset and print Amiga WordPerfect 4.1.x documents using many advanced features that WordPerfect 4 lacks or that don't work well in the Amiga version such as different font sizes, generated indexes and table of contents, using the Euro symbol, and automatic section numbering. Useful as the translator could be for those who do not own a copy of Amiga WordPerfect but sometimes need to work with Amiga WordPerfect documents, this manual generally assumes that you have access to the WordPerfect program. Since WPLaTeX was written in a hurry for our own use--the bulk of the program was produced in a single day, although many individual WordPerfect command codes were added later--it is far from perfect. On the other hand we have used it to translate some large books, giving me reasonable confidence in its stability. See the Problems and Future sections below for an overview of known deficiencies. INSTALLATION Simply copy the program binary to where you want to keep it; no external files are needed for it to work. Copy to this documentation to where you keep your manuals (such as the standard HELP: directory). The program can not be made resident, so please do not attempt to set the pure (p) protection flag on the executable file. USAGE WPLaTeX can be run from the Command Line Interface (CLI) only; it has no graphical user interface. Most of the work involved in pretty-printing a WordPerfect document using this program is on the LaTeX side, where things are fairly tedious and command-line driven anyway because of the various other programs involved. Those are briefly described in this manual, but in practice you will probably need to learn how to use them. Start WPLaTeX from the Shell. To translate an Amiga WordPerfect 4.1.x file into a LaTeX file, pass both filenames to WPLaTeX, like so: wplatex inputfile outputfile.tex ...where inputfile is the WordPerfect file, and outputfile.tex is the name you want to give to the LaTeX output file. The options available for customizing the generated output file are described below. Barring any errors, you will now be able to run through LaTeX: latex outputfile.tex If again all goes well, this in turn generates a device independent (or DVI) file called outputfile.dvi which can be translated to a PostScript file using dvips or a similar program, and then printed either by a PostScript-aware printer or using an interpreter such as GhostScript. Reality, unfortunately, is usually even more complicated. Not all constructs available in WordPerfect are translated to working LaTeX. For this reason running the generated file through LaTeX may cause errors even if no problems were reported during translation. See the Problems and Future sections for some examples of things that may go wrong. OPTIONS At the moment WPLaTeX can be run from the Command Line Interface only. Below is a description of the command-line options it accepts, in standard AmigaDOS notation. FILE (always needed) Name of Amiga WordPerfect 4.1 file to read, including its full path. This is a required argument. TO Optional name of file to write LaTeX output to (this name will typically end in .tex as is the convention with TeX input files). If no name is given, the converted data is printed to standard output (the console window by default). Thus wplatex input.wp >output.tex is equivalent to wplatex input.wp TO output.tex If the output file already exists, it will be overwritten. CLASS=DOCUMENTCLASS (keyword required) Defines LaTeX "document class." The default class is 'article,' but you may want to change it to eg. 'book,' 'letter,' 'report' etc. More exotic classes such as 'slides' may work, but can impose added restrictions. This may cause problems if for instance the LaTeX output generated for your document contains commands that are not supported by the document class you specify. In such cases LaTeX will print an error message while processing your LaTeX file. There is no easy way to predict what will and will not work, so don't be afraid to experiment. The recommended approach is to first try to get your document to translate properly with the default document class, then translate it again using the CLASS option to specify another class. If this trips up any new errors while running the document through LaTeX, the error text you get is often cryptic but will usually show enough readable context to give you some idea of where things went wrong. Since the place of LaTeX commands in the output file correspond very tightly to the WordPerfect commands in the output file, this knowledge can be used to guess what WordPerfect commands are conflicting with the document class. At this point you may decide to change your input file, or revert to using the default document class, or edit the LaTeX output file manually to work around the error. PKG or USEPACKAGE (keyword required) Tells LaTeX to load one or more additional "packages" for processing your document. Multiple packages should be separated by commas, eg. wplatex input.wp output.tex USEPACKAGE babel,amstex,epic signifies that the LaTeX file output.tex uses the packages 'babel,' 'amstex' and 'expic.' OPTS or ACKAGEOPTIONS (keyword required) Dictates any optional arguments to be passed to the package(s) selected using the USEPACKAGE option above. LATEXSPACING (switch) Trust the input WordPerfect input file to have LaTeX-aware spacing. This treats a sequence of whitespace as a single word separator, and one of hard returns as a single paragraph separator. This means that extra hard returns or spaces inserted as visual spacing is ignored. The default is to mimick the vertical spacing of the WordPerfect file in the output, with a notional line height that can be set using the LINEHEIGHT option. This option is likely to get you better results for most documents, perhaps after some cleaning up in the WordPerfect file. Especially whitespace around section headers will probably be more appropriately sized. TITLE (keyword required) Lets you select a title for your document. This is embedded in the LaTeX output file, which may be useful eg. if you want to share it with others. Moreover, this title is featured prominently on the document's title page if you elect to have one generated (see MAKETITLE option). AUTHOR (keyword required) Includes the name of the document's author in the LaTeX file. The name may contain both special characters like "ö" and raw LaTeX. If there are multiple authors, they must be separated by the command '\and': wplatex input.wp output.tex AUTHOR="Smith \and Jones" When generation of a title page is requested using the MAKETITLE option, author name is included. DATE (keyword required) Like TITLE and AUTHOR, adds title page information--in this case, the document's publication date. Even if no title page is generated (ie. if the MAKETITLE option is not used), this may be useful for document identification if you share the LaTeX file with others or archive it in long-term storage. The date is currently a free-form string that will be copied directly into the output file, so it may contain anything including raw LaTeX commands (but the special characters above the normal ASCII range are translated to their proper LaTeX sequences). MAKETITLE (switch) Makes LaTeX generate a title page from the information given using the TITLE, AUTHOR, and DATE options. MAKEINDEX (switch) Causes generation of an index based on WordPerfect's "index" entries, suitable for processing with the MakeIndex program. You will need to obtain the MakeIndex program and familiarize yourself with it to use this option. A version of this program can be found on Aminet in text/tex; its source code is available from most CTAN sites. TOC (switch) Generates a table of contents for your document. When using this option, you may have to run the generated file through LaTeX more than once to get correct page numbers in the table. Where this is necessary, LaTeX will ask to be run again. CONTENTSNAME (keyword required) When generating a table-of-contents file, this option can be used to replace the header printed over the table. NOVERSE (switch) Suppress automatic verse detection. By default WPLaTeX attempts to recognize verse-style formatting, meaning lines of text each ending in hard returns, as opposed to prose-style formatting where all lines except the last in a paragraph end in soft returns. When "verse" text is detected, it is declared as such in the output file so LaTeX can indent it fittingly, and also silence a certain LaTeX warning, "underfull hbox," that you would otherwise see for any short line ending in a hard return. LINEHEIGHT (number; keyword required) Height in millimeters to substitute for a blank line in the WordPerfect file. Provided that the LATEXSPACING option is not used, every blank line in the input file will be translated to a vertical whitespace of this height. PARINDENT (number; keyword required) Indentation (in millimeters) of the first line of any new paragraph, compared to the normal beginning of a line. Default is zero, meaning no difference in indentation between a paragraph's first line and the rest of the paragraph. PARSKIP (number; keyword required) Vertical spacing, in millimeters, between paragraphs. This amount of space is always inserted between two consecutive paragraphs, in addition to any blank lines that may be between them. If this option is not used, vertical paragraph spacing will default to a single LINEHEIGHT. SECNUMDEPTH (number; keyword required) By default, all section headers are numbered by LaTeX. Use this option to exclude lower-order sections from this numbering. This currently uses LaTeX's own numbering scheme. A depth of -2 will suppress all numbering. One of -1 lets only WordPerfect's "level 0" headings be numbered, and one of 0 produces section numbers for level 0 and level 1 headers. The higher the section numbering depth, the more types of headers will be numbered. SECINDEXDEPTH (number; keyword required) Set "detail level" of generated table of contents (if TOC option is used). Sections whose depth level exceeds this number are not included in the table of contents, and are not numbered. Use higher numbers like 4 to get a larger, more detailed index, or lower numbers like 1 to get a very brief index describing only the coarsest outline of the document. NOTE: This option is similar to SECNUMDEPTH, but its numbering scheme is not currently consistent with the one used there. TOPMARGIN (number; keyword required) Amount of space, in millimeters, to keep free at the top of the page above the document's contents when printing. You'll usually not need this option; if you are working with a paper size that the default isn't right for, there is usually a LaTeX style file (such as a4din) that sets the proper margin for you. I use USEPACKAGE=a4din to print on DIN A4 format, which is slightly different from the US legal format. TEXTHEIGHT (number; keyword required) Vertical page space in millimeters that should be considered available for printing the document's contents. To get meaningful results, this must be lower than the figure given in TOPMARGIN plus the height of the paper you're printing on. Again, this is usually better set by selecting an appropriate style using the USEPACKAGE option. BASELINESKIP (number; keyword required) Line spacing in millimeters, measured from the bottom of one line of text to the bottom of the next. The default is usually fine. PROBLEMS Before anything else, proofread your results! There are many things that could go wrong, and only some will elicit any warnings. Before you send your letter (or publish your article, or print your book, or present your slides or whatever) that was written in WordPerfect and translated to LaTeX using this program, make sure you've read a first print to see if anything is coming out differently than expected. If you hit any problem with WPLaTeX, please check this section and the Future section for a workaround. If your problem does not appear to be one of these, please let me know (see the Author section for contact information) and I'll try to fix it in a new version. Please include a copy of the offending WordPerfect file if necessary so I can track down the problem! This translator is far from perfect. Lacking a full specification of WordPerfect's file format, I had to base this code on the reverse-engineering of WP files. As a result not all WordPerfect codes may be handled by the translator. Other codes cannot be translated due to the way WPLaTeX reads the WordPerfect file and writes its LaTeX output (to wit, one byte at a time without scanning back or forth inbetween). If the generated LaTeX document is not satisfactory you may need to edit it manually before processing it using LaTeX. As this can be a tiresome and error-prone procedure, it is usually preferable to modify the WordPerfect file so that it translates properly. Use WordPerfect's Reveal Codes mode to see what is going on "under the hood." Adapting the WordPerfect file only ensures that you can continue to maintain that single file in the future without having to modify the LaTeX file every time you translate it. Specifically, some Amiga WordPerfect users rarely use features such as section headers. Include such commands whenever possible to tell LaTeX as much as possible about how the document should be formatted. Below is a list of problems that are to be expected in the current version. - Sometimes a character or brief piece of text appears twice in the LaTeX version of the document although it appears only once in the original file: This could be because of a hidden "overstrike" code in the WordPerfect file, followed by a repetition of the directly preceding scrap of text. I don't know why this happens, but check the original text using WordPerfect's Reveal Codes feature. - Double or even redundant, different numbers in section headers: LaTeX has its own auto-numbering logic, and sections are numbered by default. Automatic section numbers generated by WordPerfect are ignored by the translator. Make sure you have not numbered your sections by hand in the WordPerfect documents. If you wish to disable the numbers inserted by LaTeX, try translating the WordPerfect file again using the SECNUMDEPTH option. - Tabs don't work. Not supporting them greatly simplified the program's design, and I was in a hurry when I wrote it. Don't count on tabs ever being supported properly. Using WordPerfect's Indent command instead may help, but may also produce strange results. In general, the translator at this time is quite cavalier in handling horizontal spacing. - Inexplicable irregularities in indentation: If some lines in the LaTeX-processed document appear further to the left or right than the others, this may be due to automatic verse detection. Check your WordPerfect file for hard returns that should have been soft returns or vice versa. You may find either a hard return in the middle of a paragraph or a soft return that should have been a hard return. If there is but you do not wish to change your WordPerfect file, use the NOVERSE option to disable verse detection. The latter may trigger a series of "underfull hbox" warnings when running LaTeX. - Irregular or undesirable whitespace between paragraphs: This may be due to the combination of the paragraph spacing inserted by LaTeX and the spacing generated by the translator to match the look of the WordPerfect document. To fix this, try setting LaTeX's paragraph spacing to zero (using the PARSKIP option: Just include PARSKIP=0 on the command line when translating the WordPerfect file) and/or selecting the LATEXSPACING option (by including the keyword LATEXSPACING in the command line). - Columns are supported, but horizontal space is always divided equally among all active columns. Column widths as set in the WordPerfect file are ignored by the translator. There is currently no way around this, sorry. - "LaTeX Error: Environment multicols undefined." -- when translating WordPerfect files that use the "columns" feature, LaTeX will need to be told that the translated file uses the "multicol" (note singular, no `s' at the end) LaTeX package. Do this using the USEPACKAGE (or PKG for short) option: Retranslate the WordPerfect file but this time, add "USEPACKAGE multicol" (or PKG multicol for short) to the command line. If you were already using the USEPACKAGE option, just add ",multicol" to the end, eg. "PKG=a4din,multicol" - Using special text styles such as bold or italics in an indented block causes LaTeX errors: This happens when the bold or italicized (or whatever) text spans a hard or soft return in the block. To work around this, end the bold or italicized (or whatever) block before the end of the line, and restart it at the beginning of the next line. In the easiest case, you may find that the problem is a line break occurring directly before eg. an "end bold" command. When this is the case, simply interchanging the two codes will fix the problem. - The translator can be confused by little things such as accidentally keeping one or more spaces in what was supposed to be an empty line. Many glitches can be worked around by checking for this kind of invisible disturbance. - Style nesting doesn't work properly, eg. "[italics] [bold] text1 [end italics] text2 [end bold]" will set text2 in italics, rather than in bold as intended. This may affect most other "paired" codes as well, such as the beginning and end markers of section titles. It will probably be fixed in the future. For now, please make sure that such markers are properly nested, ie. when a style block ends, be sure that it is always the last style block to be started (not counting any blocks that had already been closed before, of course). You may find more complicated cases, such as "[italics] text1 [bold] text2 [end italics] text3 [end bold]". This will set text3 in italics rather than in bold--fix the problem by setting up two separate bold blocks: "[italics] text1 [bold] text2 [end bold] [end italics] [bold] text3 [end bold]." - Style nesting problems may also occur with regard to WPLaTeX's automatic verse detection. If the generated LaTeX file contains warnings about "paragraph style changed from verse to prose" (or vice versa) in the vicinity of an offending LaTeX construct, try translating your WordPerfect file again using the NOVERSE option. - In special environments such as an automatically generated index, special characters work differently. WPLaTeX currently does not handle this properly, so the index may contain incorrect characters or generating it may cause errors. - The translator tries to keep track of whether the current paragraph in WordPerfect is in "prose" or in "verse" style. Whenever this changes unexpectedly, an invisible (at least when printing) warning is included in the output document. This was added to help spot accidental hard returns in WordPerfect files where the author intended a soft return ("verse style" means all lines end in hard returns) which may turn up ugly "dents" in the right margin. Also, verse is detected in order to declare the text's style to LaTeX, allowing it to be typeset appropriately. You may wish to look through the output file and if any warnings occur, see if the WordPerfect file has an unwanted hard or soft return. - WPLaTeX aborts with "failed assertion" message: This is an internal error in the translator (for which I'd like to offer my apologies in advance). This should never happen--though it is probably inevitable that it will happen to somebody at some point. If it happens to you, please let me know about it in all available detail. REFERENCES This program, as well as an Amiga build of the MakeIndex program needed to generate indexes for converted documents, can be found on Aminet. Aminet mirrors at the time of writing include: http://wuarchive.wustl.edu/aminet/ http://de.aminet.net/aminet/ http://ftp.unina.it/~aminet/ http://ftp.sunet.se/~aminet/ ftp://ftp.luth.se/pub/amiga/ ftp://task.gda.pl/pub/aminet/ A complete TeX installation including LaTeX 2e can be obtained as part of the Geek Gadgets distribution. Geek Gadgets mirrors at the time of writing can be found in: ftp://ftp.ninemoons.com/pub/geekgadgets/amiga/m68k/snapshots/current/ ftp://ftp.telesys-innov.fr/pub/amiga/AmigOS/ ftp://ftp.uni-erlangen.de/pub/amiga/ade/ ftp://ftp.grolier.fr/pub/amiga/ade/ ftp://ftp.uni-trier.de/pub/amiga/ade/ LaTeX can be found separately on the Comprehensive TeX Archive Network (CTAN), together with tons of other useful TeX-related material. To install any of these, you need to have a working TeX installation. CTAN mirrors at the time of writing include: ftp://ctan.unsw.edu.au/tex-archive/ ftp://mirror.aarnet.edu.au/pub/tex-archive/ ftp://ftp.dante.de/tex-archive/ ftp://ftp.tex.ac.uk/tex-archive/ ftp://ftp.univie.ac.at/packages/tex/ ftp://ftp.belnet.be/packages/TeX/ ftp://ftp.cdrom.com/pub/tex/ctan/ For an excellent introduction into using LaTeX, with or without prior TeX knowledge, I can recommend Leslie Lamport's LaTeX: A Document Preparation System (Addison-Wesley, ISBN 0-201-52983-1). Advanced users may want to get The LaTeX Companion (Addison-Wesley, ISBN 0-201-54199-8). FUTURE One planned extension is to allow LaTeX commands to be inserted into the WordPerfect file, so that for instance graphics may be included into a document. Not supporting graphics has always been the great drawback of WordPerfect 4 for the Amiga. In order to do this however, a "harmless" WordPerfect command will need to be chosen to host the embedded LaTeX code without affecting the layout of the WordPerfect document too much. A sequence of any number of spaces is currently considered a single space. Future versions may try to match whitespace width to what was found in the WordPerfect file; this would be similar to what is currently done with hard returns, and such a feature would be subject to the LATEXSPACING option. Drawing horizontal bars using dashes may currently yield ugly results. Future versions may work around this. Font selection is not yet implemented, which can be a problem particularly when translating "ASCII-art" drawings in a monospaced (non-proportional) font. Future versions may change this. Date codes have not yet been implemented. Tables are not supported yet. Page footers are not supported, but headers are. If a footer is defined in the WordPerfect file, the translator will issue a warning and convert the footer to a page header instead. Localization could be useful, particularly if it overrides LaTeX's built-in phrases like "Contents" and "Abstract" to national variants. I'm not sure this is needed though. AUTHOR Bug reports, feature requests, or any other comments (but preferably nice ones!) are welcome at Jeroen T. Vermeulen If you have a bug to report, please send me an email with the following details. This will help me greatly in fixing the problem: (*) The version of WPLaTeX you're running (*) The exact nature of the problem (*) Any error messages you may get (*) If applicable, copies of your WordPerfect file and any generated LaTeX (*) In case of program failure or crashes: Your CPU model and OS version As always, if a program crashes you might try increasing your stack size using the Stack command. REVISION HISTORY 2000-02-23 First Aminet release