--- loncom/cgi/mimeTeX/mimetex.html 2006/03/24 23:08:33 1.2 +++ loncom/cgi/mimeTeX/mimetex.html 2008/12/04 12:17:13 1.4 @@ -1,10 +1,11 @@ + + + @@ -117,7 +125,7 @@ Banner across top of page, containing ti
m i m e T e X   m a n u a l
- ( for mimeTeX version 1.60 )
+ ( for mimeTeX version 1.70 )
Click for:  @@ -126,7 +134,7 @@ Banner across top of page, containing ti mimeTeX QuickStart
- + download mimeTeX
@@ -140,7 +148,7 @@ Banner across top of page, containing ti
-Copyright © 2002-2005, +Copyright © 2002-2008, John Forkosh Associates, Inc.
email: john@forkosh.com

@@ -219,7 +227,8 @@ Table of Contents     unzip mimetex.zip
    cc -DAA mimetex.c gifsave.c -lm -o mimetex.cgi
Now just mv mimetex.cgi to your cgi-bin/ - directory,
and you're all done. + directory,
set permissions as necessary, and you're all done. +   Usage:     @@ -261,25 +270,87 @@ SECTION I. INTRODUCTION wherever you put that <img> tag. + alt="" border=0 style="Vertical-Align:-11px"> + wherever you put that <img> tag. MimeTeX doesn't need intermediate dvi-to-gif conversion, and it doesn't - create separate gif files for each converted expression.

- -

There's also no inherent need to repeatedly write the cumbersome - <img> tag illustrated above. You can write your own custom - tags, or write a wrapper script around mimeTeX to simplify the - notation. For example, - - PmWiki already has a - - mimeTeX plugin that lets you just write - {$ f(x)=\int_{-\infty}^xe^{-t^2}dt $} - to obtain the same image. Or, if you're using - phpBB, then - Jameson - contributed the following one-line mod that lets you just write - [tex] ... [/tex] to obtain mimeTeX images:

- 
   #--------[open]-----------------------------------------------------
+    create separate gif files for each converted expression.
+    (But you can enable image caching with mimeTeX's
+      -DCACHEPATH=\"path/\"  
+    compile option.) 

+
+
 
+mimeTeX plugins... 

+
 There's no inherent need to repeatedly write the cumbersome
+    <img> tag illustrated above.  You can write your own custom tags,
+    or write a wrapper script around mimeTeX to simplify the
+    notation. 

+
+
  For example,
+    the following javascript snippet (based on
+    mathtran's
+    mathtran_img.js) lets you just write  
+    <img alt="mimetex:c=\sqrt{a^2+b^2}">  
+    wherever you want to see   

+    
   <script type="text/javascript">
+   <!--
+   // Create a namespace to hold variables and functions
+   mimetex = new Object();
+   // Change this to use your server
+   mimetex.imgSrc = "http://www.yourdomain.com/cgi-bin/mimetex.cgi?";
+   // Transform the whole document: add src to each img with
+   // alt text starting with "mimetex:", unless img already has a src.
+   mimetex.init = function () {
+       if (! document.getElementsByTagName) return;
+       var objs = document.getElementsByTagName("img");
+       var len  = objs.length;
+       for (i=0; i<len; i++) {
+          var img = objs[i];
+          if (img.alt.substring(0,8) == 'mimetex:')
+             if (!img.src) {
+                var tex_src = img.alt.substring(8);
+                img.src = mimetex.imgSrc + encodeURIComponent(tex_src);
+                // Append TEX to the class of the IMG.
+                img.className +=' tex'; }
+          }
+       mimetex.hideElementById("mimetex.error"); }
+   // Utility function
+   mimetex.hideElementById = function (id) {
+       var obj = document.getElementById(id);
+       if (obj) obj.style.display = 'none'; }
+   // resolve a cross-browser issue (see CBS events)
+   mimetex.addEvent = function (obj, evType, fn, useCapture) {
+       if (obj.addEventListener) { //For Mozilla.
+           obj.addEventListener(evType, fn, useCapture);
+           return true; }
+       else if (obj.attachEvent) { //For Internet Explorer.
+           var r = obj.attachEvent("on"+evType, fn);
+           return r; }
+       }
+   // Initialize after entire document is loaded
+   mimetex.addEvent(window, 'load', mimetex.init, false);
+   -->
+   </script>

+
+

+    Bulletin boards, wikis, etc, can also incorporate mimeTeX images
+    with short scripts.  For example, if you're using
+    phpBB2, then
+    Jameson
+    contributed the following typical one-line mod that lets you write
+    [tex] c=\sqrt{a^2+b^2} [/tex] to obtain the
+    same  image illustrated above  

+    
   #--------[open]-----------------------------------------------------
      /includes/bbcode.php
    #--------[find]-----------------------------------------------------
      // Remove our padding from the string..
@@ -287,7 +358,182 @@ SECTION I.  INTRODUCTION
      $text = preg_replace('/\[tex\](.*?)\[\/tex\]/ie',
      "'<img src=\"/cgi-bin/mimetex.cgi?'.rawurlencode('$1').'\" align=\"middle\" />'",
      $text);

+
 If you're using
+     phpBB3,
+     then no mod is even needed.
+     Just click Postings from the Administrator Control Panel,
+     and add the custom BBCode [tex]{TEXT}[/tex]  
+     with the HTML replacement
+     <img src="/cgi-bin/mimetex.cgi?{TEXT}" align=middle>

 
+
 Similarly, PmWiki also has a
+    
+    mimeTeX plugin that lets you just write
+    {$ f(x)=\int_{-\infty}^xe^{-t^2}dt $}
+    to obtain that same image.   Several other packages
+    also have similar mimeTeX plugins: 

+    

+     
+      
+      
+      
+     
+	  
+     
+	  
+	  
+
+     
+	  
+     
+	  
+     
+	  
+     
+     
+     
+    
   Package        Plugin   
 
+	  
+	  PmWiki     
+	  mimeTeX plugin  
 
+	  
+	  Wikimedia    
+	  
+	  "mimeTeX alternative"  
 
+	  PunBB     
+	  mimeTeX plugin  
 
+	  
+	  Movable Type      mimeTeX plugin  
 
+	  WordPress      
+     
+	  mimeTeX plugin   

+
+
 Please note: If you're writing your own plugin for mimeTeX,
+    please don't write php code using system( ), or any other
+    shell escape mechanism, just to cache images.  Use mimeTeX's
+      -DCACHEPATH=\"path/\"  
+    compile option instead.
+    system( ) raises security
+    issues, either real ones if used carelessly, or just in the minds of
+    system administrators.  Either way, I've received many emails from
+    people unable to use mimeTeX because of unnecessary system( )
+    calls prohibited by security-conscious sysadmins.  MimeTeX itself poses
+    minimal risk when used as illustrated above, but you're responsible
+    for any plugin/wrapper script you write around it. 

+
+
 
+Vertical alignment... 

+
 An image like
+    
+    doesn't look as good as the same image
+    
+    that's vertically aligned with your surrounding text.
+    Along with several standard 
+    
+    HTTP header fields, mimeTeX also emits a special
+      Vertical-Align: –nn  
+    header, where –nn is the number of pixels
+    (usually negative as illustrated) needed for a
+      style="Vertical-Align: –nn px"
+      attribute in the <img> tag used to
+    render your expression. 

+
+
 But mimeTeX's special Vertical-Align: header
+    is unrecognized and ignored by your browser.  You have to get the
+    header, interpret it, and write the corresponding <img> tag.
+    The only feasible way to do all this is using a scripting language,
+    as illustrated by the following, rather naive, php code 

+    
   <?php
+   $mimetexurl = "http://www.yourdomain.com/cgi-bin/mimetex.cgi?";
+   function verticalalign( $expression ) {
+      global $mimetexurl;
+      // note: curl_init() stops at the first whitespace char in $url argument
+      $expression = ereg_replace(" ","~",$expression); // so remove whitespace
+      $url     = $mimetexurl . $expression;
+      $valign  = "0";
+      $ch      = curl_init( $url );
+      curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
+      curl_setopt( $ch, CURLOPT_HEADER, true );
+      $gif     = curl_exec( $ch );
+      $errno   = curl_errno( $ch );
+      curl_close( $ch );
+      if ( $errno == 0 ) {
+        $fields = explode("Vertical-Align:",$gif);
+        $vfield = trim($fields[1]);
+        $fldlen = strspn($vfield,"+-0123456789");
+        $valign = substr($vfield,0,$fldlen); }
+      return $valign;
+      }
+   function mimetextag( $expression ) {
+      global $mimetexurl;
+      $valign = verticalalign($expression);
+      $url    = $mimetexurl . $expression;
+      echo ' <img src="',$url,'" ';
+      echo ' style="Vertical-Align:',$valign,'px" ';
+      echo ' alt="" border=0>', "\n";
+      }
+   ?>

+
+
 Now you can write  
+    <?php mimetextag('\frac12\left(a^2+b^2\right)'); ?>
+    wherever you want to see
+    
+    correctly aligned.  
+    This code calls mimeTeX twice to render each expression,
+    once to get the Vertical-Align: header and build an
+    <img> tag, and then again to render that tag.
+    If you're a good php programmer and write better code,
+    please email me a copy. 

+
+
 If you're using mimeTeX's
+      -DCACHEPATH=\"path/\"  
+    compile option, prefix your
+    path/ with a leading % and write  
+    -DCACHEPATH=\"%path/\"   instead.
+    That leading % won't become part of your cache
+    directory's path/, but it will signal mimeTeX
+    to cache headers along with each image.
+    Otherwise, the Vertical-Align: information is lost,
+    and attempts to align cached images will fail. 

+
+
 
+Alternative solutions... 

 
 MimeTeX's benefit over similar math-on-the-web solutions is, as
     mentioned above, its easy installation.  But if that's not a
     problem for you, and if your site's server already has a LaTeX
@@ -301,35 +547,38 @@ SECTION I.  INTRODUCTION
     , with arbitrary mean
+    alt="" border=0 style="Vertical-Align:-11px">,
+    with arbitrary mean
     
-    and standard deviation
+    src="../cgi-bin/mimetex.cgi?\large\mu" alt="" border=0
+    style="Vertical-Align:-5px"> and standard deviation
     , and at mimeTeX's next larger font size, looks like 

+    style="Vertical-Align:0px">,
+    and at mimeTeX's next larger font size, looks like 

      

       
-	
+	
-	
+	
+	
+        
-        
-	

        
 mimeTeX  latexrender 
 	   latexrender  mimeTeX 
        

        
     
  	
 	       
        

       

      

 
 Similar LaTeX-based solutions that you may want to look at are
+    mathtran,
     textogif and
     www.tug.org/interest.html and in the
     tex-faq. 

+
+
 For example, mathtran
+    is a public LaTeX web service that's
+    particularly easy to use by following these simple
+    instructions.  In the <head> of your
+    html page, place the tag 

+       
+      <script type="text/javascript" 

+           
+      src="http://www.mathtran.org/js/mathtran_img.js"></script>

+    and in the <body>, wherever you want to see latex images,
+    place tags like 

+       
+      <img alt="tex:any latex math expression">

+    For comparison, 

+       
+      <img alt="tex: f(x) = \frac1{\sigma\sqrt{2\pi}} 

+       
+      \int_{-\infty}^x e^{-\frac{(t-\mu)^2}{2\sigma^2}}dt"> 

+    looks like 

+     

+      
+       
+	
+	
+	
+       
+       
+	
+        
+ 	
+       
+      
 mathtran    mimeTeX 
 tex:\displaystyle f(x) = \frac1{\sigma\sqrt{2\pi}}
+         \int_{-\infty}^x e^{-\frac{(t-\mu)^2}{2\sigma^2}}dt 
 		   
+	  

+     

+
 
      Very briefly, download
      Form TX
      and follow the included instructions.
      In principle, you automatically own the copyright
      to anything you write the moment it's on paper.  In practice,
      if the matter comes under dispute, the courts look _very_ favorably
-     on you for demonstrating your intent by registering the copyright. 

-
+     on you for demonstrating your intent by registering the copyright.
+     For example, courts will stop unauthorized use of unregistered
+     material, but monetary damages are awarded _only_ if you
+     register the copyright before infringement occurs. 

 
 
 
+        
         mimetex.zip and then type
           
@@ -1003,12 +1308,12 @@ SECTION II.  BUILDING MIMETEX
   

            

-         
@@ -1137,14 +1442,15 @@ Ascii dump of bitmap image...
       http://www.yourdomain.com/cgi-bin/mimetex.cgi?x^2+y^2

      which should display  
         in the upper-left corner of your window,
+     style="Vertical-Align:-3px">  
+     in the upper-left corner of your window,
      just like clicking this link does, which tests my mimetex.cgi, 

             
       http://www.forkosh.com/cgi-bin/mimetex.cgi?x^2+y^2

      If you see the same      image
-     from the yourdomain link, then you've completed
+     \normalsize x^2+y^2" alt="" border=0 style="Vertical-Align:-3px">  
+     image from the yourdomain link, then you've completed
      a successful mimeTeX installation. 
 If you don't see the image, then your installation failed.
@@ -1230,13 +1536,22 @@ Ascii dump of bitmap image...
            is relative to mimetex.cgi, and must be writable by it.
            Files created under path/ are named
            filename.gif, where filename
-           is the 32-character MD5 hash of the LaTeX expression. 

-                 When caching a new image, mimeTeX also
+           is the 32-character MD5 hash of your LaTeX expression. 

+                    If you're also using mimeTeX's
+           Vertical-Align: feature, prefix your
+           path/ with a leading % and write
+             -DCACHEPATH=\"%path/\"  
+           instead.  That leading % won't become part of
+           your cache directory's path/, but it will signal
+           mimeTeX to cache headers along with each image.
+           Otherwise, the Vertical-Align: information is lost,
+           and attempts to align cached images will fail. 

+                    When caching a new image, mimeTeX also
            updates the file path/mimetex.log containing
            a timestamp, filename and LaTeX expression for each new file
            created.  A sample entry looks like
 
---------------------------------------------------------------------
-2004-08-07:09:00:53am            f8ccc8dd93c8eeb1d9c40b353ef781e0.gif
+2008-09-07:11:29:53am            f8ccc8dd93c8eeb1d9c40b353ef781e0.gif
 \LARGE x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}
 ---------------------------------------------------------------------
-DDEFAULTSIZE=n 

@@ -1262,6 +1577,11 @@ Ascii dump of bitmap image...
            \textstyle, \displaystyle, \limits or
            \nolimits directives in an expression always override
            the DISPLAYSIZE default. 
+      
-DGAMMA=gammacorrection 

+       
 Applies gammacorrection to antialiased
+           gif images.  Default is 1.25 (rather than the standard 2.2).
+           Specify 0.0 to turn off gamma correction (1.0 makes no
+           gamma correction but doesn't actually turn it off). 
-DNEWCOMMANDS=\"newcommands.h\" 
 LaTeX-like \newcommand's are available in mimeTeX,
            via the following facility to help you define your
@@ -1313,6 +1633,10 @@ Ascii dump of bitmap image...
            
     To see many additional examples, search for the
            uppercase string NEWCOMMANDS in mimetex.c, and look below that.
            All the above examples are already there. 

+      
 -DOPAQUE 

+       
 By default, mimeTeX renders gif images with black symbols
+           on a transparent white background.  Defining OPAQUE renders
+           images on an opaque background instead. 
 -DPATHPREFIX=\"path/\" 
 The \input{ } and
            \counter{ } commands discussed below
@@ -1324,7 +1648,33 @@ Ascii dump of bitmap image...
            defined as path/ if you want input files in some
            other directory.  And make sure your path/ ends
            with / (or with \ for Windows). 

-      
 -DREFERER=\"domain\"  or 

+      
 -DPLUSBLANK       -or-

+           -DPLUSNOTBLANK 

+       
 mimeTeX receives your LaTeX math expression as a url
+           query string, in which blank spaces are often encoded
+           as %20 or as plus signs +, and
+           where actual plus signs are often encoded as %2B.
+           But these conventions aren't always respected,
+           and even when they are blank spaces may be either
+           %20 or +.  The only ambiguity for
+           mimeTeX is whether or not to translate plus signs +
+           back to blank spaces. 

+                 If you know how your applications behave,
+           then define PLUSBLANK to always translate plus signs +
+           to blank spaces, or define PLUSNOTBLANK to never translate. 

+                 Otherwise, if you define neither,
+           mimeTeX applies some common-sense rules to decide whether or
+           not to translate.  These usually work, but can't be guaranteed.
+           If your query string contains actual blank spaces or
+           blanks encoded as %20, then plus signs +
+           aren't translated.  Otherwise, if your query string
+           contains %2B, then plus signs + are
+           translated.  If neither %20 nor %2B, or both
+           %20 and %2B, occur in your query string,
+           then the situation is ambiguous.  In this case, if mimeTeX
+           finds two or more plus signs ++ with no intervening
+           space, then they're translated; otherwise they're not. 

+      
 -DREFERER=\"domain\"       -or-

            -DREFERER=\"domain1,domain2,etc\" 

        
 Blocks mimeTeX requests from unauthorized domains that
            are using your mimetex.cgi (hence your server's resources)
@@ -1355,7 +1705,7 @@ Ascii dump of bitmap image...
            could conceivably flood your file system by submitting
            zillions of \counter{filename} commands
            to mimeTeX, each with a different filename. 

-      
-DSMASHMARGIN=n or 

+      
-DSMASHMARGIN=n       -or-

           -DNOSMASH 

        
 TeX typically renders an expression like
            \frac12\int_{a+b+c}^{d+e+f}g(x)dx as 
@@ -1373,7 +1723,7 @@ Ascii dump of bitmap image...
            number of pixels between smashed symbols (default is 3),
            compile with -DSMASHMARGIN=n.
            See Smash for further discussion. 

-      
 -DWARNINGS=n  or 

+      
 -DWARNINGS=n       -or- 

            -DNOWARNINGS 

        
 If an expression submitted to mimeTeX contains an
            unrecognzied escape sequence, e.g., "y=x+\abc+1", then
@@ -1387,7 +1737,8 @@ Ascii dump of bitmap image...
       
 -DWHITE 

        
  MimeTeX usually renders black symbols on a white
            background.  This option renders white symbols on
-           a black background instead. 

+           a transparent black background instead (or on an opaque
+           black background when combined with -DOPAQUE ). 
      
 
 
@@ -1403,7 +1754,9 @@ Ascii dump of bitmap image...
      possibly useful functionality from the command line.  In particular,
      you can store a gif (or xbitmap) image of any expression to a file.
      No syntax checking is applied to command-line arguments, so enter
-     them carefully. 

+     them carefully.  (Likewise, plus signs + are never
+     translated to blank spaces, nor is any other %xx url decoding
+     performed on command-line arguments.) 

      
  
 The complete command-line syntax for mimeTeX is 

      
@@ -1468,6 +1821,8 @@ Ascii dump of bitmap image...
           display utility,
                ./mimetex  -o -d  "x^2+y^2" | display &
           opens a small window containing the rendered expression.
+          (Note: if you already compiled mimeTeX with -DOPAQUE
+          then  -o  renders images on a transparent background.)
 
      -s fontsize   0-7, font size.  Font size can also be specified
           within the expression by a directive, e.g., \Large f(x)=x^2
@@ -1555,17 +1910,46 @@ SECTION III.  SYNTAX REFERENCE
      As usual, you must explicitly write one of the recognized math
      spaces to put extra visible space in your rendered expressions. 

 
- 
 MimeTeX recognizes math spaces \, \: \; as well as
-     \/ and \quad and \qquad .  You may also
-     write \hspace{10} to insert a 10-pixel (or any other number)
-     space, scaled by any preceding \unitlength,
-     as illustrated just above.  There are no negative spaces. 

+ 
 MimeTeX recognizes math spaces \/ \, \: \;
+     as well as \quad and \qquad ,
+     and also a backslashed blank  
+       
+     (i.e., a \ followed by a blank).
+     For example,  
+     (a\/b\,c\:d\;e\  f\quad  g\qquad  h)
+       renders  
+        .
+     In mimeTeX, you may also write   \hspace{10}  
+     to insert a 10-pixel (or any other number) space, scaled by any
+     preceding \unitlength, as illustrated
+     just above. 

+
+ 
 For negative spaces,   \!   produces a small (two
+     pixel) negative space, e.g.,   a=b   renders  
+     
+       whereas   a\!=b   renders  
+     
+       and   a\!\!=b   renders  
+     .
+     For large negative space,   \hspace{-10}   permits
+     a negative argument.  But it stops at the first pixel to its left
+     rather than "erasing" pixels.  If you don't want to stop, use
+       \hspace*{-10}   instead. For example,
+       ABC\hspace*{-20}-DEF   renders  
+     ,   erasing all of the C
+     and the right half of the B. 

 
+
 
  
 MimeTeX also supports \hfill{textwidth}, where
      textwidth is roughly equivalent to LaTeX's
@@ -1574,18 +1958,18 @@ SECTION III.  SYNTAX REFERENCE
      expression will span.  However, if \hfill{ } appears
      within a { }-enclosed subexpression, then it applies
      only to that subexpression.  For example, 
 

-        {abc \hfill{50} def} \hfill{100} ghi
+        {abc \hfill{75} def} \hfill{150} ghi
             produces    
          
 

-     The first/inner \hfill{50} inserts exactly enough whitespace so
-     that subexpression "abc  def" spans 50 pixels.
-     Then the second/outer \hfill{100} inserts exactly  enough
-     whitespace so that the entire expression spans 100 pixels.
+     The first/inner \hfill{75} inserts exactly enough whitespace so
+     that subexpression "abc  def" spans 75 pixels.
+     Then the second/outer \hfill{150} inserts exactly  enough
+     whitespace so that the entire expression spans 150 pixels.
      Without explicit { }-nesting, mimeTeX evaluates expressions
-     left-to-right (sinistrally), e.g., ...\hfill{100}...\hfill{50}...
-     is exactly equivalent to ...\hfill{100}{...\hfill{50}...}.
+     left-to-right (sinistrally), e.g., ...\hfill{150}...\hfill{75}...
+     is exactly equivalent to ...\hfill{150}{...\hfill{75}...}.
      Notice that, this time, the second/right textwidth
      argument is necessarily smaller than the first/left. 

 
@@ -1675,14 +2059,20 @@ and some other characters..
      defined by the mimeTeX preprocessor, function mimeprep( )
      in mimetex.c     Generally speaking, I've tried to
      encode the cmr10, cmmi10, cmmib10, cmsy10, cmex10, bbold10, rsfs10,
-     and stmary10 families with "names", e.g., \alpha \beta
+     stmary10 and wncyr10 families with "names", e.g., \alpha \beta
      \forall \sqcup, etc, identical to your LaTeX expectations.
      For example, the calligraphic symbols in cmsy10 are accessed by
      writing \mathcal{A} \mathcal{B} \mathcal{XYZ}.  Similarly,
      write \mathbf{A} for the cmmib fonts, write \mathscr{A}
-     for rsfs10, and write \mathbb{R} for bbold10.
-     And see stmaryrd.dvi or stmaryrd.sty, supplied with most LaTeX
-     distributions, for the names of the stmary10 symbols. 

+     for rsfs10, write \mathbb{R} for bbold10, and write
+     {\cyr Khrushchev} or \cyr{Khrushchev} to see
+     .
+     Most LaTeX distributions supply stmaryrd.dvi and stmaryrd.sty
+     that both document the names of the stmary10 symbols.
+     Similarly, amsfndoc.dvi documents the names of the wncyr10
+     cyrillic symbols and ligatures. 

        For example, 
 

         anything at all   just produces  
         ..
         src="../cgi-bin/mimetex.cgi?\normalsize\textit{anything at all}"
         alt="" border=0 align=middle>     instead. 

 
+ 
 You don't usually surround mimeTeX expressions with $'s,
+     but that works in the usual way for \text{ } and
+     \mbox{ }, rendering the $...$-enclosed
+     subexpression in mathmode.  For example, 
 

+        n=\left\{m/2\text{    if $m$ even}
+        \\(m+1)/2\text{  if $m$ odd}\right.
+          produces  
+         

+
 
 
  (IIIc) Delimiters    

 
@@ -2165,7 +2574,7 @@ and some other characters..
      [ ] and \{ \}, limits are default-rendered
      \displaystyle, which is why \right|\nolimits_a^b was required. -->
      You can also write \left\sum, \left\prod,
-     \left\cup, etc, for many of the symbols in CMEX10.
+     \left\cup, etc, for many of the symbols in CMEX10 and STMARY10.
      And any symbol that works with \left will also work
      with \right .  

          
README mimeTeX release notes
LICENSE    GPL license, under which you may use
+         
COPYING    GPL license, under which you may use
                                      mimeTeX

          
mimetex.c  mimeTeX source program and all required
                                      functions