# NAME

lyxport - Export a LyX or LaTeX file to HTML, PostScript and PDF.

# SYNOPSIS

lyxport [options] file

Perl script which takes a LyX or LaTeX file as its only argument and produces HTML, PostScript and PDF versions of the document. The name is short for lyx export''.

You can call lyxport with a filename with or without extension: file, file.lyx and file.tex will all work. lyxport will update the LaTeX file if there is a corresponding LyX file with a newer timestamp.

Use lyxport --help for more information, and lyxport --man for a full man page.

# DESCRIPTION

## Purpose

LyX ( http://www.lyx.org ) is a wonderful document processor, which can produce from a single source multiple versions for different purposes: a PostScript file for printing on a Unix-type system, a PDF file for distribution across multiple operating systems, or an HTML file for Internet display. It accomplishes this by exporting its own file format to a LaTeX file and then running various converters on this resulting file.

However, it turns out that this process isn't exactly foolproof, as these converters have all sorts of little quirks which can produce anything from surprises in the way the final result looks like to outright failure of the export process. The purpose of lyxport is to serve as a smart wrapper'' around those export facilities which LyX normally uses, trying to massage the LaTeX file that everything starts from in the hopes of having better success in producing HTML and PDF (PostScript usually poses no problems).

lyxport also allows you to keep around only the LyX file, and possibly any ancillary figure files. lyxport takes care of generating (and removing afterwards if instructed to do so) any intermediate files necessary for the export process.

For example, in order to make PDF from a LaTeX file, any included eps figures need to be converted to pdf format. But LyX likes to have the figures in eps format for on-screen display, which is a great feature to have. lyxport allows you to keep your LyX file as usual (with references to .eps figures) and will make .pdf versions of any included figure on the fly as needed. You can even ask it to remove those pdf files after it finishes, if you really want to maintain a minimum of files around (though it will have to remake them again if you ever need to update your pdf exported document).

## Command line use

If you simply type lyxport file, it will try to make PostScript, HTML, and PDF versions of your file, putting them all in a single directory named file (without a .lyx or .tex extension if your file had one). But it has command line options for making only the formats you want, and fairly detailed control over its behavior.

## If you don't have LyX

Despite its name, if you are a regular LaTeX user and don't even have LyX installed in your system, lyxport can still be useful to you. In fact, lyxport only uses LyX once in each run: if there is no file.tex or if file.lyx file is newer than file.tex, lyxport updates file.tex from file.lyx. But if there is no file.lyx at all it will simply use file.tex and proceed with all its functionality intact.

# OPTIONS AND ARGUMENTS

Single letter options (preceded by a single dash -) can be bundled: -pf is equivalent to -p -f. Long options (preceded by two dashes --) can be abbreviated to as few letters as needed to clear ambiguity.

-r --runs NUM
Set number of latex runs by hand (otherwise auto-determined).

-o --opts_l2h 'string'
String with options to be passed to latex2html. This string should be protected by single quotes to allow double quotes inside of it.

For example, if you want to pass to latex2html the option -info my info'' you can do so with lyxport -o ' -info my info'' ' (the extra spaces around the quote marks are not needed, they are here only for the sake of clarity).

latex2html has many command-line options. For a project you are working constantly on, it may be more convenient to permanently set some of those options via a file called .latex2html-init which latex2html always reads at startup. See the latex2html man page or the excellent online documentation kept at http://www-texdev.mpce.mq.edu.au/l2h/docs/manual for full details.

-h --html
Export to HTML.

-p --ps
Export to PostScript.

-f --pdf
Export to PDF. See below the section PDF GENERATION for details on how to obtain nice-looking PDF from your LaTeX sources.

If none of the three above options is specified, the default behavior is to export all three formats. If any is given, then only those formats explicitly specified will be produced (e.g. -h -f makes HTML and PDF only, but not PostScript).

-c --clean
Do a clean start export, removing first any html directory, .aux, .log and .toc files which may have been left from previous runs.

-t --tidy
lyxport will tidy up after itself, removing .aux, .log and .toc files left in the current directory. Use this only for final'' publication of documents, as those files are otherwise useful to shorten the time of runs.

This option is incremental: you can call it twice (you can bundle it as -tt). If called twice, lyxport will remove also the LaTeX file associated with your LyX file, but only if lyxport itself created it in the same run. This behavior is meant to be a safety net, so that lyxport doesn't accidentally remove LaTeX files which you may have manually modified in some way.

So if this option is called twice, you can start with a LyX file named file.lyx and end up only with your original file plus a single directory named file which will contain file.html, file.ps and file.pdf (plus some ancillary stuff for the html version). This mode of operation is obviously provided for the neatness freaks amongst us.

-d --debug
Debugging mode: lyxport will leave all temporary files it creates lying around. If a particular target refuses to build, you can then try to run the respective commands on the temporary files manually, and possibly diagnose the source of the problem.

This option will override any calls made to option --tidy.

-l --cld
Special command-line debugging mode: only prints (in a rather primitive form) the names and values of all command-line options which were set. Useful for finding problems with complicated option strings being passed to latex2html.

--help
Print this help and quit.

-m --man
Print a complete man page. lyxport is documented using embedded pod strings, so you can see its full documentation using the command perldoc lyxport.

You can also convert this documentation to other formats using the pod2_anything family of converters (pod2html, pod2latex, pod2man and pod2text). See their respective man pages for details.

Note that if you installed lyxport properly, you should already have a man page available, plus html and plain text versions of the documents. These are by default installed to a directory named /usr/local/doc/lyxport-XXX, where XXX is the version number. At installation time, you may manually change the /usr/local prefix. Consult your local documents or ask your system administrator for details on the specifics of your configuration.

-v --version
Print version information and quit.

filename
The given filename may have a .lyx or .tex extension (or none at all). lyxport will update the tex file from the lyx file if necessary.

lyxport accepts only one filename at a time.

# INTEGRATION WITH LyX

If you find that lyxport is more succesful in exporting your files than LyX's default calls to latex2html and pdflatex, you can modify LyX to use lyxport as its conversion routine. For LyX versions 1.1.6 and above, go to Edit->Preferences->Converters->Converters and specify lyxport as your converter for LaTeX->HTML and LaTeX->PDF. LyX's convention is to call $$i the current file. For example, if you want to setup lyxport to be your PDF export filter under LyX, in the Converters dialog, in the LaTeX->PDF(pdflatex) option, set:  lyxport --pdf$$i

This way you'll be able to export to pdf directly from within LyX, even if your figures are in eps format.

LyX's Converters dialog is a bit confusing: after making changes, you must first press the Modify button for your changes to actually be recorded, and then Save.

You can similarly set up lyxport to be your LaTeX to HTML converter.

For LyX versions earlier than 1.1.6 (which didn't have the new Preferences dialog) these same options can be configured via your LyX defaults file. See the LyX documentation for details.

# PDF GENERATION

## Fonts

Normally PDF documents made on Unix-type systems from LaTeX sources produce horrible looking fonts when viewed with Adobe's own Acrobat Reader. I don't know the many intricacies of the problem (you can search for the details on your own). I'll simply list here the trick that has helped me solve the font problem. Try it, your mileage may vary.

1. In your home directory, make (or modify it if it already exists) a file named .dvipsrc which must contain the lines:
    p+ psfonts.cmz
p+ psfonts.amz

2. Make sure that the LaTeX preamble of your LyX file (or the part before \begin{document} if you are using straight LaTeX files) contains:
    \usepackage[T1]{fontenc}
\usepackage{ae,aecompl}

This will guarantee that T1 encoded fonts come out looking good in the final PDF.

## Figures

pdflatex (if I understand correctly) only accepts filenames with a single . in them, and only uses graphic files with extensions pdf, png, jpg and tif (all lowercase). lyxport will do its best to analyze your latex file and try to change references to figures to accommodate pdflatex, by creating temporary copies of your image files if necessary.

Ideally, you should be able to have for example a figure called fig.1.JPG along with a fig.1.eps (for lyx to preview it), and lyxport would export a pdf document without leaving any more files after itself, even though it temporarily had to create fig_1.jpg to make pdflatex happy. As I said, ideally... If things don't quite work, try the --debug option. If you find a fix for the problem, mail it to me: fperez@pizero.colorado.edu

In order for URLs and similar elements to produce proper active links in the PDF document, you need to include in your LaTeX preamble the line

    \usepackage{hyperref}

# REQUIRES

lyxport relies on some programs listed below, for the reasons indicated:

lyx
To make LaTeX files from LyX files. Tested with lyx version 1.1.6fix1, should work with earlier versions (perhaps with minor changes to the way LyX is called).

latex
To produce PostScript and for latex2html to work properly (cross-references).

dvips
For making PostScript output.

latex2html
For generating HTML from latex sources.

pdflatex
For making PDF output from a latex file with proper cross-referencing and internal document links.

epstopdf
A Perl script to automatically generate pdf versions of eps figures included in lyx files. It is more robust in its handling of various eps quirks than a straight call to ps2pdf.

perl
Well, it's a Perl script after all, isn't it?

However, partial use of lyxport is still possible without some of these components. If for example you don't have latex2html in your system, you can still use lyxport to produce PostScript and PDF. Various combinations are possible.

## Portability

There are calls in lyxport to some Unix commands like rm -rf. For this reason it is not totally portable. These calls are however reasonably few and could be eliminated if there is enough demand by replacing them with equivalent Perl code. It's just more work...

# TO DO

• Build rpm for more convenient installation.

• Clean up the improve_tex4html() code for readability.

# VERSION

This is lyxport version 0.3

# AUTHOR

The most current version of lyxport should always be available at http://www-hep.colorado.edu/~fperez/lyxport

# ACKNOWLEDGEMENTS

Inspired on the lyx2html script by Steffen Evers <tron@cs.tu-berlin.de>. Some of the code is a blatant ripoff of Steffen's code, using s2p to get Perl versions of his original sed scripts.