eLyXer User Guide
Alex Fernández (elyxer@gmail.com)
1 The Basics
elixir, n: a substance believed to cure all ills1.
eLyXer (pronounced elixir) is a LyX to HTML converter. While there are a ton of such projects all over the web, eLyXer has a clear focus on flexibility and elegant output.
eLyXer (including this guide and all accompanying materials) is licensed under the
GPL version 3 or, at your option, any later version. See the
LICENSE file for details.
Please visit the
main page to find out about the latest developments.
1.1 System Requirements
eLyXer requires Python 2.3.4, and should work with versions up to 2.6.x; it will convert documents generated by LyX 1.5.x to 1.6.y. It has been tested on the most common operating systems: on Mac OS X, Linux and Windows, with and without CygWin.
Resource usage should be quite frugal; eLyXer runs quite happily on my 1st-gen Asus Eee, with its puny Celeron@570MHz and 512 MB of RAM. It should also be fast — the Eee can convert ~200 pages of LyX text in just over 6 seconds. Performance is fairly linear: 200 pages take 10 × as long as 20, so there are no artificial bottlenecks. Memory usage stays low even when processing large documents, since conversion is done on the fly.
1.2 Installation
There is no complex installation procedure; just uncompress the distributed file to a suitable directory. Just write at the command line prompt:
$ tar -xzf elyxer-[version].tar.gz
Or for the .zip version:
$ unzip elyxer-[version].zip
A directory called elyxer should appear. If you have bash installed, to test that everything works fine you can just run the included tests:
$ ./run-tests
It will run a number of test and check the results, so you can see if everything is well. You also need to have installed the command-line tool diff to show differences between two files.
In addition you may want to try to convert the user guide:
$ ./elyxer.py --title "eLyXer User Guide" docs/userguide.lyx docs/userguide2.html
On Windows you have to include the Python executable:
> Python.exe elyxer.py --title "eLyXer User Guide" docs/userguide.lyx docs/userguide2.html
It should generate a working web page identical to the one distributed:
$ diff docs/userguide.html docs/userguide2.html
If nothing appears (i.e. both files are equal) then everything is working fine.
Since nothing is installed you have to reference the full path to the executable file every time you run it. If you want to avoid the hassle just place elyxer.py someplace in the path (e.g. /usr/bin on Linux).
1.3 Usage
eLyXer is a standalone command line tool. It can be invoked from the command line as:
$ elyxer.py [options] [source file] [destination file]
If the source file is omitted then STDIN is used; likewise, if no destination file is specified eLyXer will output to STDOUT. This allows its use in pipes and other flexible configurations. Once again, on Windows you have to explicitly call the Python executable:
> Python.exe elyxer.py [options] [source file] [destination file]
Some examples:
$ elyxer.py file.lyx file.html
converts file.lyx to file.html. Debug messages are shown.
$ cat file.lyx | elyxer.py > file.html
converts file.lyx to file.html, as before. This time debug messages are not shown.
$ elyxer.py file.lyx | grep "<blockquote>" | wc
counts all blockquote paragraphs.
$ elyxer.py file.lyx | wget --no-check-certificate --spider -nv -F -i -
checks all external links in a document recursively. (Local links will appear as unresolved, but they can be ignored.)
1.4 Image Processing
If the ImageMagick package is installed eLyXer will use the convert tool to create PNG versions of the images embedded in the document. If it is not installed eLyXer will show an error message and will not try to convert further images.
2 Advanced Use
There are some advanced uses for eLyXer if you want to extract the most of it.
2.1 Command Line Options
eLyXer supports a few command line optios. They are the following:
--help: show command line help.
--debug: show debug messages. They may help a developer understand your problem.
--quiet: be quiet and do not output messages (except errors). This way you can avoid the comforting “Parsing line 1000” messages. When STDIN or STDOUT are used (e.g. in a pipeline) --quiet is always enabled.
--nocopy: do not show the copyright notice at the bottom. If there is no author in the document --nocopy is always enabled.
--title "title": change the title of the generated web page.
--css [new.css]: change default CSS. See below.
--version: show version number and date. Use to check which version you are actually running.
--html: generate HTML 4.0 (instead of XHTML). The resulting pages should be easier to import from certain word processors.
2.2 CSS
HTML output, as generated, can be a bit crude. Some CSS wizardry can go a long way to make eLyXer output look nicer.
eLyXer tags most elements with the type so you can later modify them using a CSS. The HTML header reads like listing
↓, so the default remote CSS file is used.
<head>
<title>Your title here</title>
<link rel="stylesheet" href="http://www.nongnu.org/elyxer/lyx.css" type="text/css" media="screen"/>
</head>
Listing 2.1 CSS link automatically added to HTML
This sample CSS file is published on nongnu.org and distributed along with the scripts, docs/lyx.css. (You may have found that your document changes its appearance with time — this is the reason. The main author regularly publishes a new, updated version of lyx.css on nongnu.org, and all documents using it automatically appear with the changes.)
To give your document a customized appearance (or for pages to be accessible offline) you probably will want to use your own CSS file; to use it first copy it to the directory where your document resides (e.g. renaming it to custom.css), and customize as needed. Then run elyxer.py with the following option:
$ elyxer.py --css=custom.css document.lyx page.html
This will make the generated page.html use your custom.css file. The ‘=’ sign between the constant ‘--css’ and the name of the CSS file is optional.
2.3 Title
By default the generated web pages have the title “Converted Document”. If a PDF title is found then it is used instead. eLyXer does not try to use the proper LyX title, since it may be found in the middle of the document or not be present at all; scanning for it would mean doing two passes, one to look for the title in the document and another to output the web page.
You can change the title of the web page (which is not the title of the document) with the --title option:
$ elyxer.py --title "My Beautiful Document" document.lyx page.html
2.4 Segmenting Pages
Quite often you don’t want a huge monolithic page, but a set of linked pages. At the moment eLyXer does not allow you to do that, but a planned extension will.
2.5 HTML Code
The HTML code generated is technically XHTML Transitional, version 1.0
2, using UTF-8 encoding. Some programs have (in this day and age) trouble importing XHTML, notably some popular word processors. To work around this problem and provide more flexible output in general you can output HTML 4.0:
$ elyxer.py --html document.lyx page-to-import.html
Again, technically the code generated is HTML 4.01 Transitional
3 using UTF-8 encoding. Both versions should pass the W3C tests
4. If your particular web page doesn’t pass the tests, then it is a bug and it will be treated as such.
3 Work in Progress
As you have already seen eLyXer is very much a work in progress.
3.1 Known Issues
The following issues (including bugs and missing features) are acknowledged and should be solved soon.
-
Document structure is not preserved for certain document categories: for example in articles sections start with a <h2> element (when they should translate to <h1>).
-
On Mac OS X the output of a message with Unicode characters may cause an error. Workaround: run elyxer.py with the --quiet option.
-
Phonetic alphabet symbols are not supported — they appear in dark cyan: [sample].
-
Vertical spacing is not preserved. (It is hard to do in CSS without significant mangling.)
-
Multi-column layouts are lost. This one is almost impossible to get right in CSS, so there are no plans to even try.
-
BibTeX is not (yet) supported.
-
ERT (bare TeX code) is ignored.
3.2 Contact Information
If your problem does not appear in the above list, please let the author know; you can find him at
elyxer@gmail.com. In the words of Rich Talley: “the tool’s author really likes getting challenging documents and making eLyXer work with them”. You can send your sample documents and we will try to make eLyXer convert them acceptably. Any documents sent will be treated with the utmost confidentiality.
You can also join the
mailing list to discuss any information related to eLyXer. The author monitors the official LyX lists for mentions of eLyXer. Bugs can also be reported at
the Savannah page.
3.3 Extending eLyXer
eLyXer does not at the moment support all LyX features; sometimes it will ignore a command, sometimes it will signal it, and it might even refuse to work with certain documents. What can you do if eLyXer does not work with your LyX file? Worry not! Its flexible approach to processing allows anyone to write support for the missing commands.
eLyXer is written in Python so that it does not need to be compiled; its code is interpreted on the fly. See the accompanying
developer guide to learn how to extend eLyXer for your own purposes. If you know how to program in Python it should not be difficult to support other LyX features. If you don’t your best bet is to ask the author.
4 FAQ
Q: What versions of LyX are supported?
A: The tool is slowly improving; it now should work with LyX versions 1.5.5 to 1.6.2. It has been tested on Linux, Mac OS X and Windows.
Q: What can we expect from the tool in the future?
A: eLyXer should support a widening set of LyX features, and a couple of tricks of its own (such as page segmenting). Eventually it may be integrated with LyX so that it can be accessed from within the editor.
Q: Why did you leave out my favorite feature <insert random LyX command here>?
A: In short, because I wasn’t using it. Usually it is better to first aim for your own needs and then worry about others, or you will never get anything done. But if you let me know, I will be glad to help.
Q: My document changed its appearance without my intervention. Was it black magic, elves or what?
A: It probably uses the online CSS file, which is regularly updated. See section
↑ for details.
Q: I found a bug, what should I do?
Bibliography
[1] WordReference.com: “definition of elixir”, accessed March 2009. http://www.wordreference.com/definition/elixir
[2] W3C: “XHTML™ 1.0 The Extensible HyperText Markup Language (Second Edition)”, revised 1 August 2002. http://www.w3.org/TR/xhtml1/
[3] W3C: “HTML 4.01 Specification”, 24 December 1999. http://www.w3.org/TR/REC-html40/
[4] W3C: “Markup Validation Service”, accessed March 2009. http://validator.w3.org/
Copyright (C) 2009 Alex Fernández (elyxer@gmail.com)