# This is a -*- Tcl -*- script.
#
# sbl.tcl --- Documentation for "SGML scripting"
#
# 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 "SGML Scripting"
stamp "Mon Dec 21 02:58:55 1998 MET"
makeindex cp
makeindex fn

register "InfoPrism" "Writing SGML Scripts" "SGML Scripting" 
register "SGML" "Writing SGML Scripts with InfoPrism" "SGML Scripting" 

include common.tcl

text "I suppose that most programmers and several other people would like to
write their documents similar to scripts rather than as plain SGML files.  
[htmlurl infism.html InfoPrism] allows this for documents with the document
type [htmlurl manual.html Manual] and the scripting language
[htmlurl http://www.tcltk.com/ Tcl] resp.
[htmlurl http://www.tcltk.com/itcl/ {[incr Tcl]}]. This document describes
SGML scripting with InfoPrism and the additional commands you have to
learn."
toc

h2 "Important Notes"
text "The [withindex cp {command set}] and the syntax is similar to those of
ordinary scripts written for \[incr Tcl\] version 3.0a1. However, SGML
scripts are processed by a safe interpreter."
h2 "Document Structure"
h3 "Title"
text "The first command in any SGML script is the
[code [withindex fn manual]] command with
the document title as argument. Additional options are: "
dl {
	dt "[code -lang] [var CODE]"
	dd "Specifies the document language. Recognized are [code DE] and
	[code EN]."
}
h2 "Other Global Commands"
text "Global commands affect the whole document and may appear anywhere in
the document."
dl {
	dt "[index cp author] [code [withindex fn author]]
	\[[code -email] [var ADDRESS]\] [var NAME]"
	dd "Specifies the author of the document. Optionally the email
	[var ADDRESS] of the author may be given."
	dt "[index cp keywords] [code [withindex fn keywords]] \[[var NAME]
	...\]"
	dd "Specifies keywords related to the document."
	dt "[code [withindex fn stylesheet]] [var URL] \[[var TYPE]]"
	dd "Specifies a [withindex cp stylesheet] for rendering the output
	document."
}
h2 "Sections"
index cp section
index fn h2
index fn h3
index fn h4
index fn h5
index fn h6
text "Sectioning commands are, in descending order, [code h2], [code h3],
[code h4], [code h5] and [code h6]. The argument is used as section
[withindex cp title]."
p
text "Additional options are: "
dl {
	dt "[code -descr] [var TEXT]"
	dd "Use [var TEXT] as long section name."
	dt "[code -label] [var NAME]"
	dd "Attach label [var NAME] to section."
}
h2 "Additional Control Structures"
index cp "control structures" "additional"
dl {
	dt "[code [withindex fn include]] [var FILE]"
	dd "Works similar to the vanilla Tcl command
	[code [withindex fn source]]."
}
h2 "Lists"
h3 "Unordered Lists"
index fn ul
index fn li
index cp lists unordered
pre {ul {
    li cats
    li dogs
}
}
ul {
	li cats
	li dogs
}
h3 "Ordered Lists"
index fn ol
index cp lists ordered
pre {ol {
    li [code ./configure]
    li [code make]
    li [code make install]
}
}
text "Software packages adhering to the GNU standards can be easily
installed with the following commands:"
ol {
	li [code ./configure]
	li [code make]
	li [code make install]
}

h3 "Definition Lists"
index fn dl
index fn dd
index fn dt
text "Definition lists are lists where each item consists of a
[dfn [withindex cp term]] and a [dfn [withindex cp description]]."

h3 "Composed List Items"
index cp lists nested
index cp "nested lists"
text "The syntax of the Tcl language makes it difficult to script nested
lists and complex items. In this section we describe a set of commands
used as remedy for this problem: "
dl {
	dt [withindex fn liwul]
	ddwex "Unordered list within an ordinary list item: " {liwul "Some animals are: " {
	li "cats"
	li "dogs"
}
	}
	dt [withindex fn ddwul]
	dd "Unordered list within a description list item."
	dt [withindex fn ddwdl]
	dd "Description list within a description list item."
	dt [withindex fn ddwex]
	dd "Example within a description list item."
}

h2 "Tables"
index cp table
text "Tables can be created with the [code table] and [code row] commands."
dl {
	dt "[code [withindex fn table]] [var SCRIPT]"
	dd "Evaluates [var SCRIPT] and creates a table with the result as it
	contents."
	dt "[code [withindex fn row]] \[[var COLUMN] ...\]"
	dd "Creates table row from [var COLUMN] arguments."
}
example {
table {
	row Name Age
	row Stefanie 18
	row Christine 16
	row Ulla 32
}
}
table {
	row Name Age
	row Stefanie 18
	row Christine 16
	row Ulla 32
}
h2 "Text Markup"
h3 "Entities"
index cp entities
text "You can use the [code [withindex fn ent]] command to generate
entities:"
example {text "[ent copy] 1998 by Stefan Hornburg"}
text "[ent copy] 1998 by Stefan Hornburg"
h3 "Preformatted Text"
index cp preformatted
text "The [code [withindex fn pre]] and [code [withindex fn example]]
commands marks the enclosed text as preformatted."
pre {pre "Preserved =>    <= blanks"}
pre "Preserved =>    <= blanks"

h2 "Cross-References"
index cp reference
index cp cross-reference
dl {
	dt "[code [withindex fn label]] [var KEY] [var TEXT]"
	dd "Marks TEXT as target for references to KEY."
	dt "[code [withindex fn ref]] [var KEY] [var TEXT]"
	dd "TEXT refers to KEY."
}
h2 "Indices"
text "Each index has to be declared with the [code [withindex fn makeindex]]
command. [code [withindex fn insertindex]] inserts the index into the
document. Index entries are generated by the [code [withindex fn index]] and
[code [withindex fn withindex]] commands."
example {makeindex animals
text "Famous animals living in the sea are the [withindex animals whale]
and the [withindex animals dolphin]."
insertindex animals
}
makeindex animals
text "Famous animals living in the sea are the [withindex animals whale]
and the [withindex animals dolphin]."
insertindex animals
h2 "Miscellaneous"
dl {
	dt "[code [withindex fn img]] [var SRC] \[[var ALT]\]"
	dd "Inserts image located at [var SRC]. It it recommended to pass an
	string [var ALT] containing an short description of the image."
}

h2 "Undocumented Commands"
ul {
	li [withindex fn br]
	li [withindex fn code]
	li [withindex fn dfn]
	li [withindex fn em]
	li [withindex fn email]
	li [withindex fn htmlurl]
	li [withindex fn item]
	li [withindex fn link]
	li [withindex fn navbar]
	li [withindex fn newsurl]
	li [withindex fn p]
	li [withindex fn register]
	li [withindex fn stamp]
	li [withindex fn text]
	li [withindex fn toc]
	li [withindex fn url]
	li [withindex fn var]
}
h2 "Index of Commands"
insertindex fn
h2 "Concept Index"
insertindex cp