doc: Augmented the `eq' doc, documented `eq-display'.

git-archimport-id: lcourtes@laas.fr--2005-libre/skribilo--devo--1.2--patch-85

2 files changed, 61 insertions, 2 deletions

diff --git a/doc/user/eq.skb b/doc/user/eq.skb
index 455832b..1ef0208 100644
--- a/doc/user/eq.skb
+++ b/doc/user/eq.skb
@@ -70,7 +70,16 @@ 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")).]))
+: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])
@@ -91,7 +100,19 @@ render equations in HTML.])
 	            (: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.]))
+[: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"))
 
    )
diff --git a/doc/user/src/eq3.skb b/doc/user/src/eq3.skb
new file mode 100644
index 0000000..e229b6c
--- /dev/null
+++ b/doc/user/src/eq3.skb
@@ -0,0 +1,38 @@
+(p [This paragraph contains this equation: ,(eq :inline? #t '(/ alpha
+beta)).  This is actually an ,(emph [inline]) equation, meaning that it
+occurs within a paragraph.  Typesetting has to be adjusted
+accordingly.])
+
+(eq-display
+	
+   (p [This is an equation display block, within which equations can be
+aligned with one another.])
+
+   (eq :ident "eq-limit-b-over-l"
+       :renderer 'lout
+       :align-with '=
+       '(= (limit (/ lambda beta) 0
+		  (apply IPL n k))
+
+	   ;; non-simplified
+	   (/ (expt (+ alpha beta) k)
+	      (* beta
+		 (sum :from (= x 0)
+		      :to   (- k 1)
+		      (* (combinations k x)
+			 (expt beta (- k 1 x))
+			 (expt alpha x)))))))
+
+   [This equation can be simplified as follows:]
+
+   (eq :ident "eq-limit-b-over-l-simplified"
+       :renderer 'lout
+       :align-with '=
+       '(= ;; simplified
+	   (/ (expt (+ alpha beta) k)
+	      (- (expt (+ alpha beta) k)
+		 (expt alpha k)))
+	
+	   (limit (/ lambda beta) 0
+		  (apply IPL n k)))))
+