File: simple.html

package info (click to toggle)
cost 2.2p1-3
links: PTS
area: main
in suites: woody
size: 1,032 kB
ctags: 1,728
sloc: ansic: 12,123; tcl: 2,702; sh: 209; makefile: 161
file content (226 lines) | stat: -rw-r--r-- 7,886 bytes
parent folder | download | duplicates (2)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- This file was automatically generated.  DO NOT EDIT BY HAND. -->
<HTML>
<HEAD>
<TITLE>Simple translations with Cost</TITLE>
<META NAME=Creator CONTENT="Cost 2.1a1">
<LINK REV=MADE HREF="mailto:joe@flightlab.com">
</HEAD>
<BODY>
<DIV CLASS=header><H1 CLASS=title>Simple translations with Cost</H1>
<P>Joe English<BR><I>Last updated: Sunday 27 June 1999, 15:31 PDT</I></DIV><HR>
<UL CLASS=TOC>
<LI CLASS=TOCENTRY><A HREF="#SECT1">1 Introduction</A>
<LI CLASS=TOCENTRY><A HREF="#SECT2">2 Getting started</A>
<LI CLASS=TOCENTRY><A HREF="#SECT3">3 Other utilities</A>
<LI CLASS=TOCENTRY><A HREF="#SECT4">4 Example</A>
<LI CLASS=TOCENTRY><A HREF="#SECT5">5 Notes</A>
</UL><HR>
<H2><A NAME=SECT1>1 Introduction</A></H2>
<P>Cost is a powerful but somewhat complex system.
The <SAMP>Simple</SAMP> module provides a simplified,
high-level interface for developing translation specifications.

<H2><A NAME=SECT2>2 Getting started</A></H2>
<P>A large number of SGML translation tasks involve nothing more than
<UL><LI>inserting some text around each element,</LI><LI>replacing each <SAMP>SDATA</SAMP> entity reference with a suitable
output format representation, and</LI><LI>``escaping'' certain characters or sequences
of characters that might be interpreted as markup in the
target language.</LI></UL>
<P>The <SAMP>Simple</SAMP> module is designed to handle these types of translations.
It makes a single pass through the document,
inserting text and optionally calling a user-specified script
at the beginning and end of each element.
The translated document is written to standard output.
<P>To load this module, put the command
<PRE>
require Simple.tcl
</PRE>
at the beginning of the specification script.
Next, define a <EM>translation specification</EM> as follows:
<PRE>
specification translate {
    <I>specification-rules...</I>
}
</PRE>
<P>The <I>specification-rules</I> is a paired list
matching <EM>queries</EM> with <EM>parameter lists</EM>.
The queries are used to select element nodes,
and are typically of the form
<PRE>
    {element <I>GI</I>}
</PRE>
or
<PRE>
    {elements "<I>GI</I> <I>GI</I>..."}
</PRE>
where each <I>GI</I> is the generic identifier or element type name
of the elements to select.
<P>Any Cost query may be used, including complex rules like
<PRE>
    {element TITLE in SECTION withattval SECURITY RESTRICTED}
</PRE>
or simple ones like
<PRE>
    {el}
</PRE>
The latter query -- <SAMP>el</SAMP> -- matches all element nodes;
it can be used to specify default parameters for elements which
don't match any earlier query.
<P>The parameter lists are also paired lists,
matching <EM>parameters</EM> to <EM>values</EM>.
The <SAMP>Simple</SAMP> module translation process
uses the following parameters:<DL><DT><SAMP>before</SAMP></DT><DD>Text to insert before the element
    (before evaluating <SAMP>startAction</SAMP>)</DD><DT><SAMP>startAction</SAMP></DT><DD>Tcl statements to execute at the beginning of the element</DD><DT><SAMP>prefix</SAMP></DT><DD>Text to insert at the beginning the element
    (after evaluating <SAMP>startAction</SAMP>)</DD><DT><SAMP>suffix</SAMP></DT><DD>Text to insert at the end of the element
    (before evaluating <SAMP>endAction</SAMP>)</DD><DT><SAMP>endAction</SAMP></DT><DD>Tcl statements to execute at the end of the element</DD><DT><SAMP>after</SAMP></DT><DD>Text to insert after the element
    (after evaluating <SAMP>endAction</SAMP>)</DD></DL><P>Tcl variable, backslash, and command substitution
are performed on the
<SAMP>before</SAMP>, <SAMP>after</SAMP>, <SAMP>prefix</SAMP>, and <SAMP>suffix</SAMP>
parameters.
This takes place when the element is processed,
not when the specification is defined.
The value of these parameters are <EM>not</EM> passed
through the <SAMP>cdataFilter</SAMP> command before being output.

<P CLASS=NOTE>NOTE -- Remember to ``protect'' all Tcl special characters
by prefixing them with a backslash
if they are to appear in the output.
The special characters are:
dollar signs <SAMP>$</SAMP>,
square brackets <SAMP>[]</SAMP>,
and backslashes <SAMP>\</SAMP>.
See the Tcl documentation on the <B>subst</B> command
for more details.<DL><DT><SAMP>cdataFilter</SAMP></DT><DD>A <EM>filter procedure</EM> for character data</DD><DT><SAMP>sdataFilter</SAMP></DT><DD>A filter procedure for system data (<SAMP>SDATA</SAMP> entity references).</DD></DL><P>The <SAMP>cdataFilter</SAMP> parameter is the name of a <EM>filter procedure</EM>.
This is a one-argument Tcl command.
Cost passes each chunk of character data to this procedure,
and outputs whatever the procedure returns.
The initial value of <SAMP>cdataFilter</SAMP> is the <B>identity</B>
command, which simply returns its input:

<PRE>
proc identity {text} {return $text}
</PRE>
<P>The <SAMP>sdataFilter</SAMP> parameter works just like
<SAMP>cdataFilter</SAMP>, except that it is used for <EM>system data</EM>
(the replacement text of <SAMP>SDATA</SAMP> entity references.)
The initial <SAMP>sdataFilter</SAMP> is also <B>identity</B>.
<P>The <SAMP>cdataFilter</SAMP> and <SAMP>sdataFilter</SAMP> parameters
are inherited by subelements;
that is, if they are not specified for
a particular element then the currently active filter procedure
will be used by default.

<H2><A NAME=SECT3>3 Other utilities</A></H2>
<P>The <B>translateContent</B> procedure works just like
the Cost built-in command <B>content</B>,
except that the content of <SAMP>CDATA</SAMP> and <SAMP>SDATA</SAMP> nodes
are filtered through the current
<SAMP>cdataFilter</SAMP> and <SAMP>sdataFilter</SAMP>, respectively.

<H2><A NAME=SECT4>4 Example</A></H2>
<P>The following specification translates
a subset of HTML to nroff -man macros.
(Well, actually it doesn't do anything useful,
it's just to give an idea of the syntax.)

<PRE>
require Simple.tcl

specification translate {
	{element H1} {
		prefix 	"\n.SH "
		suffix 	"\n"
		cdataFilter	uppercase
	}
	{element H2} {
		prefix 	"\n.SS "
		suffix 	"\n"
	}
	{elements "H3 H4 H5 H6"} {
		prefix "\n.SS"
		suffix "\n"
		startAction {
		    # nroff -man only has two heading levels
		    puts stderr "Mapping [query gi] to second-level heading"
		}
	}
	{element DT} {
		prefix	"\n.IP \""
		suffix	"\"\n"
	}
	{element PRE} {
		prefix "\n.nf\n"
		suffix "\n.fi\n"
	}
	{elements "EM I"} {
		prefix "\\fI"
		suffix "\\fP"
	}
	{elements "STRONG B"} {
		prefix "\\fB"
		suffix "\\fP"
	}

	{element HEAD} {
		cdataFilter nullFilter
	}
	{element BODY} {
		cdataFilter nroffEscape
	}
}

proc nullFilter {text} {
    return ""
}

proc nroffEscape {text} {
    # change backslashes to '\e'
    regsub -all {\\} $text {\\e} output
    return $output
}

proc uppercase {text} {
    return [nroffEscape [string toupper $text]]
}

</PRE>


<H2><A NAME=SECT5>5 Notes</A></H2>
<P>The specification order is important: queries are tested in
the order specified, so more specific queries must appear before
more general ones.
<P>Parameters are evaluated independently of one another.
For example,
<PRE>
specification translate {
    {element "TITLE"} {
	cdataFilter uppercase
    }
    {element TITLE in SECT in SECT in SECT} {
	prefix "&lt;H3&gt;"
	suffix "&lt;/H3&gt;\n"
    }
    {element TITLE in SECT in SECT} {
	prefix "&lt;H2&gt;"
	suffix "&lt;/H2&gt;\n"
    }
    {element TITLE in SECT} {
	prefix "&lt;H1&gt;"
	suffix "&lt;/H1&gt;\n"
	startAction {
	    puts $tocfile [content]
	}
    }
}
</PRE><P>The parameter <SAMP>cdataFilter uppercase</SAMP> applies to
all <TT>TITLE</TT> elements, regardless of where they occur,
and the <SAMP>startAction</SAMP> parameter applies to any
<TT>TITLE</TT>s which are children of a <TT>SECT</TT>,
even if an earlier matching rule specified a <SAMP>prefix</SAMP>
or <SAMP>suffix</SAMP>.

<P>As its name implies, the <SAMP>Simple</SAMP> module is not very
sophisticated, but it should be enough to get you started.
</BODY></HTML>