;;; eq.skb  --  Equation formatting.
;;; -*- coding: iso-8859-1 -*-
;;;
;;; Copyright 2006, 2007, 2008, 2009, 2012  Ludovic Courtès <ludo@gnu.org>
;;;
;;;
;;; This file is part of Skribilo.
;;;
;;; Skribilo 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.
;;;
;;; Skribilo 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 Skribilo.  If not, see <http://www.gnu.org/licenses/>.

;;; FIXME: This is a stub and must be completed!

(chapter :title [Equation Formatting] :ident "equations"
   
   (p [Skribilo comes with an equation formatting package.  This package
may be loaded by adding the following form at the top of your document:]

	(disp (prog (source :language scheme
		       [(use-modules (skribilo package eq))])))
	
      [It allows the inclusion of (complex) equations in your documents,
such as, for example, the following:]
	
	(disp (eq :renderer (if (and %have-lout?
	                             (engine-format? "html"))
	                        'lout
				 #f)
                  :ident "eq-disponibilite"
		  `(= (apply A D)
		      (sum :from (= i b) :to (* S b)
			   (* (script :sup (* S b) :sub i C)
			      (* (expt mu i)
				 (expt (- 1 mu)
				       (- (* S b) i))))))))
	
      [This chapter will describe the syntactic facilities available to
describe equations, as well as the rendering options.])
   
   (section :title [Syntax]
            :info-node [Eq Syntax]
      
      (p [To start with, let's have a look at a concrete example. ]
	
        (example-produce
	  (example :legend "Example of a simple equation using the verbose syntax"
	     (prgm :file "src/eq1.skb"))
	  (disp (include "src/eq1.skb")))

  	[In this example, the ,(tt [eq:]) sub-markups are used pretty
much like any other kind of markup.  However, the resulting syntax
is very verbose and hard to read.])
      
      (p [Fortunately, the ,(tt [eq]) package allows for the use of a
much simpler syntax.  ]

	(example-produce
	  (example :legend "Example of a simple equation"
	     (prgm :file "src/eq2.skb"))
	  (disp (include "src/eq2.skb")))
	
	[Readers familiar with the Lisp family of programming languages
may have already recognized its ,(emph [prefix notation]).  Note that,
unlike in the previous example, the equation itself if ,(emph [quoted]),
that is, preceded by the ,(tt [']) sign.  Additionally, when referring
to a symbol (such as the Greek letter ,(symbol "phi")), you no longer
need to use the ,(tt [symbol]) markup (,(numref :text [see Section]
:ident "symbols")).])

      (p [It is possible to create ,(emph [equation display blocks]),
where several equations are displayed and aligned according to a
particular operator. ]

	(example-produce
	  (example :legend "Inlined, displayed, and aligned equations"
	     (prgm :file "src/eq3.skb"))
	  (disp (include "src/eq3.skb")))))
   
   ;; FIXME: Write this.
   (section :title [Rendering])
   
   (section :title [Summary]
      
      (p [The options available for the top-level ,(code [eq]) markup
are summarized here:])
      
      (doc-markup 'eq
	          `((:inline? ,[If ,(code [auto]), Skribilo will
automatically determine whether the equation is to be "in-line".
Otherwise, it should be a boolean indicating whether the equation is to
appear "in-line", i.e., within a paragraph.  If the engine supports it,
it may adjust various parameters such as in-equation spacing
accordingly.])
		    (:number ,[If true, then a number is automatically
assigned to the equation and displayed.  If it is a string, then that
string is used as the equation's number.  If ,(code [#f]), then the
equation is left unnumbered.  Note that this option is only taken into
account for displayed equations.])
	            (:renderer ,[The engine that should be used to render
the equation.  This allows, for instance, to use the Lout engine to
render equations in HTML.])
	            (:mul-style ,[A symbol denoting the default style for
multiplications.  This should be one of ,(code [space]), ,(code
[cross]), ,(code [asterisk]) or ,(code [dot]).])
	            (:div-style ,[A symbol denoting the default style for
divisions.  This should be one of ,(code [over]), ,(code [fraction]),
,(code [div]) and ,(code [slash]).  Per-,(code [eq:/]) ,(code
[:div-style]) options override this setting.])
	            (:align-with ,[Within a ,(code [eq-display]) block,
this should be a symbol specifying according to which operator equations
are to be aligned with one another.]))
	          :source "skribilo/package/eq.scm")
      
      (p [Equation display blocks can be defined using ,(code
[eq-display]).  Display blocks define the scope of the alignment among
equations as specified by the ,(code [:align-with]) options of ,(code
[eq]).])
      
      (doc-markup 'eq-display
	          `()
	          :source "skribilo/package/eq.scm"))

   )

;;; arch-tag: e9c83c13-205f-4f68-9100-b445c21b959c