;;; char.skb  --  Characters, strings and symbols
;;; -*- 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/>.

;*---------------------------------------------------------------------*/
;*    Footnote ...                                                     */
;*---------------------------------------------------------------------*/
(section :title "Characters, Strings and Symbols" :file #t

;*--- characters ------------------------------------------------------*/
(subsection :title "Characters"

(p [The function ,(code "char") introduces a ,(emph "character") in
the produced document. The purpose of this function is to introduce
escape characters or to introduce characters that cannot be typesetted
in the document (for instance because the editors does not support
them). The escapes characters are ,(code (char 91)), ,(code (char 93))
and ,(code (char 59)).])

(doc-markup 'char
	    '((char [The character to be introduced. Specified value can be
a character, a string or an integer]))
	    :common-args '())

(example-produce
 (example :legend "Some characters" (prgm :file "src/api19.skb"))
 (disp (include "src/api19.skb"))))


;*--- Strings ---------------------------------------------------------*/
(subsection :title "Strings"

(p [the function ,(code "!") introduces raw strings in the target.
That is, the strings introduced by ,(code "!") are written ,(emph "as is"),
without any transformation from the engine.])

(doc-markup '!
	    '((format [The format of the command.])
	      (#!rest node... "The arguments."))
	    :common-args '())

(p [The sequences ,(code "$1"), ,(code "$2"), ... in the ,(param 'format)
are replaced with the actual values of the arguments ,(param 'node).])

(let ((file (if (engine-format? "lout")
	        "src/api20-lout.skb"
	        "src/api20-html.skb")))
  (example-produce
   (example :legend "Some characters" (prgm :file file))
   (disp (include file)))))

;*--- Symbols ---------------------------------------------------------*/
(subsection :title "Symbols"
   :ident "symbols"

(p [The function ,(code "symbol") introduces special symbols in the
produced file. Note that the rendering of symbols is unportable. It depends
of the capacity of the targeted format.])

(doc-markup 'symbol
	    '((symbol [The symbol to introduce.]))
	    :common-args '())

(p [Here is the list of recognized symbols:])

(apply ctrtable
       :width *prgm-width*
       (tr :class 'api-symbol-prototype (th "Symbol name") (th "Rendering"))
       (map (lambda (s)
               (tr :bg  *prgm-skribe-color*
                   (td :align 'left s)
                   (td :align 'left (symbol s))))
            (sort (let ((t (make-hash-table)))
                     (for-each (lambda (e)
                                  (for-each (lambda (s)
                                               (hash-set! t (car s) (car s)))
                                            (engine-symbol-table e)))
                               *api-engines*)
                     (hash-fold (lambda (key value result)
		                  (cons key result))
				'()
				t))
                  string<?)))))


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