eLyXer User Guide
Alex Fernández (elyxer@gmail.com)
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.
System Requirements
eLyXer requires Python 2.3.4, and should work with versions up to 2.6.x. 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.
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 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 need to have installed the command-line tool diff to show differences between two files.
You may also want to try to convert the user guide:
$ ./elyxer —title "eLyXer User Guide" docs/userguide.lyx docs/userguide2.html
On Windows you have to include the Python executable:
> Python.exe elyxer —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 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 [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 [options] [source file] [destination file]
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.
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.
Appearance
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>
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 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 with the following option:
$ elyxer ‐‐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. You can also change the title of the web page (which is not the title of the document) with the ‐‐title option:
$ elyxer ‐‐title "My Beautiful Document" document.lyx page.html
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 not preserved for certain document categories: for example in articles sections start with a <h2> element (when they should translate to <h1>).
-
Lists (such as this one) appear disjoint, with each item in a separate list. This causes all items to be numbered as “1”.
This happens only in the HTML file converted with eLyXer, not from within LyX.
By the way, the previous note (and this one) should not appear on the HTML.
-
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.
-
The title of all converted documents is “Converted document”. Not pretty, but you can change it with the ‐‐title option. It will also pick up the PDF title if present.
-
Phonetic alphabet symbols are not supported — they appear in dark cyan: [sample].
-
There is no visual link between a footnote and its place of insertion.
And still less on what to do with margin notes: should they appear differently?
-
Vertical spacing is not preserved. It is hard to do in CSS.
-
Multi-column layouts are lost. This one is almost impossible to get right in CSS, so there are no plans to even try.
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.
Contact Information
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: As it matures (and with some help) eLyXer should support a wider set of documents. Eventually it may be integrated with LyX so that it can be accessed from within the editor.
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.
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
↑: “Appearance” for details.
[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)