eLyXer User Guide
Alex Fernández (elyxer@gmail.com)
The Basics
elixir, n: a substance believed to cure all ills1.
eLyXer (pronounced elixir) 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.
This guide and all accompanying materials are licensed under the
GPL version 3 or, at your option, any later version. See
LICENSE file for details.
System Requirements
eLyXer requires Python 2.3.4, and should work with versions up to 2.5.x. It might also require a Unix-based operating system (it has been tested it on Mac OS X, Linux and Windows with CygWin, but not on Windows).
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.
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. To test that everything works fine just move to the docs directory:
$ cd elyxer/docs/
and run the executab le on the user guide:
$ ../elyxer userguide.lyx userguide2.html
It should generate a working web page identical to the one distributed:
$ diff userguide.html userguide2.html
If nothing appears (i.e. both files are equal) then everything is working fine.
With this procedure you have to reference the executable file with full path every time you run it. If you want to avoid the hassle just place elyxer someplace in the path (e.g. /usr/bin on Linux).
Usage
eLyXer is a standalone command line tool. It can be invoked from the command line as:
$ elyxer [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. Some examples:
$ elyxer file.lyx file.html
converts file.lyx to file.html. Debug messages are shown.
$ cat file.lyx | elyxer > file.html
converts file.lyx to file.html, as before. This time debug messages are not shown.
$ elyxer file.lyx | grep "<blockquote>" | wc
counts all blockquote paragraphs.
$ elyxer 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.)
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.
Advanced Use
There are some advanced uses for eLyXer if you want to extract the most of it.
Appearance
HTML output, as generated, is 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 a CSS file
lyx.css is employed if found.
<head>
<title>Your title here</title>
<link rel="stylesheet" href="lyx.css" type="text/css" media="screen"/>
</head>
CSS link automatically added to HTML
A sample CSS file is distributed along with the scripts, docs/lyx.css. To use it just copy it to the directory where your document resides, and customize as needed.
Postprocessing
Another feature worth mentioning is the eLyXer postprocessor posxer.
At the moment the postprocessor is under construction.
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.
HTML Code
The HTML code generated is technically XHTML Transitional, version 1.0, using UTF-8 encoding. It passes the W3C tests
2. If your particular web page doesn’t pass the tests, then it is a bug and it will be treated as such.
Work in Progress
As you have already seen eLyXer is very much a work in progress.
Known Issues
The following issues (including bugs and missing features) are acknowledged and should be solved soon.
-
Document structure is botched for articles: sections start with a <h2> element (while they should be a <h1>).
-
Lists (such as this one) appear disjoint, with each item in a separate list. This causes all items to be numbered as “1”.
-
Chapters, sections and subsections should appear numbered as in LyX.
-
Text styles do not mix and match correctly. E.g. typewriter bold text will appear as typewriter or bold, but not both.
-
On Mac OS X the output of a message with Unicode characters may cause an error. Workaround: run elyxer with the —quiet option.
Reporting Bugs
If your problem does not appear in the above list, please let the author know.
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. But if you know how to program in Python it should not be difficult to support other LyX features. If you don’t you can always ask the author; you can find him at the elyxer gmail account.
FAQ
Q: What versions of LyX are supported?
A: At the moment the tool is very limited; it basically works for the author’s machine, i.e. LyX 1.5.5 on Debian lenny.
Q: What can we expect from the tool in the future?
A: As it matures (and with some help) eLyXer should support more recent LyX versions (1.6) and a wider set of documents.
Q: Why publish a tool in such an immature state?
A: As is often said, “release early, release often”. It seems better to put eLyXer in the hands of possible users as soon as possible, and then let them have a say on future extensions.
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.
[1] WordReference.com: “definition of elixir”, accessed March 2009. http://www.wordreference.com/definition/elixir
[2] W3C: “Markup Validation Service”, accessed March 2009. http://validator.w3.org/
Copyright (C) 2009 Alex Fernández (elyxer@gmail.com)