# This is a -*- Tcl -*- script.
#
# rulwrite.tcl --- Documentation for "InfoPrism Ruleset Scripts"
#
# Copyright (C) 1998 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 "InfoPrism Ruleset Scripts"
include common.tcl
stamp "Fri Nov 13 10:57:12 1998 MET"

register "InfoPrism" "Writing Ruleset Scripts" "Rulesets"

makeindex cp
makeindex fn
toc

include rsintro.tcl

h2 "Commands"
h3 "Rulesets"
index cp rulesets
h4 "Virtual Rulesets"
index cp rulesets virtual
text "Elements representing common document components usually have
different names in DTDs. Virtual rulesets are identified by symbolic names
and can be attached to concrete elements later: "
example {
	virtrule paragraph -front paragraph
	grabrule paragraph PARA
}
h3 "Environments"
text "Environments mark a special section of a document. Usually, you enter
the environment with the [code [withindex fn begin]] command in the front
part of a girule and leave it with the [code [withindex fn end]] command in
the back part of a girule:"
pre {
girule "PRE" -front {
	begin verbatim
	return "[newline][newline 1]"
} -back {
	end verbatim
	return "[newline][newline 1]"
}
}
text "Additional arguments may be passed to the [code begin] command. The
arguments of the active instance of the enviroment [var ENVIRON] are
accessible with the [code [withindex fn envargs]] command. Environments,
e.g. [code table] can be nested. [code [withindex fn level]] returns the
nesting depth of an environment."

dl {
	dt "[code [withindex cp indent]]"
	dd "Indents enclosed text. Amount of indentation depends on the
	nesting depth."
	dt "[code [withindex cp hidden]]"
	dd "Excludes descendant nodes from translation."
}
h3 "Text Processing"
dl {
	dt "[code [withindex fn text]] \[[var OPTION] ...\] [var STRING]"
	dd "Formats [var STRING] and returns the result. Inserts
	[withindex cp linebreaks] if
	[link translate {fill column} FILLCOL] is exceeded. This behaviour can
	be disabled by passing the [var OPTION] [code -nobreak]."
}

h2 "Features"
text "Any kind of information a translator needs about a document must be
retrieved independent of the SGML elements used in the document. Instead of
explicitly examining the document a translator queries for results of
[dfn [withindex cp features]]. The [code [withindex fn provide]] command
serves as a way to implement a certain feature. The following example shows
the implementation of the [code indices] feature for the document type
[link manual Manual]:"
example {provide indices {doc} {
	foreach node [$doc gilist MAKEINDEX] {
		set indices([$node attval NAME]) [Index $node]
	}
	return [array get indices]
}
}
text "The implementation is responsible for the correct format of the
information it supplies. The following features may be provided: "
dl {
	dt [withindex cp stylesheets]
	dd ""
	dt "[index cp language] deflang"
	dd "Default language of the document."
	dt [withindex cp authors]
	dd "Authors of the document supplied as Author objects."
	dt [withindex cp nodenames]
	dd ""
	dt [withindex cp defindices]
	dd ""
	dt [withindex cp indices]
	dd "Document indices."
	dt [withindex cp bibliographies]
	dd "Bibliographies within the document."
	dt [withindex cp stamps]
	dd "Time stamps for document nodes, usually sectioning elements,
	supplied as Stamp objects."
	dt [withindex cp registerentry]
	dd "Categorizing information."
#	The result should be
#	list of [withindex cp category] and
#	[withindex cp entry]/[withindex cp description] pairs
#	like " {{{GNU Emacs Lisp} {{Emacs/W3} {Emacs/W3 World Wide Web browser}}
# {World Wide Web} {{Emacs/W3} {Emacs/W3 World Wide Web browser}}}} 
}

h2 "Auxiliary Functions"
text "A rule script may define any number of auxiliary functions with the
[code [withindex fn auxproc]] command. However, you should not use any of
the following auxiliary function names in a context other than described
below."
dl {
	dt "[code [withindex cp secup]] [var NODE]"
	dd "Returns the next ancestor of NODE which is a sectioning element."
}
example {auxproc secup {node} {
	set up [$node seek "cget -up" "cget -gi" SECTION]
	if ![llength $up] {set up [$node seek "cget -up" "cget -gi" MANUAL]}
	set up
}
}
h2 "Reference Implementation"
text "This section provides some information about the output generated by
the ruleset scripts included by the distribution."

h3 "HTML"
h4 [label style Stylesheets]
table {
	row Command "SGML element" "Class name"
	row [code navbar] "[code <LINK>] within preamble" navbar
}

h2 "Index of Commands"
insertindex fn

h2 "Index"
insertindex cp