#LyX 1.6.7 created this file. For more info see http://www.lyx.org/
\lyxformat 345
\begin_document
\begin_header
\textclass article
\begin_preamble
%   eLyXer -- convert LyX source files to HTML output.
%
%   Copyright (C) 2009-2010 Alex Fernández
%
%   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 3 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.
%
%   You should have received a copy of the GNU General Public License
%   along with this program.  If not, see <http://www.gnu.org/licenses/>.
\end_preamble
\use_default_options false
\language english
\inputencoding auto
\font_roman default
\font_sans default
\font_typewriter default
\font_default_family default
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100

\graphics default
\paperfontsize default
\spacing single
\use_hyperref false
\papersize default
\use_geometry false
\use_amsmath 1
\use_esint 1
\cite_engine basic
\use_bibtopic false
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\tracking_changes false
\output_changes false
\author "" 
\author "" 
\end_header

\begin_body

\begin_layout Title
\begin_inset Graphics
	filename elyxer.svg
	lyxscale 50

\end_inset

eLyXer User Guide
\end_layout

\begin_layout Author
Alex Fernández (elyxer@gmail.com)
\end_layout

\begin_layout Standard
\begin_inset CommandInset toc
LatexCommand tableofcontents

\end_inset


\end_layout

\begin_layout Section
The Basics
\end_layout

\begin_layout Quotation

\emph on
elixir, n: a substance believed to cure all ills
\begin_inset CommandInset citation
LatexCommand cite
key "wordreference-elixir"

\end_inset

.
\end_layout

\begin_layout Standard
eLyXer (pronounced 
\emph on
elixir
\emph default
) 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.
\end_layout

\begin_layout Standard
eLyXer (including this guide and all accompanying materials) is licensed
 under the 
\begin_inset CommandInset href
LatexCommand href
name "GPL version 3"
target "http://www.gnu.org/licenses/gpl-3.0-standalone.html"

\end_inset

 or, at your option, any later version.
 See the 
\family typewriter
LICENSE
\family default
 file for details.
\end_layout

\begin_layout Standard
Please visit the 
\begin_inset CommandInset href
LatexCommand href
name "main page"
target "index.html"

\end_inset

 to find out about the latest developments.
\end_layout

\begin_layout Subsection
System Requirements
\end_layout

\begin_layout Standard
eLyXer requires Python 2.3.4, and should work with versions up to 2.6.
\begin_inset Formula $x$
\end_inset

; it will convert documents generated by LyX 1.5.
\begin_inset Formula $x$
\end_inset

 to 1.6.
\begin_inset Formula $y$
\end_inset

.
 It has been tested on the most common operating systems: on Mac OS X, Linux
 and Windows, with and without CygWin.
\end_layout

\begin_layout Standard
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 50 seconds.
 Performance is fairly linear: 200 pages take 
\begin_inset Formula $10\times$
\end_inset

 as long as 20, so there are no scalability problems.
 Memory usage stays low even when processing large documents, and conversion
 can be done on the fly (with 
\family typewriter
--lowmem
\family default
) for even lower memory requirements.
\end_layout

\begin_layout Subsection
Installation
\end_layout

\begin_layout Standard
This section looks at how to install eLyXer on your system.
\end_layout

\begin_layout Subsubsection*
Download eLyXer
\end_layout

\begin_layout Standard
First you will need to fetch the official distribution file from the 
\begin_inset CommandInset href
LatexCommand href
name "download area"
target "https://savannah.nongnu.org/files/?group=elyxer"

\end_inset

.
 Now, there is more than one way to install eLyXe, but all of them start
 by uncompressing the distributed file to a suitable directory.
 Just write at the command prompt:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 tar -xzf elyxer-
\emph on
[version]
\emph default
.tar.gz
\end_layout

\begin_layout Standard
Or for the 
\family typewriter
.zip
\family default
 version:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 unzip elyxer-
\emph on
[version]
\emph default
.zip
\end_layout

\begin_layout Standard
A directory called 
\family typewriter
elyxer
\family default
 should appear, where the main executable file 
\family typewriter
elyxer.py
\family default
 resides.
\end_layout

\begin_layout Subsubsection*
Using the Installer
\end_layout

\begin_layout Standard
An installer is provided in the root directory, called 
\family typewriter
install.py
\family default
; it is the recommended way to install eLyXer.
 To run it just type in a console as root:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
#
\color inherit
 python install.py
\end_layout

\begin_layout Standard
On Windows you can type (as a regular user):
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
>
\color inherit
 python.exe install.py
\end_layout

\begin_layout Standard
In any case, the script will look at your Python version and decide if it
 can install eLyXer as a Python module or as a binary.
 By default it will install eLyXer as a binary, so you can check if it was
 installed successfully:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 elyxer.py --help
\end_layout

\begin_layout Standard
If it is possible (i.e.
 if your Python version is above 2.3), it will also install eLyXer as a module:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 python -m elyxer --help
\end_layout

\begin_layout Standard
In any case, a brief help text and the list of command line options should
 appear.
\end_layout

\begin_layout Standard
In what follows we will assume that eLyXer has been installed as a binary,
 except where stated; substitute 
\family typewriter
"elyxer.py"
\family default
 with 
\family typewriter
"python -m elyxer"
\family default
 if your system has eLyXer as a module and you want to use it.
\end_layout

\begin_layout Standard
The installer will also copy existing translation files to your hard drive
 so that they can be used from within eLyXer for internationalization.
\end_layout

\begin_layout Subsubsection*
Prepackaged Versions
\end_layout

\begin_layout Standard
The easiest way to install eLyXer is if someone has prepackaged it for your
 system.
 Some Linux distributions include eLyXer: 
\begin_inset CommandInset href
LatexCommand href
name "Debian squeeze"
target "http://packages.debian.org/squeeze/elyxer"

\end_inset

 and 
\begin_inset CommandInset href
LatexCommand href
name "Ubuntu Lucid"
target "http://packages.ubuntu.com/lucid/elyxer"

\end_inset

.
 In this case eLyXer needs to be run as 
\family typewriter
"elyxer"
\family default
:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 elyxer --help
\end_layout

\begin_layout Standard
Another way is with the LyX installer: the 
\begin_inset CommandInset href
LatexCommand href
name "alternate LyX installer"
target "http://wiki.lyx.org/Windows/LyXWinInstaller"

\end_inset

 includes eLyXer in the default installation.
 See 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:LyX-Integration"

\end_inset

 for LyX integration.
\end_layout

\begin_layout Subsubsection*
Manual Installation
\end_layout

\begin_layout Standard
If the installer did not work for you, you can manually install it as a
 module.
 On Linux go to the elyxer directory and type, as root:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
#
\color inherit
 python setup.py install
\end_layout

\begin_layout Standard
On Windows just type:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
>
\color inherit
 python.exe setup.py install
\end_layout

\begin_layout Standard
On Mac OS X you can use sudo to have permission:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
%
\color inherit
 sudo python setup.py install
\end_layout

\begin_layout Standard
Now you can run eLyXer as a Python module:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 python -m elyxer --help
\end_layout

\begin_layout Standard
The list of command line options should appear.
 You can also manually copy the file 
\family typewriter
elyxer.py
\family default
 to a directory found in the execution path (for instance, 
\family typewriter
/usr/bin
\family default
 on Linux or 
\family typewriter
c:
\backslash
windows
\backslash
system32
\family default
 on Windows).
\end_layout

\begin_layout Subsection
Test Drive
\end_layout

\begin_layout Standard
Now you may want to try to convert the user guide:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 elyxer.py --css lyx.css --title "eLyXer User Guide" docs/userguide.lyx docs/usergu
ide2.html
\end_layout

\begin_layout Standard
or, to run eLyXer as a Python module:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 python -m elyxer --css lyx.css --title "eLyXer User Guide" docs/userguide.lyx
 docs/userguide2.html
\end_layout

\begin_layout Standard
It should generate a working web page identical to the one distributed:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 diff docs/userguide.html docs/userguide2.html
\end_layout

\begin_layout Standard
The typical output will contain just the changed lines, which in this case
 should be only the header with the file creation date.
 An example is shown on listing 
\begin_inset CommandInset ref
LatexCommand ref
reference "alg:diff"

\end_inset

.
\end_layout

\begin_layout Standard
\begin_inset Float algorithm
wide false
sideways false
status open

\begin_layout Quotation

\family typewriter
7c7
\end_layout

\begin_layout Quotation

\family typewriter
< <meta name="create-date" content="2009-09-11"/>
\end_layout

\begin_layout Quotation

\family typewriter
---
\end_layout

\begin_layout Quotation

\family typewriter
> <meta name="create-date" content="2009-09-12"/>
\end_layout

\begin_layout Plain Layout
\begin_inset Caption

\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "alg:diff"

\end_inset

Example of 
\family typewriter
diff
\family default
 output for functionally identical HTML files.
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
If nothing else appears (i.e.
 both files are functionally equal) then everything is working fine.
 If you have 
\family typewriter
bash
\family default
 installed, to test that everything 
\emph on
really
\emph default
 works fine you can just run the included tests:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 ./run-tests
\end_layout

\begin_layout Standard
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 
\family typewriter
diff
\family default
 to show differences between two files.
\end_layout

\begin_layout Subsection
Usage
\end_layout

\begin_layout Standard
eLyXer is a standalone command line tool.
 It can be invoked from the command line as:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 elyxer.py [options] [source file] [destination file]
\end_layout

\begin_layout Standard
or, again for the module:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 python -m elyxer [options] [source file] [destination file]
\end_layout

\begin_layout Standard
If the source file is omitted then 
\family typewriter
STDIN
\family default
 is used; likewise, if no destination file is specified eLyXer will output
 to 
\family typewriter
STDOUT
\family default
.
 This allows its use in pipes and other flexible configurations.
 Some examples:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 elyxer.py file.lyx file.html
\end_layout

\begin_layout Standard
converts 
\family typewriter
file.lyx
\family default
 to 
\family typewriter
file.html
\family default
.
 Debug messages are shown.
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 cat file.lyx | elyxer.py > file.html
\end_layout

\begin_layout Standard
converts 
\family typewriter
file.lyx
\family default
 to 
\family typewriter
file.html
\family default
, as before.
 This time debug messages are not shown.
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 elyxer.py file.lyx | grep "<blockquote>" | wc
\end_layout

\begin_layout Standard
counts all blockquote paragraphs.
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 elyxer.py file.lyx | wget --no-check-certificate --spider -nv -F -i -
\end_layout

\begin_layout Standard
checks all external links in a document recursively.
 (Local links will appear as unresolved, but they can be ignored.)
\end_layout

\begin_layout Subsection
Image Processing
\end_layout

\begin_layout Standard
HTML pages do not contain images, as PDF documents; rather they have pointers
 to image locations on disk.
 (Luckily LyX documents are the same in this respect.) eLyXer will generate
 pages that point to the same locations as the original images, when they
 are PNG images.
 Other image types like Encapsulated PostScript cannot be used directly
 from within pages.
 If the ImageMagick package is installed eLyXer will use the 
\family typewriter
convert
\family default
 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.
\end_layout

\begin_layout Standard
Image location is fragile.
 All images should be placed in the same location (and with the same structure)
 as the original document; and they should all be referenced relatively
 to the current document.
 During conversion from within LyX (in those versions where it is available)
 image locations can be lost.
 Your best bet is to do conversion in place.
\end_layout

\begin_layout Subsection
\begin_inset CommandInset label
LatexCommand label
name "sub:LyX-Integration"

\end_inset

LyX Integration
\end_layout

\begin_layout Standard
If you used the eLyXer installer LyX will automatically detect it after
 reconfiguration.
 Just make sure that you are running LyX 1.6.5 or later, and click on Tools\SpecialChar \menuseparator
Reconfi
gure.
\end_layout

\begin_layout Standard
LyX should be able to detect if eLyXer was installed as a module or as a
 binary, or even if it has been installed from a Linux distribution.
 In any case you can verify that it has been recognized by LyX by opening
 Tools\SpecialChar \menuseparator
Preferences\SpecialChar \ldots{}
, going to External formats\SpecialChar \menuseparator
Converters, and finding the
 converter for 
\begin_inset Quotes eld
\end_inset

LyX -> HTML
\begin_inset Quotes erd
\end_inset

.
 If eLyXer is there, it worked! Now you can convert your documents using
 View\SpecialChar \menuseparator
HTML.
 Otherwise try to reinstall eLyXer from scratch and then reconfigure LyX.
\end_layout

\begin_layout Section
Advanced Use
\end_layout

\begin_layout Standard
There are some advanced uses for eLyXer if you want to extract the most
 of it.
\end_layout

\begin_layout Subsection
Command Line Options
\end_layout

\begin_layout Standard
eLyXer supports a few command line options:
\end_layout

\begin_layout Description

\family typewriter
--help
\family default
: Show command line help.
\end_layout

\begin_layout Description

\family typewriter
--quiet
\family default
: Be quiet and do not output messages (except errors).
 This way you can avoid the comforting 
\begin_inset Quotes eld
\end_inset

Parsing line 1000
\begin_inset Quotes erd
\end_inset

 messages.
 When STDIN or STDOUT are used (e.g.
 in a pipeline) 
\family typewriter
--quiet
\family default
 is always enabled.
\end_layout

\begin_layout Subsubsection*
Advanced Options
\end_layout

\begin_layout Description

\family typewriter
--debug
\family default
: Show debug messages.
 They may help a developer understand your problem.
\end_layout

\begin_layout Description

\family typewriter
--version
\family default
: Show version number and date.
 Use to check which version you are actually running.
\end_layout

\begin_layout Description

\family typewriter
--lyxformat
\family default
: Return the highest LyX version that eLyXer understands.
 This parameter is provided to help with 
\family typewriter
lyx2lyx
\family default
 integration, so that this tool knows if it must convert the file to a lower
 LyX format.
\end_layout

\begin_layout Subsubsection*
Options to Control HTML output
\end_layout

\begin_layout Description

\family typewriter
--title
\begin_inset space ~
\end_inset


\series bold
"
\series default
title
\series bold
"
\family default
\series default
: Change the title of the generated web page.
\end_layout

\begin_layout Description

\family typewriter
--css
\begin_inset space ~
\end_inset


\series bold
"
\series default
new.css
\series bold
"
\family default
\series default
: Change default CSS.
 See section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:CSS"

\end_inset

: CSS.
\end_layout

\begin_layout Description

\family typewriter
--html
\family default
: Generate HTML 4.0 (instead of XHTML).
 The resulting pages should be easier to import from certain word processors.
 See section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:HTML-Code"

\end_inset

: HTML code.
\end_layout

\begin_layout Description

\family typewriter
--unicode
\family default
: Restore full Unicode output.
 Right now switches midspaces to medium mathematical spaces.
 See also section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:HTML-Code"

\end_inset

: HTML code.
\end_layout

\begin_layout Description

\family typewriter
--iso885915
\family default
: Generate a document using ISO-8859-1 encoding.
 Again, see section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:HTML-Code"

\end_inset

: HTML code.
\end_layout

\begin_layout Description

\family typewriter
--nofooter
\family default
: Omit the footer message 
\begin_inset Quotes eld
\end_inset

Document generated by eLyXer
\begin_inset Quotes erd
\end_inset

 (shown at the bottom).
\end_layout

\begin_layout Subsubsection*
Options to Control image output
\end_layout

\begin_layout Description

\family typewriter
--
\family default
directory
\begin_inset space ~
\end_inset


\family typewriter
\series bold
"
\family default
\series default
images_dir
\family typewriter
\series bold
"
\family default
\series default
: Look for images in the directory specified.
\end_layout

\begin_layout Description

\family typewriter
--
\family default
destdirectory
\begin_inset space ~
\end_inset


\family typewriter
\series bold
"
\family default
\series default
dest_dir
\family typewriter
\series bold
"
\family default
\series default
: Converted images will end up into this directory.
\end_layout

\begin_layout Description

\family typewriter
--forceformat
\begin_inset space ~
\end_inset

".extension"
\family default
: Force the format implied by the extension (e.g.
 
\family typewriter
".jpg"
\family default
 for JPEG) for output images.
\end_layout

\begin_layout Description

\family typewriter
--converter
\begin_inset space ~
\end_inset


\series bold
"program"
\family default
\series default
:
\family typewriter
 
\family default
Use the given program to convert images.
 Right now only two converters are supported: 
\family typewriter
\series bold
imagemagick
\family default
\series default
 (default) and 
\family typewriter
\series bold
inkscape
\family default
\series default
.
 The latter chooses Inkscape as the image converter, instead of the default
 ImageMagick.
 Inkscape uses some non-standard extensions so it might be needed to convert
 SVG images to PNG.
\end_layout

\begin_layout Description

\family typewriter
--noconvert
\family default
: Use all images in their original format, do not convert anything.
 Useful e.g.
 for SVG figures.
\end_layout

\begin_layout Subsubsection*
Advanced Options to Control HTML output
\end_layout

\begin_layout Description

\family typewriter
--splitpart
\begin_inset space ~
\end_inset


\series bold
"
\series default
depth
\series bold
"
\family default
\series default
: Split the resulting webpage at the given depth.
 See section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:Segmenting-Pages"

\end_inset

: Segmenting Pages.
\end_layout

\begin_layout Description

\family typewriter
--toc
\family default
: Generate just a table of contents.
 See section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:TOC"

\end_inset

: TOC.
\end_layout

\begin_layout Description

\family typewriter
--target
\begin_inset space ~
\end_inset


\series bold
"
\series default
frame
\series bold
"
\family default
\series default
: Add a 
\family typewriter
target
\family default
 attribute to every link in the generated HTML, making all links point to
 the provided frame.
 Again, see section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:TOC"

\end_inset

: TOC.
\end_layout

\begin_layout Description

\family typewriter
--toctarget
\begin_inset space ~
\end_inset


\series bold
"
\series default
original.html
\series bold
"
\family default
\series default
: Generate a table of contents with links to the original HTML file.
 See section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:TOC"

\end_inset

: TOC.
\end_layout

\begin_layout Description

\family typewriter
--lowmem
\family default
: Activate a low memory mode which does not keep the whole document in memory:
 conversion is done on the fly.
 Keep in mind that some features as the TOC will be missing from the generated
 document.
\end_layout

\begin_layout Description

\family typewriter
--numberfoot
\family default
:
\family typewriter
 
\family default
Label footnotes using numbers, instead of letters.
 Useful when bibliographical references are not numbered and therefore cannot
 be confused with footnotes.
\end_layout

\begin_layout Description

\family typewriter
--raw
\family default
: Generate an HTML page without header or footer.
\end_layout

\begin_layout Description

\family typewriter
--jsmath
\begin_inset space ~
\end_inset


\series bold
"
\series default
URL
\series bold
"
\family default
\series default
: Use the excellent JavaScript library 
\begin_inset CommandInset href
LatexCommand href
name "jsMath"
target "http://www.math.union.edu/locate/jsMath"

\end_inset

 at the given URL to pretty-print mathematical equations.
 See section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:Math"

\end_inset

.
\end_layout

\begin_layout Description

\family typewriter
--mathjax
\begin_inset space ~
\end_inset


\series bold
"
\series default
URL
\series bold
"
\family default
\series default
: Use the promising JavaScript library 
\begin_inset CommandInset href
LatexCommand href
name "MathJax"
target "http://www.mathjax.org/"

\end_inset

 at the given URL to pretty-print mathematical equations.
 See also section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:Math"

\end_inset

.
\end_layout

\begin_layout Description

\family typewriter
--template
\begin_inset space ~
\end_inset


\series bold
"
\series default
file
\series bold
"
\family default
\series default
: Use an HTML template.
 The raw converted document will be placed where 
\family typewriter
<!--$content-->
\family default
 appears in the template.
 Available variables: 
\family typewriter
<!--$content-->
\family default
, 
\family typewriter
<!--$title-->
\family default
, 
\family typewriter
<!--$author-->
\family default
, 
\family typewriter
<!--$encoding-->
\family default
, 
\family typewriter
<!--$css-->
\family default
, 
\family typewriter
<!--$navigation-->
\family default
, 
\family typewriter
<!--$year-->
\family default
, 
\family typewriter
<!--$date-->
\family default
, 
\family typewriter
<!--$datetime-->
\family default
, 
\family typewriter
<!--$version-->
\family default
, 
\family typewriter
<!--$script-->
\family default
, 
\family typewriter
<!--$mathjax-->
\family default
, 
\family typewriter
<!--$jsmath-->
\family default
.
\end_layout

\begin_layout Description

\family typewriter
--copyright
\family default
: Include a copyright notice at the bottom.
\end_layout

\begin_layout Description

\family typewriter
--nocopy
\family default

\begin_inset space ~
\end_inset

(deprecated): No effect since the copyright notice is now optional, maintained
 for backwards compatibility.
\end_layout

\begin_layout Standard
When an option accepts an argument it can be added after a space as 
\family typewriter
--target
\begin_inset space ~
\end_inset


\series bold
"
\series default
frame
\series bold
"
\family default
\series default
, or with an equals sign as in 
\family typewriter
--target=
\series bold
"
\series default
frame
\series bold
"
\family default
\series default
.
 The quotes are optional and can be useful if your arguments include e.g.
 spaces.
\end_layout

\begin_layout Subsubsection*
Adding Options In LyX
\end_layout

\begin_layout Standard
To add one of these options so that it is used from within LyX, you have
 to modify the converter line.
 To this effect open Tools\SpecialChar \menuseparator
Preferences\SpecialChar \ldots{}
, go to External formats\SpecialChar \menuseparator
Converters,
 find the converter for 
\begin_inset Quotes eld
\end_inset

LyX -> HTML
\begin_inset Quotes erd
\end_inset

 and edit the converter line.
 It should read something like this:
\end_layout

\begin_layout LyX-Code

\family typewriter
python -m elyxer --directory $$r $$i $$o
\end_layout

\begin_layout Standard
(By default LyX will prefer to use eLyXer as a module.) If you want to generate
 pure HTML instead of XHTML, change the line to:
\end_layout

\begin_layout LyX-Code

\family typewriter
python -m elyxer 
\family default
\series bold
--html
\family typewriter
\series default
 --directory $$r $$i $$o
\end_layout

\begin_layout Standard
And so on.
 If eLyXer was only installed as a binary the original line will be:
\end_layout

\begin_layout LyX-Code

\family typewriter
elyxer.py --directory $$r $$i $$o
\end_layout

\begin_layout Standard
So you will have to change it accordingly.
 Figure 1 shows what to do to add the 
\family typewriter
--html
\family default
 option when eLyXer is installed as a module: after editing the line and
 adding the new option, click on 
\begin_inset Quotes eld
\end_inset

Modify
\begin_inset Quotes erd
\end_inset

 and then 
\begin_inset Quotes eld
\end_inset

Save
\begin_inset Quotes erd
\end_inset

 or 
\begin_inset Quotes eld
\end_inset

Apply
\begin_inset Quotes erd
\end_inset

 the changes.
\begin_inset Marginal
status open

\begin_layout Plain Layout
You should never remove the 
\family typewriter
$$i $$o
\family default
 at the end, since it is what tells eLyXer where to find the input and output
 files.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Plain Layout
\align center
\begin_inset Graphics
	filename converters.png

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption

\begin_layout Plain Layout
eLyXer converter in LyX 1.6.5.
\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\begin_layout Standard
LyX 1.6.5 supports a new 
\begin_inset Quotes eld
\end_inset

extra flag
\begin_inset Quotes erd
\end_inset

 line; however, at this moment it does not work with eLyXer.
\end_layout

\begin_layout Subsection
CSS
\begin_inset CommandInset label
LatexCommand label
name "sub:CSS"

\end_inset


\end_layout

\begin_layout Standard
HTML output, as generated, can be a bit crude.
 Some CSS wizardry can go a long way to make eLyXer output look nicer.
\end_layout

\begin_layout Standard
eLyXer tags most elements with the type so you can later modify them using
 a CSS.
 The HTML header reads like listing 
\begin_inset CommandInset ref
LatexCommand ref
reference "alg:CSS"

\end_inset

, so the default remote CSS file is used.
\end_layout

\begin_layout Standard
\begin_inset Float algorithm
wide false
sideways false
status open

\begin_layout Quotation

\family typewriter
<head>
\end_layout

\begin_layout Quotation

\family typewriter
<title>Your title here</title>
\end_layout

\begin_layout Quotation

\family typewriter
\series bold
<link rel="stylesheet" href="http://www.nongnu.org/elyxer/lyx.css" type="text/css"
 media="screen"/>
\end_layout

\begin_layout Quotation

\family typewriter
</head>
\end_layout

\begin_layout Plain Layout
\begin_inset Caption

\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "alg:CSS"

\end_inset

CSS link automatically added to HTML
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
This sample CSS file is published on nongnu.org and distributed along with
 the scripts, 
\family typewriter
docs/lyx.css
\family default
.
 (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 
\family typewriter
lyx.css
\family default
 on nongnu.org, and all documents using it automatically appear with the
 changes.)
\end_layout

\begin_layout Standard
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 
\family typewriter
custom.css
\family default
), and customize as needed.
 Then run 
\family typewriter
elyxer.py
\family default
 with the following option:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 elyxer.py --css=custom.css document.lyx page.html
\end_layout

\begin_layout Standard
This will make the generated 
\family typewriter
page.html
\family default
 use your 
\family typewriter
custom.css
\family default
 file.
 The 
\family typewriter
`='
\family default
 sign between the constant 
\family typewriter
`--css'
\family default
 and the name of the CSS file is optional.
\end_layout

\begin_layout Subsection
Title
\end_layout

\begin_layout Standard
By default the generated web pages have the title 
\begin_inset Quotes eld
\end_inset

Converted Document
\begin_inset Quotes erd
\end_inset

.
 If a PDF title is found then it is used instead.
 The proper LyX title (a paragraph of type 
\begin_inset Quotes eld
\end_inset

Title
\begin_inset Quotes erd
\end_inset

 embedded in the text) will also be used if found.
 But when 
\family typewriter
--lowmem
\family default
 is in use eLyXer does not try to get the proper 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 all the
 document and another to output the web page, and 
\family typewriter
--lowmem
\family default
 implies on-the-fly conversion to save memory.
\end_layout

\begin_layout Standard
You can change the title of the generated web page with the 
\family typewriter
--title
\family default
 option:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 elyxer.py --title "My Beautiful Document" document.lyx page.html
\end_layout

\begin_layout Subsection
Table Of Contents
\begin_inset CommandInset label
LatexCommand label
name "sub:TOC"

\end_inset


\end_layout

\begin_layout Standard
A table of contents (or TOC) can be generated for every converted LyX document.
 You can optionally also add a target frame to every link.
 The trick is to combine both options to generate a TOC that links to the
 original document on a different frame.
 For example, if the original page is called 
\family typewriter
page.html
\family default
 and you generated it with this command:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 elyxer.py document.lyx page.html
\end_layout

\begin_layout Standard
you can generate the TOC linking to this page, and at the same time point
 it to frame 
\family typewriter
contents
\family default
:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 elyxer.py --toc --toctarget page.html --target contents document.lyx page-toc.html
\end_layout

\begin_layout Standard
Then you can put it all together with a simple frameset generated manually.
 Just remember to place the original document in the frame called 
\family typewriter
contents
\family default
.
\end_layout

\begin_layout Standard
\begin_inset Float algorithm
wide false
sideways false
status open

\begin_layout Plain Layout

\family typewriter
<html>
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space ~
\end_inset


\begin_inset space ~
\end_inset

<frameset cols="30%,70%">
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space ~
\end_inset


\begin_inset space ~
\end_inset


\begin_inset space ~
\end_inset


\begin_inset space ~
\end_inset

<frame name="toc" src="page-toc.html" />
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space ~
\end_inset


\begin_inset space ~
\end_inset


\begin_inset space ~
\end_inset


\begin_inset space ~
\end_inset

<frame name="contents" src="page.html" />
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space ~
\end_inset


\begin_inset space ~
\end_inset

</frameset>
\end_layout

\begin_layout Plain Layout

\family typewriter
</html>
\end_layout

\begin_layout Plain Layout
\begin_inset Caption

\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "alg:frameset"

\end_inset

An example frameset for TOC navegation
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
TOC generation accepts the same options as normal document conversion.
 For example, if you follow these instructions literally you will notice
 that the TOC has very wide margins and looks a bit weird; that is because
 it is using the default CSS.
 A special CSS file for TOC files is provided in 
\family typewriter
docs/toc.css
\family default
, so better results should be obtained with the 
\family typewriter
--css
\family default
 option:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 elyxer.py --toc --toctarget page.html --css docs/toc.css --target contents
 document.lyx page-toc.html
\end_layout

\begin_layout Standard
With a little bit of practice you will be able to generate useful (and nice
 looking) TOC files.
 You can see an example for the 
\begin_inset CommandInset href
LatexCommand href
name "user guide"
target "userguide-frameset.html"

\end_inset

 (if you are not already looking at it).
\end_layout

\begin_layout Subsection
Segmenting Pages
\begin_inset CommandInset label
LatexCommand label
name "sub:Segmenting-Pages"

\end_inset


\end_layout

\begin_layout Standard
Quite often you don't want a huge monolithic page, but a set of linked pages.
 To do so you can use the 
\family typewriter
--splitpart
\family default
 option, specifying the level at which eLyXer should split pages.
 For instance:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 elyxer.py --splitpart 1 document.lyx output.html
\end_layout

\begin_layout Standard
will split 
\family typewriter
document.lyx
\family default
 into pages at level 1, using 
\family typewriter
output.html
\family default
 as the root page.
 Each page will get a number that starts with 
\family typewriter
output
\family default
 and ends with 
\family typewriter
.html
\family default
, with a suffix that depends on the page -- 
\family typewriter
output-2.html
\family default
 will correspond to the second split part.
\end_layout

\begin_layout Standard
The level corresponding to 1 depends on the document class: books will be
 split at chapters, but articles will get a section per page.
 And so on with lower levels.
\end_layout

\begin_layout Subsection
HTML Code
\begin_inset CommandInset label
LatexCommand label
name "sub:HTML-Code"

\end_inset


\end_layout

\begin_layout Standard
The HTML code generated is technically XHTML Transitional, version 1.0 
\begin_inset CommandInset citation
LatexCommand cite
key "xhtml"

\end_inset

, 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:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 elyxer.py --html document.lyx page-to-import.html
\end_layout

\begin_layout Standard
Again, technically the code generated is HTML 4.01 Transitional 
\begin_inset CommandInset citation
LatexCommand cite
key "html-401"

\end_inset

 using UTF-8 encoding.
 Both versions should pass the W3C tests 
\begin_inset CommandInset citation
LatexCommand cite
key "w3c-validator"

\end_inset

.
 If your particular web page doesn't pass the tests, then it is a bug and
 it will be treated as such.
\end_layout

\begin_layout Standard
The CSS file for eLyXer uses some CSS2 features for math structures (fractions,
 arrays).
 This makes the output incompatible with older browsers; it requires Microsoft
 Internet Explorer 7, Firefox 3, Safari 3 or Chrome 1.
 Check the 
\begin_inset CommandInset href
LatexCommand href
name "Math Showcase"
target "math.html"

\end_inset

 to see if your browser can render eLyXer output correctly.
\end_layout

\begin_layout Subsubsection*
Character Encodings
\end_layout

\begin_layout Standard
For better browser compatibility, medium mathematical spaces are substituted
 in the output with midspaces -- improving the output for some popular browsers.
 If you want your mathematical spaces back, just use the 
\family typewriter
--unicode
\family default
 option:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 elyxer.py --unicode document.lyx page-to-import.html
\end_layout

\begin_layout Standard
Check out the 
\begin_inset CommandInset href
LatexCommand href
name "Math Showcase with Unicode"
target "math-unicode.html"

\end_inset

 to see the results.
 In the future other non-Unicode substitutions might be used.
\end_layout

\begin_layout Standard
In case you want to use the ISO-8859-15 encoding in your generated document,
 you can add the 
\family typewriter
--iso885915
\family default
 option:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 elyxer.py --iso885915 document.lyx page.html
\end_layout

\begin_layout Standard
This will make eLyXer output a document with all non-ASCII characters encoded
 as 
\family typewriter
&nbsp;
\family default
, 
\family typewriter
&#x2005;
\family default
 and so on.
 This encoding is similar to ISO-8859-1, also called Latin-1, but including
 the Euro sign.
 The 
\begin_inset CommandInset href
LatexCommand href
name "Math Showcase (ISO-8859-15 edition)"
target "math-iso885915.html"

\end_inset

 has been generated using this option.
\end_layout

\begin_layout Standard
Both encoding options can be combined with 
\family typewriter
--html
\family default
 at will.
\end_layout

\begin_layout Subsection
Internationalization
\end_layout

\begin_layout Standard
eLyXer is distributed along with a few translation files.
 They are automatically regenerated every time 
\family typewriter
make
\family default
 is run, and reside in the folder 
\family typewriter
po/
\family default
.
 Internationalization is done using GNU 
\family typewriter
gettext
\family default
, so every locale is identified by a two-letter code (such as 
\begin_inset Quotes eld
\end_inset

en
\begin_inset Quotes erd
\end_inset

 for English and 
\begin_inset Quotes eld
\end_inset

es
\begin_inset Quotes erd
\end_inset

 for Spanish).
 There are two kinds of files: the text 
\family typewriter
.po
\family default
 file (which can be found in 
\family typewriter
po/my.po
\family default
 for locale 
\begin_inset Quotes eld
\end_inset

my
\begin_inset Quotes erd
\end_inset

), and the binary 
\family typewriter
.mo
\family default
 file (found in 
\family typewriter
po/my/elyxer.po
\family default
).
\end_layout

\begin_layout Standard
For internationalization to work properly, Linux distributors should take
 all binary 
\family typewriter
.mo
\family default
 files and place them in the directory corresponding to locale files, which
 we will call 
\family typewriter
$localedir
\family default
.
 As 
\begin_inset CommandInset href
LatexCommand href
name "the Python gettext page"
target "http://docs.python.org/library/gettext.html"

\end_inset

 explains, this is distribution-dependent: for example on Debian 
\family typewriter
$localedir
\family default
 is 
\family typewriter
/usr/share/locale
\family default
, so for locale 
\begin_inset Quotes eld
\end_inset

es
\begin_inset Quotes erd
\end_inset

 the correct route would be
\end_layout

\begin_layout LyX-Code

\family typewriter
/usr/share/locale/es/LC_MESSAGES/elyxer.mo
\end_layout

\begin_layout Standard
Windows distributors on the other hand should place files in 
\family typewriter
%PYTHONHOME%
\backslash
share
\backslash
locale
\family default
, for example for locale 
\begin_inset Quotes eld
\end_inset

es
\begin_inset Quotes erd
\end_inset

 on a machine where Python is in 
\family typewriter
C:
\backslash
python
\family default
:
\end_layout

\begin_layout LyX-Code

\family typewriter
C:
\backslash
python
\backslash
share
\backslash
locale
\backslash
es
\backslash
LC_MESSAGES
\backslash
elyxer.mo
\end_layout

\begin_layout Standard
To generate a new translation file (we will use 
\begin_inset Quotes eld
\end_inset

my
\begin_inset Quotes erd
\end_inset

 as an example locale here, corresponding to Burmese): you need to have
 the GNU 
\family typewriter
gettext
\family default
 package installed.
 Then go to the directory where elyxer.pot resides:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 cd src/conf
\end_layout

\begin_layout Standard
and generate a 
\family typewriter
.po
\family default
 file for your locale:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 msginit --output-file=my.po --locale=my
\end_layout

\begin_layout Standard
Then move the file to the 
\family typewriter
po/
\family default
 directory:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 mv my.po ../../po/
\end_layout

\begin_layout Standard
and start translating it to Burmese! Once you are done run make from the
 root directory:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 ./make
\end_layout

\begin_layout Standard
and it will generate the file 
\family typewriter
po/my/elyxer.mo
\family default
.
 Finally, place this file in
\end_layout

\begin_layout LyX-Code

\family typewriter
$localedir/my/LC_MESSAGES/elyxer.mo
\end_layout

\begin_layout Standard
and you are done.
\end_layout

\begin_layout Subsection
Math
\begin_inset CommandInset label
LatexCommand label
name "sub:Math"

\end_inset


\end_layout

\begin_layout Standard
Math equations are an important part of what takes LyX apart from other
 editors, since it supports the full LaTeX feature set -- that is, about
 everything under the sun.
 Unfortunately, math support is hard to get right.
 Many developers are focusing on MathML, but at the time of this writing
 (Q2 2010) support on some common browsers is still missing.
\end_layout

\begin_layout Standard
eLyXer follows its usual minimalistic approach and doesn't try to be everything
 to everybody -- instead, it supports out of the box a set of usual constructs
 (fraction, square root) and tries to simulate others (binomial, overbrace).
 See the 
\begin_inset CommandInset href
LatexCommand href
name "Math showcase"
target "math.html"

\end_inset

 for yourself and learn what eLyXer supports and what not.
\end_layout

\begin_layout Standard
For more sophisticated math equations there are a couple of advanced features.
\end_layout

\begin_layout Subsubsection*
jsMath
\end_layout

\begin_layout Standard
The first is to use 
\begin_inset CommandInset href
LatexCommand href
name "jsMath"
target "http://www.math.union.edu/~dpvc/jsMath/welcome.html"

\end_inset

, for which you have to run eLyXer with the option 
\family typewriter
--jsmath
\family default
:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 elyxer.py --jsmath jsMath/ math.lyx math-jsmath.html
\end_layout

\begin_layout Standard
It uses the given URL (in this case the relative URL 
\family typewriter
jsMath/
\family default
) to load the required JavaScript files and start rendering.
 Unfortunately, all JavaScript code has to be loaded from the same domain
 as the main document, so if you wish to use this method you will have to
 host jsMath on your site.
 See the 
\begin_inset CommandInset href
LatexCommand href
name "Math showcase (jsMath edition)"
target "math-jsmath.html"

\end_inset

 to see how jsMath improves (or deteriorates) the picture for you.
\end_layout

\begin_layout Subsubsection*
MathJax
\end_layout

\begin_layout Standard
Another possibility is to use 
\begin_inset CommandInset href
LatexCommand href
name "MathJax"
target "http://www.mathjax.org/"

\end_inset

, which is just as simple with the option 
\family typewriter
--mathjax
\family default
:
\end_layout

\begin_layout LyX-Code

\family typewriter
\color blue
$
\color inherit
 elyxer.py --mathjax MathJax/ math.lyx math-jsmath.html
\end_layout

\begin_layout Standard
This option also uses the given URL (now 
\family typewriter
MathJax/
\family default
) to load MathJax from and set it up.
 Although some code needs to be hosted on the same site as the pages, MathJax
 uses a feature called web-fonts which can be downloaded from a public server;
 this is quite easier to host.
 See the 
\begin_inset CommandInset href
LatexCommand href
name "Math showcase (MathJax edition)"
target "math-mathjax.html"

\end_inset

 to see how MathJax fares with eLyXer.
 Keep in mind that MathJax is still prerelease quality; it should improve
 greatly during 2010.
\end_layout

\begin_layout Subsubsection*
Client-side Rendering
\end_layout

\begin_layout Standard
Something to note is that both jsMath and MathJax are JavaScript libraries;
 all rendering is done client-side by the user's browser.
 This has quite a few advantages:
\end_layout

\begin_layout Itemize
Math processing on the server is quite light; equations are basically surrounded
 by a special tag and left in TeX form.
\end_layout

\begin_layout Itemize
For developers: integration of these libraries is very easy.
 It took just a few days to integrate both libraries with eLyXer.
\end_layout

\begin_layout Itemize
Both libraries (especially MathJax) are improving all the time thanks to
 the efforts of Davide P.
 Cervone and the rest of the developer team; eLyXer and its users reap the
 benefits readily.
\end_layout

\begin_layout Itemize
The client browser already knows its abilities, and can choose the rendering
 method it considers to be the best.
 MathJax can even choose between MathML and HTML+CSS 
\emph on
at page rendering time
\emph default
, showing MathML on fancier browsers and simpler HTML where it is not available.
\end_layout

\begin_layout Standard
It also brings some disadvantages:
\end_layout

\begin_layout Itemize
JavaScript code can only be loaded from the server originating the page.
 This means that you cannot host your pages e.g.
 at www.myserver.com and MathJax at www.mymathjaxserver.com.
\end_layout

\begin_layout Itemize
As a consequence, everyone publishing eLyXer pages converted with 
\family typewriter
--mathjax
\family default
 needs to also host the code for MathJax, and the same for jsMath.
 (Web fonts used in MathJax can at least be hosted elsewhere, so publishers
 do not need to also host the fonts package, but this hasn't still been
 used in eLyXer.)
\end_layout

\begin_layout Itemize
And of course it takes some time to render everything on the client, which
 can degrade the user experience on older machines.
\end_layout

\begin_layout Standard
Publishers should carefully consider pros and cons before deciding what
 to use.
\end_layout

\begin_layout Section
Work in Progress
\end_layout

\begin_layout Standard
As you can see eLyXer is a mature and tried package, but it has some rough
 edges.
\end_layout

\begin_layout Subsection
Known Issues
\end_layout

\begin_layout Standard
The following issues (including bugs and missing features) are acknowledged.
 Some of them should be solved soon; others may take longer.
\end_layout

\begin_layout Enumerate
On Mac OS X the output of a message with Unicode characters may cause an
 error.
 Workaround: run 
\family typewriter
elyxer.py
\family default
 with the 
\family typewriter
--quiet
\family default
 option.
\end_layout

\begin_layout Enumerate
Some phonetic alphabet symbols are not well supported -- if generated with
 LyX they only appear in a different color: 
\begin_inset Formula $\text{\textipa{[sample]}}$
\end_inset

.
 
\begin_inset Note Note
status open

\begin_layout Plain Layout
This happens only in the HTML file converted with eLyXer, not from within
 LyX.
\end_layout

\end_inset


\begin_inset Note Comment
status open

\begin_layout Plain Layout
By the way, the previous note (and this one) should not appear on the HTML.
\end_layout

\end_inset


\end_layout

\begin_layout Enumerate
Multi-column layouts are lost.
 This one is almost impossible to get right in CSS, so there are no plans
 to even try.
\end_layout

\begin_layout Enumerate
Many BibTeX styles are missing.
 (They are quite trivial to add though.)
\end_layout

\begin_layout Enumerate
ERT (bare TeX code) is ignored.
\end_layout

\begin_layout Enumerate
Many AMS environments (like 
\family typewriter
alignat
\family default
, 
\family typewriter
gather
\family default
\SpecialChar \ldots{}
) are not working or look strange -- some non-AMS environments too.
\end_layout

\begin_layout Enumerate
Images are never scaled above their nominal resolution.
 This is seldom needed if at all, so there are no plans to change it; if
 people really need the feature just let the author know so it can be added
 as an option.
\end_layout

\begin_layout Subsection
Wish List
\begin_inset CommandInset label
LatexCommand label
name "sub:Wish-List"

\end_inset


\end_layout

\begin_layout Standard
The following features have been requested by users; specific people are
 referenced by a couple of initials so they can recognize themselves while
 keeping some anonymity.
 (If you prefer that your initials do not to appear here at all just let
 me know.)
\end_layout

\begin_layout Standard
\begin_inset Tabular
<lyxtabular version="3" rows="13" columns="4">
<features>
<column alignment="left" valignment="top" width="0">
<column alignment="center" valignment="top" width="0">
<column alignment="center" valignment="top" width="0">
<column alignment="center" valignment="top" width="0">
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Feature
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Date
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Users
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Status
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Option for footnotes at the end of each section
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
2010-09-23
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
MJ
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Queued
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
EPUB output format (
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:EPUB-output-format"

\end_inset

)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
2010-09-23
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
MJ
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Too complex
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Option for footnotes at the margin
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
2010-09-21
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
A
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Queued
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Understand 
\backslash
setcounter{section}{1}
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
2010-05-15
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
JB
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Queued
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Output SVG as 
\family typewriter
<img>
\family default
 tags (
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:Output-SVG-as"

\end_inset

)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
2010-09-22
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
YG
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Pending
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Render change tracking: "Show changes in output"
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
2010-09-18
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
YG
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Queued
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family roman
\series medium
\shape up
\size normal
\emph off
\bar no
\noun off
\color none
Option to turn off title prefixes in TOC
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family roman
\series medium
\shape up
\size normal
\emph off
\bar no
\noun off
\color none
2010-07-10
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
YG
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\family roman
\series medium
\shape up
\size normal
\emph off
\bar no
\noun off
\color none
Queued
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Use BibLaTeX with eLyXer
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
2010-09-14
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
PJ, WE
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Queued
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Add more controls for image conversion (
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:More-controls-for"

\end_inset

)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
2010-10-02
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
WE
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Queued
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Support for format 401 (Insert Horizontal Line)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
2010-10-06
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
US
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Pending
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Parse contents of ERTs
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
2010-10-06
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
US
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Too complex
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Correct scaling of tables with relative sizes (e.g.
 
\family typewriter
%col
\family default
)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
2010-10-09
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
US
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Pending
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Standard
Some features require further explanations.
\end_layout

\begin_layout Subsubsection*
EPUB output format
\begin_inset CommandInset label
LatexCommand label
name "sub:EPUB-output-format"

\end_inset


\end_layout

\begin_layout Standard
The EPUB management package 
\begin_inset CommandInset href
LatexCommand href
name "calibre"
target "http://calibre-ebook.com/user_manual/conversion.html"

\end_inset

 does not output valid EPUB documents when converted from eLyXer HTML files,
 at least according to the 
\begin_inset CommandInset href
LatexCommand href
name "Threepress validator"
target "http://threepress.org/document/epub-validate"

\end_inset

.
\end_layout

\begin_layout Standard
This is a complex feature request; calibre does minimal formatting in its
 EPUB conversion, so making it generate valid EPUB documents requires changing
 deeply how eLyXer outputs XHTML.
 Lots of help would be needed to get this working.
\end_layout

\begin_layout Subsubsection*
Output SVG as 
\family typewriter
<img>
\family default
 tags
\begin_inset CommandInset label
LatexCommand label
name "sub:Output-SVG-as"

\end_inset


\end_layout

\begin_layout Standard
This feature would be most welcome from the part of the author.
 Unfortunately, Firefox alone from the major browsers refuses to render
 
\family typewriter
<img>
\family default
 tags correctly for SVG.
 According to 
\begin_inset CommandInset href
LatexCommand href
name "bug #276431"
target "https://bugzilla.mozilla.org/show_bug.cgi?id=276431"

\end_inset

, this was fixed on 2010-09-08, so the next version should do the right
 thing; at that point this feature will be queued for inclusion.
\end_layout

\begin_layout Standard
You can check out how your browser does with SVG images with this 
\begin_inset CommandInset href
LatexCommand href
name "SVG test page"
target "svg/svg-test.html"

\end_inset

.
\end_layout

\begin_layout Subsubsection*
More controls for image conversion
\begin_inset CommandInset label
LatexCommand label
name "sub:More-controls-for"

\end_inset


\end_layout

\begin_layout Standard
eLyXer uses ImageMagick to convert images.
 Some images (in EPS format, for example) do have blank borders, or they
 come in varied sizes.
 It would be nice to remove blank borders and have some kind of unified
 resolution in the conversion, which would be passed to ImageMagick.
\end_layout

\begin_layout Subsection
Contact Information
\end_layout

\begin_layout Standard
If your problem does not appear in the above list, please let the author
 know; you can find him at 
\begin_inset CommandInset href
LatexCommand href
name "elyxer@gmail.com"
target "mailto:elyxer@gmail.com"
type "mailto:"

\end_inset

.
 In the words of Rich Talley: 
\begin_inset Quotes eld
\end_inset

the tool's author really likes getting challenging documents and making
 eLyXer work with them
\begin_inset Quotes erd
\end_inset

.
 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.
\end_layout

\begin_layout Standard
You can also join the 
\begin_inset CommandInset href
LatexCommand href
name "mailing list"
target "http://lists.nongnu.org/mailman/listinfo/elyxer-users"

\end_inset

 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 
\begin_inset CommandInset href
LatexCommand href
name "Savannah page"
target "https://savannah.nongnu.org/bugs/?func=additem&group=elyxer"

\end_inset

.
\end_layout

\begin_layout Subsection
Extending eLyXer
\end_layout

\begin_layout Standard
eLyXer should now support most LyX features; but 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.
\end_layout

\begin_layout Standard
eLyXer is written in Python so that it does not need to be compiled; its
 code is interpreted on the fly.
 See the accompanying 
\begin_inset CommandInset href
LatexCommand href
name "developer guide"
target "devguide.html"

\end_inset

 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.
\end_layout

\begin_layout Section
FAQ
\end_layout

\begin_layout Description
Q: What versions of LyX are supported?
\end_layout

\begin_layout Description
A: The tool is slowly improving; it now should work with LyX versions 1.5.5
 to 1.6.5.
 It has been tested on Linux, Mac OS X and Windows.
\end_layout

\begin_layout Description
Q: There are indeed 
\emph on
a ton
\emph default
 of similar projects over the web.
 Why add another one?
\end_layout

\begin_layout Description
A: The four tools supported by LyX (tex4ht, hevea, tth and latex2html) gave
 inferior results a couple of years ago, and were quite inflexible.
 The author found the need for a good converter, while at the same time
 acknowledging the difficulty of the problem.
\end_layout

\begin_layout Description
Q: Speaking of that: why build a LyX to HTML converter, instead of a more
 generic LaTeX to HTML converter?
\end_layout

\begin_layout Description
A: The problem space is quite simplified, and therefore progress is much
 faster.
 To make it even easier eLyXer has historically centered on the subset of
 LyX functionality that is useful to most LyX users, leaving the rest for
 a later stage.
 Nowadays eLyXer aims to support the full LyX feature set.
\end_layout

\begin_layout Description
Q: What can we expect from the tool in the future?
\end_layout

\begin_layout Description
A: eLyXer should fulfill the needs of 99% of LyX users in the short term.
 It has also learned a couple of tricks of its own such as page segmenting.
 Eventually it could be distributed along with LyX as part of the standard
 installer.
\end_layout

\begin_layout Description
Q: Why did you leave out my favorite feature 
\emph on
<insert random LyX command here>
\emph default
?
\end_layout

\begin_layout Description
A: In short, because nobody asked for it.
 Every feature which has been requested (either to me personally or to the
 list) has been tended to, unless it was too far out or I forgot about it.
 At this point of development every missing LyX feature will be considered
 a high priority item for the next version, if at all possible to implement.
\end_layout

\begin_layout Description
Q: My document changed its appearance without my intervention.
 Was it black magic, elves or what?
\end_layout

\begin_layout Description
A: It probably uses the online CSS file, which is regularly updated.
 See section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:CSS"

\end_inset

 for details.
\end_layout

\begin_layout Description
Q: Why use an online CSS, instead of placing the CSS file in the same directory
 as the converted file?
\end_layout

\begin_layout Description
A: There were pros and cons.
 An online CSS resource allowed me to update it for everyone at the same
 time, but might make it more difficult for people without an internet connectio
n; local CSS files are more flexible but can also be confusing to novice
 users.
 In the end the online solution was preferred, with the 
\family typewriter
--css
\family default
 option as a fallback.
 
\end_layout

\begin_layout Description
Q: My jsMath (MathJax) pages are not rendering correctly; equations are
 silently ignored.
\end_layout

\begin_layout Description
A: Check that jsMath (MathJax) is installed on the same server as your pages;
 for security reasons the browser's 
\begin_inset Quotes eld
\end_inset

same-origin
\begin_inset Quotes erd
\end_inset

 policy mandates that JavaScript can only be loaded from the same site as
 the original page.
 Also make sure that JavaScript is enabled on the browser.
\end_layout

\begin_layout Description
Q: I found a bug, what should I do?
\end_layout

\begin_layout Description
A: Just send it to the author at 
\begin_inset CommandInset href
LatexCommand href
name "elyxer@gmail.com"
target "mailto:elyxer@gmail.com"
type "mailto:"

\end_inset

.
 You can also report it to the 
\begin_inset CommandInset href
LatexCommand href
name "Savannah interface"
target "https://savannah.nongnu.org/bugs/?func=additem&group=elyxer"

\end_inset

.
\end_layout

\begin_layout Bibliography
\begin_inset CommandInset bibitem
LatexCommand bibitem
key "wordreference-elixir"

\end_inset

WordReference.com: 
\begin_inset Quotes eld
\end_inset

definition of elixir
\begin_inset Quotes erd
\end_inset

, accessed March 2009.
 
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

http://www.wordreference.com/definition/elixir
\end_layout

\end_inset


\end_layout

\begin_layout Bibliography
\begin_inset CommandInset bibitem
LatexCommand bibitem
key "xhtml"

\end_inset

W3C: 
\begin_inset Quotes eld
\end_inset

XHTML™ 1.0 The Extensible HyperText Markup Language (Second Edition)
\begin_inset Quotes erd
\end_inset

, revised 1 August 2002.
 
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

http://www.w3.org/TR/xhtml1/
\end_layout

\end_inset


\end_layout

\begin_layout Bibliography
\begin_inset CommandInset bibitem
LatexCommand bibitem
key "html-401"

\end_inset

W3C: 
\begin_inset Quotes eld
\end_inset

HTML 4.01 Specification
\begin_inset Quotes erd
\end_inset

, 24 December 1999.
 
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

http://www.w3.org/TR/REC-html40/
\end_layout

\end_inset


\end_layout

\begin_layout Bibliography
\begin_inset CommandInset bibitem
LatexCommand bibitem
key "w3c-validator"

\end_inset

W3C: 
\begin_inset Quotes eld
\end_inset

Markup Validation Service
\begin_inset Quotes erd
\end_inset

, accessed March 2009.
 
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

http://validator.w3.org/
\end_layout

\end_inset


\end_layout

\end_body
\end_document
