Introduction.

Readers already familiar with LyX can skip ahead to Section 3 for requirements/usage, Section 4 for supported features, and Section 5 for example modules.

Many educators in technical fields such as physics, engineering, chemistry, etc have prepared course materials using the LaTeX system. Many also find it convenient to create these documents using a free technical word-processor called LyX. The LaTeX format is significantly different from the Connexions XML format, which might dissuade LaTeX enthusiasts from contributing Connexions content.

This module offers a Perl translation script, called lyx2cnx.pl, that directly converts a LyX document to a Connexions XML document. A user should be able to simply type a document in LyX, convert it using lyx2cnx, then import it to Connexions as Plain XML. This module gives instructions for creating Connexions modules using LyX.

Please note that this script is an alpha version. It works well for my authoring habits (see the provided examples), but others may find it buggy. The author appreciates any bug reports. If you have a LyX file that won't convert, please send it to me and I'll try and work out the problem.

Introduction: What is LyX?

LyX is a free, open-source, cross-platform GUI word-processor designed for authoring technical documents, similar to programs like Scientific Word. LyX can create PDF and Postscript output using the popular LaTeX engine for technical typesetting. By itself, LaTeX can be quite complicated. LyX offers the power of LaTeX with the simplicity of a word processor. Versions of LyX are available for Windows, Linux, Unix and Mac OSX platforms and can be downloaded at www.LyX.org.

LyX offers a graphical equation editor, one of the best and easiest in existence. The philosophy of LyX is "What You See is What You Mean" (WYSIWYM), meaning the user focuses on the document's content - equations, figures, sections, etc - and the formatting is handled automatically by the LaTeX engine. This is very similar to the philosophy of Connexions and XML.

LyX is customizable, allowing the user to specify the types of content that are available. This makes it easy to represent the available Connexions content tags within LyX. The user types in blocks of text, choosing the desired content-type using a drop-down menu. There are no tags to worry about.

A primary motivation for using LyX as a front-end for Connexions is to enable offline development of multi-use content. Course materials can be complex and are best developed using offline editing tools. If I go to the trouble of creating a course text, I would like to be able to easily compile professional-quality PDF files of that content. MS Word is one option for doing this, except that using it is only slightly less painful than gouging your own eyes out.

LyX does everything Word does and a million things that Word can't do, and LyX does it all for free. It seamlessly integrates text editing with placement of numbered figures, equations and bibliography items. It has customizable fields for stating a document's title, author, abstract, keywords, and any other information deemed necessary. A LyX document is easily converted to LaTeX, to PostScript, and to PDF formats. Figure 1 shows the appearance of the PDF output for this module created by LyX (which calls pdfLaTeX in the background).

As this module shows, it is also easy to convert from the LyX format to CNXML, making LyX an ideal choice for creating multi-purpose technical content.

Figure 1: An example page from the PDF version of this module as produced by LyX.

Requirements and Usage.

The lyx2cnx script requires LyX , perl and tralics . Tralics is a LaTeX-to-XML translator used for converting equations. The lyx2cnx script expects "tralics" to be in the system's executable search path. Get Tralics from the APICS web site.

Lyx2cnx is designed to be run from the *nix command line. The usage is simple: lyx2cnx lyxfile cnxfile . The script also looks for a file called template.cnxml in the document's directory. This file contains the header and footer for the Connexions module. To create a module in LyX, place lyx2cnx in your system's search path and follow these steps:

Supported Features.

Lyx2cnx works by translating LyX layouts directly into CNXML tags. At present, not all CNXML features are mapped to LyX layouts. In the current version, the user can create

These features are not exhaustive, but are sufficient to create good technical Connexions modules.

Example Modules.

These modules were created using LyX and lyx2cnx:

Creating Sections and Paragraphs in LyX.

Paragraphs and sections are created in much the same way as with other word processors. In the upper left corner of the LyX main window, there is a drop-down box containing Layout options. The Layout determines the content type for a line or paragraph. The default Layout is "Standard". To create a paragraph, just start typing text in Standard mode. Press Enter to start a new paragraph. To start a new Section, select the "Section" Layout from the Layout box. Experienced LyX users may also take advantage of numerous hot-key shortcuts to change layout environments.

Creating Figures.

In LyX, figures are placed inside of "floats." A float is a movable box containing graphics and a caption. When LaTeX compiles a document, it moves the float around until it finds a best-fit position. Thus the figure is said to "float". The user only needs to place the float in an approximate desired location, and LaTeX handles the rest.

The LyX-CNXML translator uses floats to recognize figures. To place a Figure within a LyX document, select Insert →→ Floats →→ Figure from the LyX menu bar. A box appears within your document with a caption line labeled "Figure:". Press return. Now select Insert →→ Graphics to place your media. Then return to the caption line, select Insert →→ Label from the menu bar, and enter text to serve as an id for your figure. Finally, enter the caption text just after the label.

Figure 2 shows an example of a Figure float in LyX. Namely, Figure 2 shows the placement of itself within LyX during the preparation of this document. I apologize for any eyestrain which may result from this example.

Once the Figure has been placed in according to these instructions, the CNXML translator handles the creation of <figure> and <media> tags. The user is now done, except that each graphic file must be manually uploaded to the Connexions module workspace. I have noticed some bugs with file formats other than PNG, so I recommend using PNG images.

Figure 2: Example of Figure placement within LyX.

Using Cross-References.

To place a cross-reference in LyX, select Insert →→ Cross Reference from the application's menu bar. This raises a menu of cross-references. Select the one you want. For example, I can follow this procedure to refer to Figure 2 or Section 8. Lyx2cnx converts LyX cross-references into internal links within the Connexions module.

Lyx2cnx will also strip leading words from cross-references, such as "Figure" , "Fig." , "Section" or "Sec." This is because Connexions renders a cross-reference by printing its type and number, e.g. "Figure 2." LaTeX, on the other hand, would just print "2." If you want to also use the module as a LaTeX source to generate PDF files, you should type the word "Figure" before any figure cross-reference.

Creating Equations.

LyX represents equations in the TeX format. At present, the CNXML translator extracts all TeX equations and uses Tralics to convert them to XML. For most equations, for example y=e x y=e x , this method produces good results. The Tralics system is simple, extremely easy to download, install and use. It is available from the APICS group's web site. Tralics does not produce Content MathML, but it works well as a quick solution for authoring draft Connexions modules. A method is also provided, as described below, for users to supply their own MathML translations, bypassing Tralics if desired.

To create an inline equation in LyX, press Ctrl-m. To make a displayed equation, press Ctrl-Shift-M. Access the Math Panel by selecting Insert →→ Math →→ Math_Panel from the menu bar. Use the Math Panel to type in the equation. For displayed equations, use Insert →→ Label to assign an id to the equation. If you want to use the CNXML translator to process the equation, you are done.

If you want to control how the equation appears in the final Connexions module, you can insert a custom translation by placing it within a Minipage just after the LyX equation. A Minipage is just what it sounds like: a page within the page you are writing. In LaTeX, a mini-page can contain everything a regular page contains. In LyX, a minipage can be collapsed into a small icon, which is a convenient way of hiding garish XML.

To insert a Minipage, select Insert →→ Minipage from the main menu bar. Then select the "Comment" layout and paste the desired translation into the Minipage. To collapse the Minipage and get it out of the way, simply click on the "Minipage" tab.

As an example, Equation 1 is presented in MathML created by MathType. Equation 2 shows the same equation written in LyX, translated automatically by Tralics through the lyx2cnx script.

Figure 3 shows the appearance of these equations within LyX. The Minipage under Equation 1 is collapsed, and the Minipage under Equation 2 is expanded, showing its contents. Figure 4 shows the appearance of the equations in a PDF file compiled by pdflatex from within LyX.

Figure 3: Appearance of equations within LyX.

Figure 4: Rendering of equations in the PDF file produced by LyX.

Inline tags.

Some inline tags, such as "emphasis" and "link" , have a natural correspondence to LyX features. To use the emphasis tag in LyX, simply select a block of text and select Layout →→ Emphasis_Style from the menu bar. To create a link , select Insert →→ URL. Other inline tags are less direct:

Lists.

Itemized and enumerated lists are represented in LyX by the Itemize and Enumerate environments. Examples:

Currently, the <name> field is not supported, and nested lists are not supported.

Tips for avoiding bugs.

Most bugs arise from the handling of labels. Lyx2cnx uses labels to assign the id for sections, figures, etc. LyX will let you stick a label virtually anywhere, but lyx2cnx and Connexions are a little picky about the placement and content of labels/ids. Some recommendations:

To-do list.