$\LiRE$: $\rm\LaTeX$ inspired Reference Extensions

Table of Contents

1 Introduction
2 Philosophy
2.1 Basic concepts behind $\LiRE$
2.2 License
3 Documentation
3.1 Installation and usage
3.2 Supported $\rm\LaTeX$ commands and compatibility
3.2.1 BibTeX
3.2.2 Floats
3.2.3 Document structure
3.2.4 Footnotes
3.2.5 Special symbols
3.3 Other notes
4 Acknowledgment
5 References

1 Introduction

$\LiRE$ is a modest PHP library comprising some basic classes that allow to write nicely cross-referenced web-based articles using a mixed syntax of HTML/$\rm\LaTeX$. As the name implies, the library is intended primarily for creating multiple types of references in web documents. This is better explained in the next section. Also, the French verb “lire” means “to read”.

2 Philosophy

2.1 Basic concepts behind $\LiRE$

One of the strengths in $\rm\TeX$/$\rm\LaTeX$ [1, 2] is its cross-reference system. Using bibiographies is also facilitated thanks to tools such as BibTeX. Internet, on the other hand, is all about linking pieces of information together. Then there are also the typesetting possibilities of HTML. For example, creating complex tables may be difficult in $\rm\LaTeX$, while it could be achieved in a more flexible manner by using plain HTML (and maybe some CSS).

This is where the $\LiRE$ library comes in. While $\LiRE$ is not by itself a full-fledged $\rm\LaTeX$ parser, it allows for compatible syntax to be used for web content preparation. All important types of references are considered, that is:

BibTeX bibliography entries;
References to “floating” structures¹ (figures and tables; equations also fall under this category);
Document structure (sections, subsections, and subsubsections);
Footnotes.

If one requires $\rm\LaTeX$ compatible math to be used on the webpage, an additional library needs to be used as $\LiRE$ by itself does not propose math typesetting tools.

The library logo is shown in Figure 1 and can be typeset by defining the following in $\rm\LaTeX$:

\def\LiRE{{\sf %
L%
\kern-.2em\lower-.2ex\hbox{\i}%
\kern-.256em \lower-1.3ex\hbox{\rm{.}}%
\kern-.1emR%
\kern-.08emE}}

Then one may use the macro \LiRE to typeset (almost) the following:

Figure 1. $\LiRE$ library logo

Proposed file type for a HTML/$\rm\LaTeX$ file is .htex which points at both HTML and $\rm\TeX$.

2.2 License

The $\LiRE$ library is available under the terms of the GPL-v3.0 license:

  Copyright (C) 2011-2012 Aleksei Tepljakov
  
  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/.

3 Documentation

3.1 Installation and usage

Download: version 0.2-beta. To use it in your PHP script for parsing text, invoke it in the following way:

  require_once('lib/Lire.php');
  $lireParser = new Lire();
  $text       = $lireParser->parseLatex($text);

Additionally, you should add the CSS stylesheet that comes with the library in order to display different structure items correctly. Do this in the usual way:

  <link href='lib/css/default.css' rel='stylesheet' type='text/css'>

Otherwise you can create your own specific style based on your needs. In this case you may use the styles supplied in /lib/css/default.css as reference.

Setting up the math parser/typesetter is up to the user. A good choice for displaying high-quality math is the JavaScript based MathJax. A very basic setup would require one to add the following to the head section of the document:

  <script type='text/javascript'
    src='http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML'>
  </script>

Some additional configuration could be required. An example is provided below.

  <script type="text/x-mathjax-config">MathJax.Hub.Config(
  {
    extensions: ["tex2jax.js"],
    jax: ["input/TeX", "output/HTML-CSS"],
    tex2jax:
    {
        inlineMath: [ ['$','$'], ["\\(","\\)"] ],
        displayMath: [ ['$$','$$'], ["\\[","\\]"] ],
        processEscapes: true
    },
            
    TeX:
    {
        extensions: ["AMSmath.js","AMSsymbols.js",
    	"noErrors.js","noUndefined.js"]
    },
            
    "HTML-CSS": {
        availableFonts: ["TeX"]
    }
   });
  </script>

3.2 Supported $\rm\LaTeX$ commands and compatibility

Hereafter, a list of supported commands is listed with necessary comments. Note that at this time only a selected number of features is supported. The documentation is scarce, but should be enough for a seasoned PHP/HTML/$\rm\LaTeX$ user.

3.2.1 BibTeX

Supported commands for BibTeX bibliography handling are provided further in Table 1. This table probably looks poor in Internet Explorer (see for yourself). Moral: use a proper browser.

Table 1. BibTeX commands

Command	Effect
`\bibliography{link}`	Insert a single bibliography file either using a full URL, or a local file path. The “.bib” extension is not required.
`\bibliographystyle{style-name}`	Use the specified bibliography style, which is by default set to “IEEEtran-compatible”. In order to use a different style, one needs to create a corresponding PHP file in the `\lib\bibtex\bibstyle` directory. Citation style selection is not yet supported by the library wrapping class. Otherwise, it is possible to use a custom style, defined in a PHP file residing in the `\lib\bibtex\citestyle` directory.
`\cite{bibtex-key}`	Adds the citation reference to the text in the usual way. Multiple bibtex-keys may be supplied separated by a comma.
`\nocite{*}`	Adds uncited bibliography references to the bibliography until all references are present even if not used in the text.

Multiple bibliograpies are supported. This is useful for separating publications, for example. The \nocite{*} and \bibliographystyle{...} commands work globally; the reference style will be chosen according to the first occurence of the command.

3.2.2 Floats

This feature adds wrapping elements (<div>'s) around your tables, figures and equations. This is used for two main purposes:

Enumerate the floats (using simple counters);
Apply specific styles to the floats.

You can use the following environments (both numbered and unnumbered) by using \begin{env} ... \end{env}:

table,
figure,
equation, eqnarray, align and multline; note that these share the same counter.

Commands \caption{caption} and \label{float:label} are supported within the environments. The command \centering can be used to center figures and tables. Finally, \ref and \eqref are used to reference figures/tables and equations, respectively. Also note, that multiple consecutively numbered equations have to be placed in separate floats (environments).

Here is an exemplary equation (1), referenced using \eqref:

\begin{equation} y(x) = \sum_{i=1}^{N}{\dfrac{a_i^2 + \sqrt{b_i}}{c_i + x^i}}. \tag{1}\end{equation}

3.2.3 Document structure

Three levels of structure are provided. If the default configuration is used, the following correspondence is achieved:

Table 2. Structure commands

$\rm\LaTeX$ heading command	Heading TOC level	HTML heading tag
`\section{title}`	1	<h2>
`\subsection{title}`	2	<h3>
`\subsubsection{title}`	3	<h4>

Unnumbered entries are also supported. Additionally, a command \addtocline{Custom heading} can be used to set the title in the TOC if this is required. This command needs to be placed inside of the heading command, e.g. \section*{Unnumbered section\addtocline{TOC heading}}. Note, that this command is not found in $\rm\TeX$ and is only used in the library implementation.

Last but not least the \url{} and \href{} commands are supported in the usual way. For example, here is the link² to the LiRE website: http://starspirals.net/lire/

3.2.4 Footnotes

Basic footnote³ support with forward/backward links. Use \footnote{Footnote content}. Then place \footnotes in your document where you want the footnote list to appear.

3.2.5 Special symbols

Typically, one should use Unicode with $\LiRE$. However, there could be trouble with BibTeX entries. Thus, a limited character conversion scheme is used when parsing BibTeX.

3.3 Other notes

$\rm\LaTeX$ will not be parsed in text fragments appearing inside of <code> and <pre> HTML tags.

The current implementation of the library relies heavily on RegEx based search/replacement tools. For large texts with lots of bibliography entries the parser can become slow and thus using a caching mechanism is advised. It is up to the user to select the appropriate caching tools. Further development of the library will likely be devoted to improving performance by completely rewriting the parser or by optimizing the current implementation.

Also, documents spanning multiple web pages are not supported. $\LiRE$ follows different goals and therefore multiple page support is not planned in the future at this time.

4 Acknowledgment

The library was developed for the FOMCON project website [3] and as such the development of the library was supported by the Estonian Doctoral School in ICT under interdisciplinary project “FOMCON” and Estonian Science Foundation under grant nr. 8738.

5 References

[1]	D. E. Knuth, The $\TeX$book, 15th ed. Addison-Wesley, 1989.
[2]	L. Lamport. LaTeX. [Online]. Available: http://www.latex-project.org/
[3]	A. Tepljakov. (2012) FOMCON: Fractional-order Modeling and Control. [Online]. Available: http://www.fomcon.net/

¹ Quotation marks around the word floating are there because this term is not very correct in the context of the web
² This first link was inserted via the \href command
³ Such as this one