lyxport

用于OMNeT++的模板

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

=over

=item B<-r --runs> I<NUM>

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

=item B<-o --opts_l2h> I<'string'>

String with options to be passed to B<latex2html>. This string should be
protected by single quotes to allow double quotes inside of it.

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

B<latex2html> has I<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 F<.latex2html-init> which B<latex2html> always
reads at startup. See the B<latex2html> man page or the excellent online
documentation kept at http://www-texdev.mpce.mq.edu.au/l2h/docs/manual for
full details.

=item B<-h --html>

Export to HTML.

=item B<-p --ps>

Export to PostScript.

=item B<-f --pdf>

Export to PDF. See below the section L<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 I<all> three formats. If any is given, then only those formats
explicitly specified will be produced (e.g. B<-h -f> makes HTML and PDF only,
but not PostScript).

=item B<-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.

=item B<-t --tidy>

B<lyxport> will tidy up I<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
B<-tt>). If called twice, B<lyxport> will remove also the LaTeX file
associated with your LyX file, but I<only if> B<lyxport> I<itself created it
in the same run>. This behavior is meant to be a safety net, so that
B<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 F<file.lyx>
and end up only with your original file plus a single directory named F<file> which 
will contain F<file.html>, F<file.ps> and F<file.pdf> (plus some ancillary stuff for
the html version). This mode of operation is obviously provided for the neatness
freaks amongst us.

=item B<-d --debug>

Debugging mode: B<lyxport> will leave I<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 B<--tidy>.

=item B<-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
B<latex2html>.

=item B<--help>

Print this help and quit.

=item B<-m --man>

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

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

Note that if you installed B<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 F</usr/local/doc/lyxport-XXX>, where
F<XXX> is the version number. At installation time, you may manually change
the F</usr/local> prefix. Consult your local documents or ask your system
administrator for details on the specifics of your configuration.

=item B<-v --version>

Print version information and quit.

=item B<filename>

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

B<lyxport> accepts only I<one> filename at a time.

=back

=cut
###########################################################################
=pod

=head1 INTEGRATION WITH LyX

If you find that B<lyxport> is more succesful in exporting your files than
LyX's default calls to B<latex2html> and B<pdflatex>, you can modify LyX to
use B<lyxport> as its conversion routine. For LyX versions 1.1.6 and above, go
to C<< Edit->Preferences->Converters->Converters >> and specify B<lyxport> as your
converter for C<< LaTeX->HTML >> and C<< LaTeX->PDF >>. LyX's convention
is to call B<$$i> the current file.

For example, if you want to setup B<lyxport> to be your PDF export filter
under LyX, in the C<Converters> dialog, in the C<< 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 C<Converters> dialog is a bit confusing: after making changes, you must
first press the C<Modify> button for your changes to actually be recorded, and
then C<Save>.

You can similarly set up B<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.

=cut
###########################################################################
=pod

=head1 PDF GENERATION

=head2 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 I<me> solve the
font problem. Try it, your mileage may vary.

=over

=item 1

In your home directory, make (or modify it if it already exists) a file named F<.dvipsrc> which must contain the lines:

    p+ psfonts.cmz
    p+ psfonts.amz

=item 2

Make sure that the LaTeX preamble of your LyX file (or the part before C<\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.

=back

=head2 Figures

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

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

=head2 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}

=cut
###########################################################################
=pod

=head1 REQUIRES

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

=over

=item B<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).

=item B<latex>

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

=item B<dvips>

For making PostScript output.

=item B<latex2html>

For generating HTML from latex sources.

=item B<pdflatex>

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

=item B<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 B<ps2pdf>.

=item B<perl>

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

=back

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

=head2 Portability

There are calls in B<lyxport> to some Unix commands like B<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...

=cut
###########################################################################
=pod

=head1 TO DO

=over

=item *

Build rpm for more convenient installation.

=item *

Clean up the C<improve_tex4html()> code for readability.

=back

=cut
###########################################################################
=pod

=head1 VERSION

This is B<lyxport> version 0.3

=cut
###########################################################################
=pod

=head1 AUTHOR

Fernando P閞ez E<lt>[e-mail]<gt>.

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

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

=cut
###########################################################################
=pod

=head1 ACKNOWLEDGEMENTS

Inspired on the B<lyx2html> script by Steffen Evers
E<lt>[e-mail]<gt>.  Some of the code is a blatant ripoff of
Steffen's code, using B<s2p> to get Perl versions of his original B<sed>
scripts.

=cut
###########################################################################
=pod


=head1 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

=cut
#************************** end of file <lyxport> **********************