Extension:WikiTex/Documentation

From MediaWiki.org
Jump to navigation Jump to search

WikiTex Documentation

Usage[edit]

Use <wikitex> and </wikitex> to enclose that part of the page (maybe all page) where you want to use the usual math editing:

<wikitex>
Let $Q$ be any finite set, and $\mathcal B=2^Q$ be the collection of the subsets of
$Q$. Let $f:\mathcal B\rightarrow \mathbb R$ be a function assigning real numbers to
the subsets of $Q$ and suppose $f$ satisfies the following conditions:
:(i) $f(A)\ge 0$ for all $A\subseteq Q$, $f(\emptyset)=0$,
:(ii) $f$ is monotone, i.e. if $A\subseteq B\subseteq Q$ then $f(A)\le f(B)$,
:(iii) $f$ is submodular, i.e. if $A$ and $B$ are different subsets of $Q$ then
$$ \eqno{(2)}
 f(A)+f(B)\ge f(A\cap B) + f(A\cup B).
$$
</wikitex>

Beware: formulas are typeset with plain TeX with some predefined commands (such as \mathcal or \mathbb above). LaTeX constructs do not work.

The result is

WikiTexSample.png

Formula numbers[edit]

Displayed formulas might be numbered. Formula numbers are defined within the $$ signs as the argument enclosed inside curly brackets of the \eqno macro:

 $$\eqno{(*)} a^2 + b^2 = c^2 $$

The formula number is extracted from the formula, and is used directly. This means that no TeX construct can (or should) be used: \eqno{(***)} is prefectly valid. Sorry, no automatic formula numbering and labels. The \eqno macro should be defined in the TexInclude preamble to stop TeX from complaining about \eqno:

\def\eqno#1{}

Attributes[edit]

The <wikitex> tag accepts a few attributes which are in effect for all formulas until the closing </wikitex> tag. Attributes come after the wikitex word but before the > sign. Attributes might have a value, then the attribute is followed by an equality sign =, and then the attribute value enclosed within quotation marks:

 < wikitex refresh dpi="144" >

Do not leave spaces around the = sign.

Warning: attribute setting is not part of the formula. It means that if same formula occurs in several <wikitex> blocks with different attribute settings, it will be shown everwhere the way it was generated last time, and not as the particular attribute setting would require.

refresh
This attribute forces all formulas generated freshly. Formulas are hashed and images are stored by their hash. When the a formula is encountered it is checked first whether the image is there, and it is processed only if no image found. With this attribute all formulas are processed independently whether the image exists or not. Use it when you change the include file, or you want to regenerate the images for some reason.
The refresh attribute slows down page rendering significantly. Use it only with the preview feature, and delete it before saving the page.
This attribute has effect only when editing the page, but has no effect when vieweing it.
You might need to clear your browser's cache before you see the newly generated pictures.
dpi="resolution"
You can specify the resolution of the picture generated. TeX works with 10 point size symbols and with dpi="100" you will get a picture with true 10 point size. The default value is dpi="120" which gives acceptable results for the typical browser setting.
To change the default dpi value, please change it in WikiTex.php. Locate this line, and replace 120 with your favourite number:
  if( !isset($dpi) || ! preg_match('/^[0-9]+$/',$dpi) ) { $dpi=120; }
This is the effect of using different dpi values: WikiTexFontSize.png
include="Include:File"
You can specify your own TeX macros which will be prepended to all formulas between <wikitex> and </wikitex>. The value is the wiki page name which contains the macros. You can specify several include files, separated by semicolons:
 include="Math:TexInclude; Lectures:TexInclude"
In this case the content of Math:TexInclude will be included the first, followed by the content of Lectures:TexInclude (which can, for example, redefine previously defined commands).
See #TeX include files for a description how to prepare the include files.
noinclude
without this attribute, the standard include file MediaWiki:TexInclude will be prepended first to the formula. If this attribute is present, this file will not be prepended.
Use it only if you know what you are doing. You should define the \eqno macro to ignore its argument, otherwise formula numbering won't work.

CSS for displayed formulas[edit]

Displayed formulas, i.e. those between $$ and $$ signs, are formatted differently than inline formulas. First, the text of the display formula is scanned for the \eqno{...} macro, and the text between the curly brackets is extracted as the formula number. Next the formula is typeset, and the picture is placed between <div> and </div> as follows:

 <div class="texdisplay"> 
   <span class="dispno"> extracted formula number </span> 
   <img class="tex" src="..." alt="..." />
 </div>

The second line is there only if there formula contains formula number. How this is rendered depens on the definition of the classes "texdisplay", "dispno", and "tex" which should be defined in the actual skin.

The easiest way to make sure that all these classes are defined is to edit the MediaWiki:Common.css file, as described in the Installation section.


TeX include files[edit]

The included pages are copied into the TeX file verbatim, without any processing. Thus these files should not upset TeX. Also, you want to see and edit them on Wiki. The best way to achieve this is to start all lines with a space. Spaces are (mostly) ingmored by TeX, while wiki understands these lines as something which should be displayed.

Nevertheless, wiki might want to process some of your inserted text, such as [[. To prevent this, you can enclose the whole file between <nowiki> and </nowiki>. These words, however, should be protected from TeX. Thus use the TeX comment symbol:

%<nowiki>
 % here are the include macros, each line starting with a space
 \def\firstmacro{\hbox{first}}
 \def\secondmacro{\hbox{second}}
 % and this is the last line of the file:
%</nowiki>

Macro which you must define[edit]

To get formula numbers right, you should include this definition in the standard MediaWiki:TexInclude file:

\def\eqno#1{}

As all formulas (even displayed ones) are typeset in inline mode, TeX complains about \eqno{} as inappropriate.

Macro which you might want to define[edit]

Inline formulas are split at $ signs. Thus inside an inline formula you cannot have another $ sign. This, however, might be handy if you are typesetting a formula with a text in it. In the formula

 \{f: \hbox{$f$ and $g$ are compatible} \}

we are using the \hbox to get the text and the spacing right. Putting $ signs before and after this sequence, the result is not a properly formed formula. The remedy is the \math macro:

 \def\math#1{$#1$}

which lets us write the above formula as

 $\{f: \hbox{\math{f} and \math{g} are compatible} \}$

This problem does not occur in displayed formulas. Thus the following TeX formula is fine and handled correctly:

 $$ f(x) = \cases { -1 & if $x<0$ \cr
                     0 & if $x=0$ \cr
                    +1 & otherwise }
 $$

Computing vertical adjustment[edit]

TeX, as all typesetting programs, keeps track of the base line of each block, and aligns neightbouring blocks vertically along their baselines. To align a formula with the neighbouring text one should know where the baseline of the formula is.

Formulas can grow upwards and downwards quite a lot (think of fractions with fractions in the enumenator or in the denumenator only). When a picture is generated from the formula, it is trimmed to the visible parts, and the place of the base line is lost. The best practice is to assume that it is somewhere at the middle of the picture. Which sometimes gives devastating result. The question is can we recover the position of the baseline?

The appropach taken by Extension:WikiTex is to let TeX tell us this information. The typeset formula is enclosed into a box, and TeX can print out its dimensions, meaning width, height and depth. The last two are measured from the baseline of the box. WikiTex generates the following TeX file:

 .. preamble copied from the include files
 \setbox0\hbox{$  here comes the formula itself $}%
 \message{//\the\dp0//}%
 \box0%
 \bye

The % marks at the end of the lines prevent generating superfluous empty spaces. The \setbox0\hbox{..} line typesets its argument at stores it in box numbered 0 (used for temporary purposes by TeX). The \message command prints out its argument to the log file. The argument is the depth of box zero surrounded by double slash chartacters. The \box0 command unpacks the content of box zero – and the formula appears here. The last line is the closing command for plain TeX.

The external worker program calls TeX which places this info in the log file. The log file is searched for the text "//depth:<number>pt//", and if found, the "number" is extracted:

  # search for //depth: in the log file, digits, point, and the - sign allowed
  DEPTH=`grep "//depth:[0-9.\-]*pt//" this.log 2>/dev/null`
  # cut the beginning
  DEPTH=${DEPTH#*depth:}
  # cut the end
  DEPTH=${DEPTH%%pt*}

Now $DEPTH is the depth of the generated formula in points, which might be a negative number (if the bottom of the formula is above the base line). This value is returned by the worker program. What we have to do is to convert points to pixels, and we've got the position of the base line!

Well, not exactly. TeX works with frames, and not with pixel images. A frame is a rectangle which is a placeholder for the pixel image of the final character. Sometimes a character has pixels outside the frame, sometimes it does not fill the frame from side to side, thus this computation migh displace the baseline a little. Still it is a good approximation, and works quite well.

The <tex> tag[edit]

WikiTex internally strips the dollar signs and wraps all formulas between <tex> and </tex> then calls the rendering routine recursively. You can also use the <tex> tag directly. There are certain differences, which make the two tags behave differently. So be warned.

  • the whole text in a <tex> block is typeset in math mode, thus do not use $ signs at the beginning and at the end.
  • <wikitex> works on block level, while <tex> works on element level. This means, for example, that if you put two <wikitex> blocks next to each other, the second one will start a new paragraph. Putting two <tex> blocks next to each other will produce two adjacent pictures on the same line.
  • Attributes of <wikitex> are in effect for all formulas between $..$ and $$..$$, however have no effect on <tex> blocks. Each <tex> has its own attributes.
  • You can use $ signs inside a <tex> block, but you cannot use in a formula between $..$. Thus
     <tex> -1 \hbox{ if $x<0$} </tex>
    is perfectly valid, while putting this between $..$ you'll get error messages.
  • <tex> has an additional attribute: display. When this attribute is present, the formula is prepended by the TeX command \displaystyle, searched for the command \eqno{...} to extract a formula number, and a display is generated from the picture.

Formula cache[edit]

WikiTex uses the same place and same method to cache processed formulas as the <math> extension. First, it computes the hash of the formula using MD5. To avoid collision with formulas rendered by <math>, a single $ sign is prepended to inline formulas, and double $$ is prepended to displayed formulas. The hash – a 32 character hexadecimal number –, with the .png extension, is the name of the generated image. If the image exists (and the refresh attribute is missing), it is used. If the image does not exist, the external worker program is called. The value of the vertical align is recovered from the database, or stored there if the image was created freshly. WikiTex uses the math_mathml field for this purpose in the Math table.


Using Latex[edit]

I have chosen plain TeX, rather than LaTeX as the former one is much faster. LaTeX has thousands of features, extensions, which one uses quite rarely. The speed is not so important when you typeset a large chunk of text (such as an article or a book chapter), but becomes important when dozens of small pieces should be processed. Nevertheless, if you think the difference in speed is worth of the gain, hack the code to use latex rather than plain tex. Here are some pointers.

  • Prepare the LaTeX file as follows:
     \documentclass{article} % don't set larger size
     ... insert here all included files
     \begin{document} %start of the document
     \thispagestyle{empty} %no page number will be generated for this page
     \setbox0\hbox{$ ...the formula to be typeset comes here... $}
     \message{//\the\dp0//}
     \box0
     \end{document}
    
    To do so, locate the fwrite() commands in WikiTex.php, function wfTexXMLFunction(), and change what they write out accordingly.
  • In the helper function replace the call to "tex" to "latex".
  • As include files are copied to the pre-amble, they can contain only definitions, package requirements, but nothing which would produce visible output.
  • Don't forget: you can use the old fashioned \def\whatever{} definition in LaTeX, too, next to the \newcommand and \renewcommand
  • Do not forget to define the \eqno{} macro as well to ignore its only argument.