B.16  Extra Features

• T_EX macros
• Command Definition inside Command Definition
• Date and time
• Fancy sectioning commands
• Targeting Windows
• MathJax support

This section describes H^EV^EA functionalities that extends on plain L^AT_EX, as defined in [L^AT_EX]. Most of the features described here are performed by default.

B.16.1  T_EX macros

Normally, H^EV^EA does not recognise constructs that are specific to T_EX. However, some of the internal commands of H^EV^EA are homonymous to T_EX macros, in order to enhance compatibility. Note that full compatibility with T_EX is not guaranteed.

B.16.1.1  À la T_EX macros definitions

The \def construct for defining commands is supported. It is important to notice that H^EV^EA semantics for \def follows T_EX semantics. That is, defining a command that already exists with \def succeeds.

Delimiting characters in command definition are somehow supported. Consider the following example from the T_EX Book:

\def\Look{\textsc{Look}}
\def\x{\textsc{x}}
\def\cs AB#1#2C$#3\$ {#3{ab#1}#1 c\x #2}
\cs AB {\Look}{}C${And \$}{look}\$ 5.

It yields: And $lookabLookLook cx5.

Please note that delimiting characters are supported as far as I could, problems are likely with delimiting characters which include spaces or command names, in particular the command name \{. One can include \{ in a command argument by using the grouping characters {… }:

\def\frenchquote(#1){\guillemotleft~\emph{#1}~\guillemotright{} (in French)}
he said \frenchquote(Alors cette accolade ouvrante {``\{''}~?).

Yields: he said « Alors cette accolade ouvrante “{” ? » (in French).

Another issue regards comments: “%” in arguments may give undefined behaviours, while comments are better avoided while defining macros. As an example, the following code will not be handled properly by H^EV^EA:

\def\x%
   #1{y}

Such T_EX source should be rewritten as \def\x#1{y}.

Another source of incompatibility with T_EX is that substitution of macros parameters is not performed at the same moment by H^EV^EA and T_EX. However, things should go smoothly at the first level of macro expansion, that is when the delimiters appear in source code at the same level as the macro that is to parse them. For instance, the following source will give different results in L^AT_EX and in H^EV^EA:

\def\cs#1A{``#1''}
\def\othercs#1{\cs#1A}
\othercs{coucouA}

L^AT_EX output is “coucou”A, while H^EV^EA output is “coucouA”. Here is H^EV^EA output: “coucouA” Please note that in most situations this discrepancy will make H^EV^EA crash.

B.16.1.2  The \let construct

H^EV^EA also processes a limited version of \let:

The effect is to bind macro-name1 to whatever macro-name2 is bound to at the time \let is processed. This construct may prove very useful in situations where one wishes to slightly modify basic commands. See sections 10.3 and B.2 for examples of using \let in such a situation.

B.16.1.3  The \global construct

It is possible to escape scope and to make global definitions and bindings by using the T_EX construct \global. The \global construct is significant before \def and \let constructs.

Also note that \gdef is equivalent to \global\def.

B.16.1.4  T_EX Conditional Macros

The \newif\ifname, where name is made of letters only, creates three macros: \ifname, \nametrue and \namefalse. The latter two set the name condition to true and false, respectively. The \ifname command tests the condition name:

Text text₁ is processed when name is true, otherwise text₂ is processed. If text₂ is empty, then the \else keyword can be omitted.

Note that H^EV^EA also implements L^AT_EX ifthen package and that T_EX simple conditional macros are fully compatible with L^AT_EX boolean registers. More precisely, we have the following correspondences:

B.16.1.5  Other T_EX Macros

H^EV^EA implements the macros \unskip and \endinput. It also supports the \csname… \endcsname construct.

B.16.2  Command Definition inside Command Definition

If one strictly follows the L^AT_EX manual, only commands with no arguments can be defined inside other commands. Parameters (i.e. #n) occurring inside command bodies refer to the outer definition, even when they appear in nested command definitions. That is, the following source:

\newcommand{\outercom}[1]{\newcommand{\insidecom}{#1}\insidecom}
\outercom{outer}

yields this output:

Nevertheless, nested commands with arguments are allowed. Standard parameters #n still refer to the outer definition, while nested parameters ##n refer to the inner definition. That is, the source:

\newcommand{\outercom}[1]{\newcommand{\insidecom}[1]{##1}\insidecom{inner}}
\outercom{outer}

yields this output:

B.16.3  Date and time

Date and time support is not enabled by default, for portability and simplicity reasons.

However, H^EV^EA source distribution includes a simple (sh) shell script xxdate.exe that activates date and time support. The hevea command, should be invoked as:

# hevea -exec xxdate.exe ...

This will execute the script xxdate.exe, whose output is then read by H^EV^EA. As a consequence, standard L^AT_EX counters year, month, day and time are defined and L^AT_EX command \today works properly. Additionally the following counters and commands are defined:

Note that I chose to add an extra option (and not an extra \@exec primitive) for security reasons. You certainly do not want to enable H^EV^EA to execute silently an arbitrary program without being conscious of that fact. Moreover, the hevea program does not execute xxdate.exe by default since it is difficult to write such a script in a portable manner.

Windows users should enjoy the same features with the version of xxdate.exe included in the Win32 distribution.

B.16.4  Fancy sectioning commands

Loading the fancysection.hva file will radically change the style of sectional units headers: they appear over a green background, the background color saturation decreases as the sectioning commands themselves do (this is the style of this manual). Additionally, the document background color is white.

Note : Fancy section has been re-implemented using style-sheets. While it respects the old behaviour, users are encouraged to try out style-sheets for more flexibility. See Section 9 for details.

The fancysection.hva file is intended to be loaded after the document base style. Hence the easiest way to load the fancysection.hva file is by issuing \usepackage{fancysection} in the document preamble. To allow processing by L^AT_EX, one may for instance create an empty fancysection.sty file.

As an alternative, to use fancy section style in doc.tex whose base style is article you should issue the command:

  # hevea article.hva fancysection.hva doc.tex

You can also make a doc.hva file that contains the two lines:

  \input{article.hva}
  \input{fancysection.hva}

And then launch hevea as:

  # hevea doc.hva doc.tex

Sectioning command background colours can be changed by redefining the corresponding colours (part, chapter, section,…). For instance, you get various mixes of red and orange by:

\input{article.hva}
\input{fancysection.hva}
\definecolor{part}{named}{BrickRed}
\definecolor{section}{named}{RedOrange}
\definecolor{subsection}{named}{BurntOrange}

(See section B.14.2 for details on the named color model that is used above.)

Another choice is issuing the command \colorsections{hue}, where hue is a hue value to be interpreted in the HSV model. For instance,

\input{article.hva}
\input{fancysection.hva}
\colorsections{20}

will yield sectional headers on a red-orange background.

H^EV^EA distribution features another style for fancy sectioning commands: the undersection package provides underlined sectional headers.

B.16.5  Targeting Windows

At the time of this release, Windows support for symbols through Unicode is not as complete as the one of Linux, which I am using for testing H^EV^EA.

One of the most salient shortcomings is the inability to display sub-elements for big brackets, braces and parenthesis, which H^EV^EA normally outputs when it processes \left[, \right\} etc.

We (hopefully) expect Windows fonts to display more of Unicode easily in a foreseeable future. As a temporary fix, we provide a style file winfonts.hva. Authors concerned by producing pages that do not look too ugly when viewed through Windows browsers are thus advised to load the file winfonts.hva. For instance they can invoke H^EV^EA as:

# hevea winfonts.hva ...

At the moment, loading winfonts.hva only changes the rendering of L^AT_EX big delimiters, avoiding the troublesome Unicode entities. As an example, here are some examples of rendering.

More generally, it remains authors responsibility to be careful not to issue too refined Unicode entities. To that aim, authors that target a wide audience should first limit themselves to the most common symbols (e.g. use \leq [≤] in place of \preceq [≼]) and, above all, they should control the rendering of their documents using several browsers.

B.16.6  MathJax support

MathJax support is enabled by loading the mathjax package. Two operating mode modes are provided: explicit and automatic. Notice that H^EV^EA distribution includes a innocuous mathjax.sty for L^AT_EX compatibility — see also Sec. C.4.2.

B.16.6.1  Explicit mode

Explicit mode is enabled when \usepackage{mathjax} appears in the document preamble, or when H^EV^EA is invoked as “hevea mathjax.hva…”.

Basic consists in one environment displayjax and one command \textjax. The environment is appropriate for displayed maths. As an example, the following source

A displayed formula:
\begin{displayjax}
\frac{\pi}{4} = \left[1 - \frac{1}{3} + \frac{1}{5} - \frac{1}{7} +
\frac{1}{9} + \cdots + \frac{(-1)^n}{2n+1} + \cdots \right]
\end{displayjax}

is displayed as follows:

The \textjax command is appropriate for inline mathematical contents. For instance, the following source

``A nice inline formula:
\textjax{\frac{\pi}{4} = \left[1 - \frac{1}{3} + \frac{1}{5} - \frac{1}{7} +
\frac{1}{9} + \cdots + \frac{(-1)^n}{2n+1} + \cdots \right]}.''

is typeset as: “A nice inline formula: \(\frac{\pi}{4} = \left[1 - \frac{1}{3} + \frac{1}{5} - \frac{1}{7} + \frac{1}{9} + \cdots + \frac{(-1)^n}{2n+1} + \cdots \right]\).”

Advanced support consists in the mathjax environment. Source code enclosed in \begin{mathjax}\ldots\end{mathjax} will be reproduced into output for the MathJax script to handle it. However, H^EV^EA does not start any other action. Thanks to this feature, users can have any (recognised by MathJax) displayed math environment processed by MathJax. For instance, the following source

\begin{mathjax}
\begin{eqnarray*}
z^2  & = & x^2 + y^2\\
\end{eqnarray*}
\end{mathjax}

will be displayed as:

Finally, notice that a document that uses the explicit MathJax constructs can be processed by L^AT_EX, provided it loads the mathjax.sty file present in H^EV^EA distribution. This can be done simply by having the line \usepackage{mathjax} in teh document preamble. Then, H^EV^EA and L^AT_EX will react appropriately (see sections 2.3.2 and B.5.2).

B.16.6.2  Automatic mode

Automatic mode is enabled when \usepackage[auto]{mathjax} appears in the document preamble, or when H^EV^EA is invoked as “hevea mathjaxauto.hva…”.

In automatic mode, H^EV^EA will pass all mathematical text to MathJax. This mode seems by far the most practical, but beware:

1. There is no communication back from MathJax to H^EV^EA. As result, equation numbers, as generated for instance by the equation environment, will not find their way to the final display.
2. Some constructs, such as \mbox, are not handled by MathJax.

B.16.6.3  Customising the MathJax script

By default H^EV^EA insert a reference to the “default” MathJax script with “default” configuration parameters. Advanced users can change this setting by redefining the \jax@meta command, which must contain the appropriate <script> element. See the file html/mathjax.hva for details.

9

According to date man page.