# This is a -*- Tcl -*- script.
#
# translator.tcl --- InfoPrism::Translator class documentation
#
# Copyright (C) 1998, 1999 Stefan Hornburg
#
# Author: Stefan Hornburg <racke@gundel.han.de>
# Maintainer: Stefan Hornburg <racke@gundel.han.de>
# Version: 0.0.6
#
# This file 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 2, or (at your option) any
# later version.
# 
# This file 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 this file; see the file COPYING.  If not, write to the Free
# Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.

manual "The Translator Class"
author "Stefan Hornburg" -email racke@gundel.han.de
stamp "Fri Jan  1 21:05:29 1999 MET"

makeindex fn
makeindex cp

include common.tcl

text "SGML applications are represented by instances of the [code Translator]
class within InfoPrism."

toc

h2 "Methods"
dl {
	dt "[withindex fn [code name]]"
	dd "Returns name of output format."
	dt "[withindex fn [code outfile]] [var NODE]"
	dd "Returns output file for the document node NODE or an empty string."
}
h3 "Text Processing"
dl {
	dt "[withindex fn [code quote]] [var TEXT]"
	dd "Replaces [withindex cp {special characters}] within [var TEXT] and
	returns result."
}
h3 "Entities"
dl {
	dt "[withindex fn [code transents]] [var ENT]"
	dd "Translates [withindex cp entity] [var ENT] to the appropriate
	representation for this format."
}
h3 "Translation"
dl {
	dt "[withindex fn [code formatsubmaybe]] [var NODE]"
	dd "Formats descendants of [var NODE] and returns the result unless
	[var NODE] is empty."
}
h3 "Index"
insertindex fn

h2 "Create New Translators"
text "New translators have to be derived from the base class
[code InfoPrism::Translator]. The constructor must call the constructor of
the base class with the name of the output format to which the translator
belongs and pass any arguments to the builtin [code configure] method."
example {package require Trans
namespace eval InfoPrism {namespace eval Example {}}

class InfoPrism::Example::Translator {
	inherit InfoPrism::Translator

	constructor {args} {
		InfoPrism::Translator::constructor example
	} {
		eval configure $args
	}
}
}

h3 "Overriding Methods"
text "Several methods of the base class are just placeholders for
translator-specific implementations. In the most cases it is useful to
override them. One example is [code quote]."

h2 "Concept Index"
insertindex cp