Making LY X Produce Decent Hyperlinked HTML & PDF Files

As someone who writes for a living I have used a whole slew of word processors and generally haven't been all that happy with any of them. When I write I want to focus on the content, not the presentation. So the whole WYSIWYG generation of word processors left me cold. In fact, I spend most of my time in outline mode in Word. LyX takes a different approach. It focuses on What You See Is What You Mean (WYSIWYM). In other words, it doesn't worry about formating, just content.

When I first reviewed LY X a year ago I decided it was good enough to use (and have done so regularly since) but still painful. With the 1.5.1 release I can revise that review to say that it's only minorly irritating to use LY X but it's good points are so numerous that it's more than worth the pain if you need to deal with large documents, with math formulas or with large bibliographies. And thanks to the efforts of folks like Dr. Richard G. Heck (who has my undying gratitude for fixing HTML generation in LY X) LY X is substantially better at generating HTML.

LY X does have a learning curve and one is well advised to at least read the tutorial (Help->Tutorial). But I believe that the modern versions of LY X have vastly improved over their predecessors and the learning curve is well worth the effort.

Contents

1 Starting a New Document

To start a new document I begin by using File->New From Template and then pointing at the locally saved version of my template file. This file sets a few environmental variables that enable URLs and set a few other things the way I like.

2 Math

TEX, the underlying technology for LY X, was original invented in order to produce beautiful mathematical equations. So as one would expect LY X comes with a fairly nifty equation editor. For example, here's an equation I pulled out of my book on retirement planning:

What's especially nice is that I can enter the TEX formula commands directly into the dialog and LY X will translate the command on the fly to the right graphical representation. But there is also a graphical formula palette available by right clicking on an equation. The only trick I've had to remember is to press command-return when I want to enter multiple equations at one time.

3 Bibliographies

One of the more unpleasant tasks in writing a paper with lots of references is keeping track of those references, linking to citations and making sure the bibliography is properly formatted and ordered. Thankfully there is a great standard called BibTex that handles a lot of the drudgery. The first step to using BibTex is to get a bibliography manager program which can keep track of all the bibliographic entries. For OS X there's BibDesk[Bib(2006)]. It's pretty nifty but I did find perusing its manual worthwhile, especially regarding its AutoFile feature. With AutoFile, BibDesk is designed not only to keep track of reference information but also of the underlying documents being referenced.

To get BibTex references working I double click on the "BibTex Generated Bibliography" icon at the bottom of the new file created from the template and navigate to the .bib file generated by BibDesk. To add actual citations I use Insert->Citation which will list all the citations available in the BibTex file. It's worth pointing out that BibDesk only updates the BibTex file when the File->Save command in BibDesk is used.

One of the issues I've noodled on for a while is how to get decent bibliography entries for Webpages. BibDesk supports URL, Electronic and Webpage styles but I find that they either don't have enough information or require too much information to properly fill out. I now find myself mostly using the "proceedings" style where I put the web page name as the title, a year and then enter the URL. I find this publishes quite nicely.

4 URLs

A real weakness in LY X is its URL handling. There is a special URL dialog but unfortunately it can only produce URLs of the form text /lyx. That is, some text followed by a URL. To get around this I use Evil Red Text (ERT). I create an ERT by pressing the TEX button and then entering information of the form \href{https://www.goland.org}{this URL} which is the command I used to generate this URL.

5 Adding Cross References

TEX supports a very simple type of cross referencing using \ref and \label that allows one to reference anything that has been labeled. These references, especially if set to 'reference', will work in HTML but references always reference the nearest section to the label, they don't link to the actual labeled text. This is fine for printed documents but less than optimal for HTML.

One horrendously painful workaround is to use the \hypertarget{Label}{Text} and \hyperlink{Label}{Text} macros. Both macros are inserted using the TEX button to create ERT. For example, I use \hypertarget{L1}{this text} to link this text to this link that I created using \hyperlink{L1}{this link}.

6 Making Pretty HTML

File->Export->HTML. Thanks to Dr. Heck it's as simple as that.

7 Conclusion

Although LY X isn't necessarily the easiest word processor ever invented it richly rewards the investment to learn it by providing an environment that lets the author focus on the text above all. I really enjoy editing text in LY X even for its various glitches and issues. I also give a hearty thanks to the LY X developers for doing a great job of continually improving LY X.

References

A Appendix – Creating the Template

A.1 Configuring URL Output

The HREF function described above is enabled via a package called hyperref. To enable hyperref and also to set the output behavior so that hyperlinks will be colored when outputted in PDF documents (a useful feature since PDF viewers like Apple's preview do not highlight URLs by default in PDFs) the text below needs to be added to the preamble of the document. Preamble is accessed via Document->Settings->LATEX Preamble

\usepackage{hyperref}

\hypersetup{colorlinks=true, linkcolor=blue, filecolor=blue, pagecolor=blue, urlcolor=blue}

A.2 Configuring BibTex

I added in a BibTex based bibliography by going to the end of the document and using Insert->Lists/TOC->BibTex Bibliography. As described above(3 ) I point the file at the appropriate .bib file. I set the style to "plainnat" because I like how it outputs citations (author's last name + Year) and it also will output URLs listed in the bibliography. I also check "add Bibliography to TOC" so the Bibliography shows up in the table of contents.

A.3 Making Simple Quotes

I think the default quote format in LY X is a bit odd. I prefer simple quotes. To enable this I set Document->Settings->Language->Quote Style->"text".

A.4 Avoiding Problems With Fonts

Leaving the fonts (available via Document->Settings-Fonts) all on default will produce reasonable output. Messing around with the choices can be a bit dicey in terms of generating HTML as there is a problem with some of the fonts generating bizarre ligatures. For example, set Roman to Bera Serif and generate a HTML file that contains the strings "fi" and "fj". The HTML output will invert them, "fi" will come out "fj" and "fj" will come out "fi". If you keep all the fonts on default then all will be well.

B Historical Cruft

Before Dr. Heck fixed LY X it used to be that it wasn't possible to generate HTML from LY X that honored bibliographies. The dance below fixed that problem. It's no longer necessary but I paid a really painful price to figure out the exact right set of commands so I'm keeping a copy here, just in case.

Let's assume that file is called "myfile.tex". I next open a terminal window, navigate to the directory containing myfile.tex and type in the following commands:

latex myfile

bibtex myfile

latex myfile

latex myfile

htlatex myfile xhtml

Notice that the extension ".tex" is not used. Then end result will be a file called myfile.html that will contain a full HTML representation, with a bibliography and will generate gifs for any math formulas.