;;; figure.skb  --  Figures.
;;; -*- coding: iso-8859-1 -*-
;;;
;;; Copyright 2008  Ludovic Courtès <ludo@gnu.org>
;;; Copyright 2003  Manuel Serrano
;;;
;;;
;;; 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/>.

;*---------------------------------------------------------------------*/
;*    Figure ... @label figure@                                        */
;*---------------------------------------------------------------------*/
(section :title "Figures" :file #t

   (p [The ,(markup-ref "figure") markup shown below produces floating
figures.  Well, whether the figure is really ``floating'' depends on the
engine used (see ,(numref :text [Chapter] :ident "engines")): printed
output as produced by the ,(tt [lout]) and ,(tt [latex]) engines do
produce floating figures, but on-line output as produced by the ,(tt
[html]) engine does not.])

(doc-markup 'figure
	    `((:legend ,[The legend of the figure. If no ,(param :ident) is
               provided to the figure, it uses the legend value as an
               identifier. In consequence, it is possible to use the 
               ,(param :legend) value in
               ,(ref :mark "ref" :text "references").])
	      (:number ,[If the optional argument ,(param :number) is a number,
                that number is used as the new Scribe compiler figure 
                counter. If it is ,(tt "#t") the compiler automatically
                sets a number for that figure. If it is ,(tt "#f") the 
                figure is numberless.])
	      (:multicolumns ,[A boolean that indicates, for back-ends 
                supporting multi-columns rendering (e.g., "TeX"), if the figure
                spans over all the columns.])
	      (#!rest body [The body of the figure.]))
	    
	    :see-also '(ref document))

 ;; Note: We can't use `example-produce' because the Lout engine, for
 ;; instance, forbids the occurrence of `figure' within a table.
 (example :legend "The figure markup" (prgm :file "src/api14.skb"))
 (include "src/api14.skb")

;*--- List of figures -------------------------------------------------*/
(subsection :title "List of Figures"
(index "figure" :note "list of figures")

(p [Skribilo has no built-in facility to display the list of figures.
Instead, it provides a general machinery for displaying any kind of
lists of items contained in a document.  This is described in the
section ,(ref :section "Resolve") and ,(ref :subsection
"Introspection").  For the sake of simplicity, an example showing how to
display the list of figures of a document is included below.])

(example-produce
 (example :legend "The figure markup" (prgm :file "src/api15.skb"))
 (disp (include "src/api15.skb")))))

;;; Local Variables:
;;; ispell-local-dictionary: "american"
;;; End: