;;; image.skb  --  Images.
;;; -*- coding: iso-8859-1 -*-
;;;
;;; Copyright 2008  Ludovic Courtès <ludo@gnu.org>
;;; Copyright 2003, 2004  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/>.

;*---------------------------------------------------------------------*/
;*    Image ...  @label image@                                         */
;*---------------------------------------------------------------------*/
(section :title "Images" :file #t

(p [Images are defined by the means of the ,(code "image") function])

(doc-markup 'image
	    `((:file ,[The file where the image is stored on the disk
                       (see ,(ref :mark "*image-path*" 
				:text "image path")).
                       The image is converted 
                       (see ,(markup-ref "convert-image")) into a format 
                       supported by the engine. This option is exclusive 
                       with the ,(param :url) option.])
	      (:url [The URL of the file. This option is exclusive with the
                     ,(param :file) option.])
	      (:width [The width of the image. It may be an integer for a pixel
                       size or a floating point number for a percentage.])
	      (:height [The height of the image. It may be an integer for a 
                        pixel size or a floating point number for a 
                        percentage.])
	      (:zoom [A zoom factor.])
	      (#!rest comment [A text describing the image.]))
	    :see-also '(*image-path* convert-image))

(example-produce
 (example :legend "The image markup" (prgm :file "src/api16.skb"))
 (disp (include "src/api16.skb")))
   
(mark "*image-path*")
(p [Files passed as a ,(tt [:file]) argument to ,(markup-ref "image")
are searched in the current ,(emph [image path]), which is defined by
the ,(tt [*image-path*]) ,(srfi-ref 39) parameter.  This parameter
contains a list of directories and its value can be obtained using
,(code [(*image-path*)]).  Its value can be altered using the ,(tt [-P])
command-line option of the ,(tt [skribilo]) compiler (see ,(numref :text
[Chapter] :ident "compiler") for details).])


;*--- Image format ----------------------------------------------------*/
(subsection :title "Image formats"
   (index "image" :note "conversion")

   (p [
Images are unfortunately ,(emph "unportable"). The various Skribe output 
formats support different image formats. For instance, HTML supports 
,(code "gif") and ,(code "jpeg") while the LaTeX back-end only supports 
,(code "ps"). Skribe tries, only when needed, to automatically 
,(emph "convert") images to a format supported by the target
to be produced. For this, it uses external tools. The default Skribe
translation scheme is:])
(itemize (item [Do not translate an image that needs no conversion.])
	 (item [Uses the ,(code "fig2dev") external tool to translate 
                ,(code "Xfig") images.])
	 (item [Uses the ,(code "convert") external tools to translate all 
                other formats.]))
   
   (p [,(ref :chapter "Engines" :text "Engines") support different image
formats. Each engine may specify a converter to be applied to an image.
The engine custom ,(code "image-format") specifies the list of supported
image formats. This list is composed of a suffix such as ,(code "jpeg") or 
,(code "gif").])
   
   (p [The function ,(code "convert-image") tries to convert an
image according to a list of formats. All the specified formats are 
successively tried. On the first success, the function ,(code "convert-image")
returns the name of the new converted image. On failure, it returns 
,(code "#f").]) 
   (doc-markup 'convert-image 
	       `((file [The image file to be converted. The file is
searched in the ,(ref :mark "*image-path*" :text "image path").])
		 (formats [A list of formats into which images are converted to.]))
	       :common-args '()
               :skribe-source? #f
	       :source #f ;;"skribilo/runtime.scm"
               :def '(define-markup (convert-image file formats) ...)
	       :see-also '(*image-path*)
	       :idx *function-index*)))