lyxport.txt

用于OMNeT++的模板

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 the PDF GENERATION entry
        elsewhere in this document 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:
    [e-mail]

  Links

    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
    Fernando P閞ez <[e-mail]>.

    Please email me with comments, suggestions, bugfixes, etc.

    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 <[e-mail]>.
    Some of the code is a blatant ripoff of Steffen's code, using s2p to get
    Perl versions of his original sed scripts.

COPYRIGHT AND DISCLAIMER
    This program is Copyright 2001 by Fernando P閞ez.

    This program is free software; you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by the
    Free Software Foundation; either version 2 of the License, or (at your
    option) any later version.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
    Public License for more details.

    If you do not have a copy of the GNU General Public License write to the
    Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

    If the author of this software was too lazy to include the full GPL text
    along with the code, you can find it at:
    http://www.gnu.org/copyleft/gpl.html