Text and Html statements: Difference between revisions

Latest revision as of 20:27, 17 March 2016

The Html or Text statement

The Html (or Text) statement in User Language is a general purpose alternative to a series of Print statements for producing a fair amount of literal data. Primarily for use with Janus Web Server (hence the name Html), it is available with many Sirius products. It is most useful when Print output is captured or directed by some means. It is also quite useful for populating a Stringlist with a large amount of mostly constant text. This latter capability is provided by the To option of the Html/Text statement.

In this section, "Html block" refers to either the Html or Text block.

The Html block can be used to produce print output of largely literal or static data. For example, sending output to a browser with Janus Web Server often requires a significant quantity of static text for HTML directives. Rather than placing this static data inside quotes in a Print statement, the Html block will automatically assign text as print output. Any Model 204 expression, including simple %variable values or $function invocations, can be placed inside an Html block, as long as it is enclosed inside the expression start and end characters. The default start and end characters are the curly brackets ({) and (}).

The following is an example of an Html statement specification:

html <form method="POST" action="processform"> <br> Last name: <input type="text" name="lname" value="{%LNAME}"> </form> end html

The syntax of the Html and Text blocks is shown below:

Html [options] body block_end_line

or

Text [options] body block_end_line

options, body, and block_end_line are discussed below.

The components of the Html or Text block are discussed in the following sections. The Html (or Text) block can be used in contexts other than the production of a web page. For example, it can be used:

To store lines in a temporary procedure or sequential dataset, using the USE command
To populate a Stringlist, using the To option on the Html/Text statement
To populate a $list, using the $List_Capture function
To send lines over a Janus Sockets connection, using the $Sock_Capture function
To prepare output processed by some other program, when the output is created by something like a BATCH2 or RCL connection to Model 204

Here are some advantages of the Html/Text block:

User Language is visually close to the output.
Literal text does not need to be enclosed in apostrophes.
The Print keyword is not necessary.
Any valid Model 204 expression can be included inside an Html block, not just literals, %variables, fieldnames, $functions, and a few other constructs.
The With and And keywords are not needed between expressions.
Apostrophes do not need to be doubled, as in:
print 'Just say ''No'''

The following is an example of an Html block using JavaScript to illustrate applications of the Html/Text options:

html nocont exprs '!{' expre '}!' <html> <head> <title>My Javascript Page</title> </head> !{$sir_date('Wkd Mon DD YYYY HH:MI:SS')}! <br> <body> <script>  </script> </body> </html> end html

Html statement options used in this example:

Nocont is used to turn off continuations signified by trailing dashes. In the JavaScript, dashes are used in an input line that prevents browsers without JavaScript from displaying script as literal output.
Exprs and Expre let you use characters other than the curly brackets ({ }) to demarcate expressions. The curly bracket characters are necessary in JavaScript.

The Html block is available to any customer who owns any of the following products:

Fast/Unload User Language Interface
Janus SOAP
Janus Sockets
Janus Web Server
Sirius Functions

The Html block is also available if the Limited Janus Web Server capability is available.

Options: Html or Text block options

The various options for an Html or Text block are introduced after the Html or Text keyword. They are described in the following subsections.

Data, Print, Audit, or Trace

These keywords indicate that the Html block consists of only the text that follows the keyword on the logical line: that is, there is no End Html statement to end the block. The Print, Audit, and Trace keywords provide the same functionality as the PrintText, AuditText, TraceText statements. These statements, along with ReturnText, and SetText (which don't have Text/Html statement keyword equivalents) are sometimes called targeted Text statements.

Prior to Sirius Mods version 7.2, only the Data keyword had this effect, and the Print, Audit, and Trace keywords did not exist. The ReturnText and SetText stetements were added to the Text statement in Sirius Mods version 7.8.

Any Html statement keywords that appear after a Data, Print, Audit, or Trace keyword are processed not as keywords but simply as text. If you want to specify keywords in addition to a Data, Print, Audit, or Trace keyword, they must appear before Data, Print, Audit, or Trace to be treated as a keyword.

All other Html block processing, including expression processing, is performed on the line as if it were inside an Html block. The exception is Nodummy processing, because dummy string replacement is performed before the Html statement is parsed.

Data or Print

Either of these keywords can be thought of as providing a single-line Html/Text statement which can still be much easier to type and read than a User Language Print statement, as in:

html data Don't need to worry about apostrophes text print {%i} + {%j} = {%i + %j}

The following is an equivalent alternative to the second statement in the preceding example:

PrintText {%i} + {%j} = {%i + %j}

The PrintText statement has the same effect as a Text Print statement. The PrintText keyword is simply a merging and reordering of Text Printto emphasize the principle action. The lone difference between PrintText and Text Print is that PrintText cannot be used if you want to include other Html/Text options, as in:

text noexpr print The set is {2, 3, 5, 8, 13, ...}

The Print keyword and the PrintText statement are available in Sirius Mods 7.2 and later.

Audit

This keyword provides a single-line Html/Text statement that functions like a User Language Audit statement, that is, routing subsequent text to the audit trail.

For example, this statement directs the text content to the audit trail:

text audit It ({$time}) was the best of times

The following is an equivalent alternative to the preceding example.

AuditText It ({$time}) was the best of times

As with the PrintText keyword above, the AuditText statement has the same effect as a Text Audit statement, except it cannot be used if you want to include additional Html/Text Options.

The Audit keyword and the AuditText statement are available as of Sirius Mods 7.2.

Trace

This keyword provides a single-line Html/Text statement that is the same as a User Language Trace statement, that is, routing subsequent text to the trace destination (which may be the audit trail, print device, or CCATEMP trace table, or a combination of them, as specified in the ULTRACE parameter). For example, this statement directs the text content by default to the audit trail:

text trace This day ({$date}) is unlike any other

The following is an equivalent alternative to the preceding example.

TraceText This day ({$date}) is unlike any other

As with the PrintText keyword above, the TraceText statement has the same effect as a Text Trace statement, except it cannot be used if you want to include additional Html/Text options. The Trace keyword and the TraceText statement are available as of Sirius Mods version 7.2.

Ent_print

The Ent_print keyword overrides the current $Ent_Print setting for character entity translation over the Html block. Ent_print must be followed by one of these keywords:

`Off`	No character entity translation will occur over the Html block.
`On`	All data printed by the Html statement will undergo character entity translation.
`Var`	Only the results of expressions will undergo character entity translation.

Character entity translation is the process of converting a single character that might be problematic in certain contexts to a more verbose but non-problematic equivalent. For example, if a "less than" sign (<) appears in HTML text, it should typically be represented as < to prevent an HTML processor from mistakenly interpreting it as the start of an HTML tag.

When entity translation is performed, the default translations are "ampersand" (&) to &, "less than" (<) to <, and "double quotation mark" (") to ". These defaults should be sufficient for most HTML and XML applications (though XML might also require translation of the single quotation mark character (') to ' if attributes are enclosed in single quotation marks, but they can be modified with the $Ent_Tab function.

The Ent_print keyword is a compile-time option that affects only what is inside the Html block and that is not affected by evaluation time setting of $Ent_Print, even within the Html block. If no Ent_print keyword is present on the Html statement, character entity translation is controlled by the evaluation-time $Ent_Print setting.

LiteralsToTemp

The LiteralsToTemp option indicates that the literal data in the statement is stored in CCATEMP rather than STBL, avoiding excessive demands on STBL space. Designed for a Text statement with an unusually large amount of literal data, this is an alternative to setting the X'01' bit of the SIRCOMP user parameter (which performs the same function).

Nocom or Nocomments

The Nocomments (abbreviated Nocom) option indicates that lines beginning with an asterisk (*) are not comment lines. For example:

HTML NOCOM * This line will go to the output END HTML

Nocont or Nocontinuations

The Nocontinuations (abbreviated Nocont) option causes trailing dashes to cease being treated as line continuations. For example, the following statement will cause the output to appear on two separate lines:

HTML NOCONT English: B- Social Studies: C END HTML

Nodum or Nodummy

The Nodummy (abbreviated Nodum) option stops dummy string substitution. For example, the following statement will cause the literal string ?&W to be output without global variable substitution:

HTML NODUM Hello, ?&W END HTML

Noell or Noellipses

With the Noellipses (abbreviated Noell) option, a trailing ellipsis (...) is not treated as a concatenation operator. For example:

HTML NOELL These lines are not joined... They will appear on different lines. END HTML

Noexpr or Noexpressions

If you do not want expression substitution, specify Noexpr or Noexpressions. For example:

HTML NOEXPR {This will be sent directly to output} END HTML

Raw

The Raw option acts as Nocom, Nocont, Nodum, Noell, and Noexpr all at once.

Noend

The Noend option eliminates the block end line. Thus, the block will terminate at the end of the procedure. For example:

PROC FOO HTML NOEND Now we are in HTML. END HTML Still in HTML. END PROC

Exprs or Exprstart

The Exprstart (abbreviated Exprs) option specifies a string, up to three characters long, that begins an expression within the block body. The default is a left curly brace ({). For example:

html exprs go expre stp The answer is go8*9stp end html

It is probably best to use start and end sequences that are not likely to occur in the literal text in the Html/Text block and that clearly demarcate expressions from literal text. The go and stp in the example above are actually not very good choices.

If the expression start string occurs in the input text, you can "double" the expression start string, instead of using the Exprs option. For example:

html <script> {{alert("User error")} </script> end html

Note that because the double open-curly-brace ({{) is not treated as an expression start, the close-curly-brace (}) is not treated as an expression end, since the compiler is not processing an expression where it appears. This illustrates the point that generally there is no need to change the expression end character as its presence is irrelevant in non-expression contexts and an unquoted close-curly-brace cannot occur in a User Language expression. Probably the only compelling reason to change the expression end characters is aesthetics or readability — one might want the expression end to mirror the expression start.

html exprs '{<' expre '>}' <script> var foobar = "{<%foobar>}" if (foobar == '') {alert("Need a value for foobar")} <script> end html

One can even use the same set of characters as expression start and end characters:

html exprs // expre // <script> var foobar = "//%foobar//" if (foobar == '') {alert("Need a value for foobar")} <script> end html

The above example is simply intended to illustrate a point and should not be considered a recommendation.

Note: If you use multiple special characters to demarcate expressions, you are advised to enclose those characters in single quotation marks (as above) in your Exprs and Expre specifications. Otherwise, multiple-character combinations involving certain special characters (including these six, for example: = , ( ) < > ) cause M204.0580 errors.

Expre or Exprend

The Exprend (abbreviated Expre) option specifies a string that ends an expression within the block body. The default is a right curly brace (}).

End

To set your own block_end_line, you can use the End option. For example:

text to %list end listEnd Four score and seven listEnd

If the text of the line you are specifying contains spaces, enclose it in single quotation marks. For example:

text to %list end 'end text block' Our forebears end text block

The default block_end_line value is End Html (for the Html block) or End Text (for the Text block).

To %stringlist, To Audit, To Print, or To Trace

The To option lets you direct the contents of the Html or Text block to a Stringlist or to the destinations associated with the User Language statements Audit, Print, or Trace.

To %stringlist [= New]

The To option, when used to add data to a Stringlist, has an optional = New clause following the Stringlist, which first creates a new Stringlist instance. Without = New, the data is appended to the Stringlist.

Here is how Text To populates a Stringlist with some names:

%jumps is object stringList ... text to %jumps = new Axel Flip Lutz Salchow Toe Loop Wally end text

The text to %jumps = new statement above is an optional simplification (as of Sirius Mods version 7.6) of the sequence:

%jumps = new text to %jumps

There are many advantages to using Html To or Text To over a plain Html statement wih $List_Capture:

$List_Capture or an equivalent is not available for Stringlists.
Because Html To does not go through generic Print processing, it has a somewhat more efficient processing path, that is, it uses less CPU.
Because Html To does not go through generic Print processing, the generated quads take somewhat less space.
An Html To block does not affect the current $List_Capture setting, so it eliminates the need to worry about saving and restoring the $List_Capture setting.
A To option on an Html statement is simply less and cleaner code than an Html statement inside a $List_Capture bracket.
If an expression inside an Html To block invokes a User Language method, and that method does a Print statement, the output of that Print statement does not end up on the Stringlist target of the Html statement. Inside a $List_Capture bracket, the output of such a Print statement ends up on the $List_Capture's target $list.

The To option of the Html or Text statement appends to the target Stringlist, so it does not instantiate the Stringlist if it is null. In fact, a null Stringlist target for an Html To results in a null-pointer request-cancelling error.

Even if the ultimate target of an Html or Text statement is a plain $list, the Html To can still be used to gain some of the benefits of this structure without much extra code by using the Stringlist object MoveFromId and MoveToId methods:

%htmlList is object stringList %list is float ... %list = $listNew ... %htmlList = new %htmlList:modeFromId(%list) text to %htmlList This gets added to the $list. end text %htmlList:modeToId(%list)

To Audit, To Print, To Trace

These options direct the contents of an Html or Text block or line to the destinations associated with the User Language statements Audit, Print, or Trace. Respectively these destinations are the journal/audit trail, the current print output device, or the trace destination (which may be the audit trail, print device, or CCATEMP trace table, or a combination of them).

For example, the following statement directs the Text block content to the audit trail:

text to audit Now ({$time}) is the time for all good men to come to the aid of their company. end text

To direct a single line of output, you can use the Data keyword ("Data, Print, Audit, or Trace") as in the following:

text to audit Data It ({$time}) was the best of times

Or, simpler, you can use the Audit keyword like this:

text Audit It ({$time}) was the best of times

Furthermore, the targeted Text statements provide an alternative syntax, in which the "target" (Print, Audit, Trace) is at the start of the statement, making them more "natural" analogues of the Print, Audit and Trace statements. For example:

auditText It ({$time}) was the best of times

Body: Html or Text block body

Each line of an Html or Text block, up to the block_end_line, creates a line of literal output, with the following substitutions:

Expressions	An expression is begun by a left brace ({) or a user-defined string specified with the `Exprs` option, and it is ended by a right brace (}) or a user-defined string specified with the `Expre` option. Text within the expression is evaluated as if it were the right-hand side of a `User Language` assignment; that value is produced, rather than literal output.
Dummy strings	Normally, as in other `Model 204` input, dummy strings are substituted under the control of the `SUB` parameter. This can be suppressed with the `Nodummy` option, which may be useful if your block contains strings like "what the heck??!!".
Continuation	Continuation allows text from multiple lines to be printed on one line by adding a hyphen (-) to all preceding lines in the block. All spacing and indentation following the hyphen is ignored. This option works inside an expression.
Ellipses	Ellipses allow text from multiple command lines to be printed on one line by adding three dots (...) to all preceding command lines. Leading spaces will be included. This option will not work inside an expression.
Indentation	Except for continuation lines, the output of a line is indented by as many spaces as the input is indented relative to the `Html` or `Text` statement that begins the block.

block_end_line: Html or Text block end

By default, the line that ends an Html or Text block is End Html for an Html block, or it is End Text for a Text block. You can specify your own end line with the End option, as described above in End.

Printing of expression results

Model 204 expressions enclosed in the expression start and end characters are printed as if the result of the expression were placed literally in the place of the expression in the HTML block. For example, Text Print {$date} produces a result like 08-02-29.

Character entity substitution

The result of the expression might undergo character entity substitution under control of the $Ent_Print setting or the Ent_print parameter on the Html/Text statement. An expression can explicitly override the default $Ent_Print and Ent_print processing by immediately following the expression start character(s) with one of the following special characters:

&	Perform character entity substitution regardless of the current `$Ent_Print` setting and the `Ent_print` setting on the `Html` statement.
!	Do not perform character entity substitution, regardless of the current `$Ent_Print` setting and the `Ent_print` setting on the `Html` statement.
*	Do not print the results of the expression. This can be useful if embedding a $function that itself prints output, such as `$List_Print` or `$Web_Sel`, or a $function that simply sets some environmental parameter (such as `$Web_Set` or `$Resetn`) whose return value should not be displayed.

Note: The asterisk (*) suppresses the printing of the return code but not the output from a $List_Print or $Web_Sel function.

In the following example, character entity substitution is explicitly suppressed for the contents of %FONT and explicitly forced for %COMMENT, and the return code from $LIST_PRINT is suppressed:

HTML {!%FONT}This is in a fancy font</font> <input type="text" name="comment" value="{&%COMMENT}"> <br>And here's some stuff<br> {*$LIST_PRINT(%LIST)} END HTML

The {~} and {~= ...} directives

The special expression {~} directs the compiler to replace this expression with the literal character content of the next expression appearing on the same line. So:

printText {~} = {1234:nextPrime}

displays:

1234:nextPrime = 1237

The evaluation of the expression following {~} is carried out as usual. As of Sirius Mods 7.8, you can also specific a ~= directive, as in:

printText {~=1234:nextPrime}

This displays:

1234:nextPrime=1237

The expression after the ~= directive can be preceded or followed by blanks. Blanks before the expression appear in the output before the expression result (after the equal sign), and spaces after the expression appear in the output after the expression literal (before the equal sign). For example,

printText {~= 100:nextPrime }

displays:

100:nextPrime = 101

If more control of spacing is required, the simple {~} directive should be used, instead.

As mentioned at the end of the To Audit, To Print, To Trace section above, the PrintText statement is a synonym for the Text Print statement.

Table usage

While the Html/Text statement can provide a convenient typing shorthand relative to a host of Print statements, and it can make code considerably more readable, it does not necessarily use any less table space than the comparable Print statements.

Table space can be saved with the Html/Text statement, as follows:

By using the To clause and sending the Html/Text statement output directly to a Stringlist, the amount of QTBL space used is reduced.
If the X'01' bit is set in the SIRCOMP user parameter when a program is compiled, string literals are saved in CCATEMP rather than STBL. Since Html/Text statements often have a large quantity of literal text, they can use a lot of STBL space, so the STBL space savings of the SIRCOMP X'01' bit can be great. The drawback to having string literals in CCATEMP rather than STBL is that the access path to the data is somewhat longer, that is, slightly more CPU is required to access it. When the Html/Text statement uses a To clause, the extra overhead of CCATEMP data access is reduced, because Html/Text To processing keeps the CCATEMP pages holding literal data open over as many literals as possible.
Furthermore, for pre-compiled APSY procedures, the literals in CCATEMP do not need to be APSY loaded, and they are shared among all users of a procedure. Finally, if a user with a large number of Html/Text statement literals is server-swapped, there is less data to server-swap if literals are kept in CCATEMP (although, the data in CCATEMP does take buffer pool space and might require CCATEMP I/O).

So there is probably no good general rule of thumb regarding whether the SIRCOMP X'01' bit should be set. Probably, unless a site is struggling with server size problems, it is best and simplest to just keep the literals in STBL.

Text and Html statements: Difference between revisions

Latest revision as of 20:27, 17 March 2016

Contents

The Html or Text statement

Options: Html or Text block options

Data, Print, Audit, or Trace

Data or Print

Audit

Trace

Ent_print

LiteralsToTemp

Nocom or Nocomments

Nocont or Nocontinuations

Nodum or Nodummy

Noell or Noellipses

Noexpr or Noexpressions

Raw

Noend

Exprs or Exprstart

Expre or Exprend

End

To %stringlist, To Audit, To Print, or To Trace

To %stringlist [= New]

To Audit, To Print, To Trace

Body: Html or Text block body

block_end_line: Html or Text block end

Printing of expression results

Character entity substitution

The {~} and {~= ...} directives

Table usage

See also

Navigation menu

@@ Line 1: / Line 1: @@
-==The '''HTML''' or '''TEXT''' statement==
+==The Html or Text statement==
-The '''Html''' (or '''Text''') statement in User Language is a general purpose alternative to a
+The <var>Html</var> (or <var>Text</var>) statement in <var class="product">User Language</var> is a general purpose alternative to a
-series of Print statements for producing a fair amount of literal data. Primarily for use
+series of <var>Print</var> statements for producing a fair amount of literal data. Primarily for use
-with Janus Web Server (hence the name Html), it is available with many Sirius
+with <var class="product">Janus Web Server</var> (hence the name <code>Html</code>), it is available with many Sirius
-products. It is most useful when PRINT output is captured or directed by some means.
+products. It is most useful when <var>Print</var> output is captured or directed by some means.
-It is also quite useful for populating a StringList with a large amount of mostly constant
+It is also quite useful for populating a <var>Stringlist</var> with a large amount of mostly constant
-text. This latter capability is provided by the To option of the '''Html/Text''' statement.
+text. This latter capability is provided by the <var>[[#toOption|To]]</var> option of the <var>Html</var>/<var>Text</var> statement.
-In this section, “HTML block” refers to either the '''Html''' or '''Text''' block.
+In this section, "Html block" refers to either the <var>Html</var> or <var>Text</var> block.
-The Html block can be used to produce print output of largely literal or static data. For
+The <var>Html</var> block can be used to produce print output of largely literal or static data. For
-example, sending output to a browser with Janus Web Server often requires a significant
+example, sending output to a browser with <var class="product">Janus Web Server</var> often requires a significant
 quantity of static text for HTML directives. Rather than placing this static data inside
-quotes in a Print statement, the Html block will automatically assign text as print output.
+quotes in a <var>Print</var> statement, the <var>Html</var> block will automatically assign text as print output.
-Any Model 204 expression, including simple %variable values or $function invocations,
+Any <var class="product">Model 204</var> expression, including simple %variable values or $function invocations,
-can be placed inside an Html block, as long as it is enclosed inside the expression start
+can be placed inside an <var>Html</var> block, as long as it is enclosed inside the expression start
-and end characters. The default start and end characters are the curly brackets ( { )
+and end characters. The default start and end characters are the curly brackets (<tt>{</tt>)
-and ( } ).
+and (<tt>}</tt>).
-The following is an example of an '''Html''' statement specification:
+The following is an example of an <var>Html</var> statement specification:
-<pre>
+<p class="code">html
-html
 <form method="POST" action="processform">
-<br>
+&lt;br>
-Last name: <input type="text"
+Last name: <input type="text" name="lname" value="{%LNAME}">
-name="lname" value="{%LNAME}">
 </form>
 end html
-</pre>
+</p>
-The syntax of the '''Html''' and '''Text''' blocks is shown below:
+The syntax of the <var>Html</var> and <var>Text</var> blocks is shown below:
-  Html [options]
+<p class="syntax"><span class="literal">Html</span> <span class="squareb">[</span><span class="term">options</span><span class="squareb">]</span>
-  body
+<span class="term">body
-  block_end_line
+block_end_line</span>
+</p>
-or
+or
-  Text [options]
-  body
+<p class="syntax"><span class="literal">Text</span> <span class="squareb">[</span><span class="term">options</span><span class="squareb">]</span>
-  block_end_line
+<span class="term>body
+block_end_line</span>
-''options'', ''body'', and ''block_end_line'' are discussed below.
+</p>
-The components of the Html or Text block are discussed in the following sections. The Html (or Text) block can be used in contexts other than the production of a web page. For example, it can be used:
+<var class="term">options</var>, <var class="term">body</var>, and <var class="term">block_end_line</var> are discussed below.
-* To store lines in a temporary procedure or sequential dataset, using the USE command
-* To populate a StringList, using the To option on the Html/Text statement
+The components of the <var>Html</var> or <var>Text</var> block are discussed in the following sections. The <var>Html</var> (or <var>Text</var>) block can be used in contexts other than the production of a web page. For example, it can be used:
-* To populate a $list, using the $LIST_CAPTURE function
+<ul>
-* To send lines over a Janus Sockets connection, using the $SOCK_CAPTURE function
+<li>To store lines in a temporary procedure or sequential dataset, using the <var>USE</var> command
-* To prepare output processed by some other program, when the output is created by something like a BATCH2 or RCL connection to Model 204 Here are some advantages of the Html/Text block:
+<li>To populate a <var>Stringlist</var>, using the <var>[[#toOption|To]]</var> option on the <var>Html</var>/<var>Text</var> statement
-* User Language is visually close to the output.
+<li>To populate a <var>[[$lists|$list]]</var>, using the <var>[[$List_Capture]]</var> function
-* Literal text does not need to be enclosed in apostrophes.
+<li>To send lines over a <var class="product">Janus Sockets</var> connection, using the <var>[[$Sock_Capture]]</var> function
-* The Print keyword is not necessary.
+<li>To prepare output processed by some other program, when the output is created by something like a <var>BATCH2</var> or <var>RCL</var> connection to <var class="product">Model 204</var>
-* Any valid Model 204 expression can be included inside an Html block, not just literals, %variables, fieldnames, $functions, and a few other constructs.
+</ul>
-* The With and And keywords are not needed between expressions.
-* Apostrophes do not need to be doubled, as in:
+Here are some advantages of the <var>Html</var>/<var>Text</var> block:
+<ul>
-  print <nowiki>'Just say ''No'''</nowiki>
+<li><var class="product">User Language</var> is visually close to the output.
+<li>Literal text does not need to be enclosed in apostrophes.
-The following is an example of an Html block using JavaScript to illustrate applications of the '''Html/Text''' options:
+<li>The <var>Print</var> keyword is not necessary.
-<pre>
+<li>Any valid <var class="product">Model 204</var> expression can be included inside an <var>Html</var> block, not just literals, %variables, fieldnames, $functions, and a few other constructs.
-html nocont exprs '!{' expre '}!'
+<li>The <var>With</var> and <var>And</var> keywords are not needed between expressions.
+<li>Apostrophes do not need to be doubled, as in:
+<p class="code">print <nowiki>'Just say ''No'''</nowiki> </p>
+</ul>
+The following is an example of an <var>Html</var> block using JavaScript to illustrate applications of the <var>Html</var>/<var>Text</var> options:
+<p class="code">html nocont exprs '!{' expre '}!'
 <nowiki><html>
 <head>
@@ Line 71: / Line 75: @@
 name=prompt("Person's name","Type name here");
 end html
 %s1='if (name=="'
 fr where rectype='PHONE'
@@ Line 78: / Line 82: @@
    %s1='else if (name=="'
 end for
 html nocont exprs '!{' expre '}!'
-  else {alert ("Unkown person")};
+else {alert ("Unkown person")};
-  -->
+-->
-  </script>
+</script>
-  </body>
+</body>
-  </html>
+</html>
 end html</nowiki>
-</pre>
+</p>
-'''Html''' statement options used in this example:
-* Nocont is used to turn off continuations signified by trailing dashes. In the JavaScript, dashes are used in an input line that prevents browsers without JavaScript from displaying script as literal output.
+<var>Html</var> statement options used in this example:
-* Exprs and Expre let you use characters other than the curly brackets ( { } ) to demarcate expressions. The curly bracket characters are necessary in JavaScript.
+<ul>
+<li><var>Nocont</var> is used to turn off continuations signified by trailing dashes. In the JavaScript, dashes are used in an input line that prevents browsers without JavaScript from displaying script as literal output.
-The Html block is available to any customer who owns any of the following products:
+<li><var>Exprs</var> and <var>Expre</var> let you use characters other than the curly brackets (<tt>{ }</tt>) to demarcate expressions. The curly bracket characters are necessary in JavaScript.
-* ''Fast/Unload User Language Interface''
+</ul>
-*'' Janus SOAP''
-* ''Janus Sockets''
+The <var>Html</var> block is available to any customer who owns any of the following products:
-* ''Janus Web Server''
+<ul>
-* ''Sirius Functions''
+<li><var class="product">Fast/Unload User Language Interface</var>
+<li><var class="product">Janus SOAP</var>
+<li><var class="product">Janus Sockets</var>
+<li><var class="product">Janus Web Server</var>
+<li><var class="product">Sirius Functions</var>
+</ul>
+The <var>Html</var> block is also available if the <var class="product">Limited Janus Web Server</var> capability is available.
-The '''Html''' block is also available if the Limited Janus Web Server capability is available.
 ==Options: Html or Text block options==
-The various options for an Html or Text block are introduced after the Html or Text
+The various options for an <var>Html</var> or <var>Text</var> block are introduced after the <code>Html</code> or <code>Text</code>
 keyword. They are described in the following subsections.
 ===Data, Print, Audit, or Trace===
-These keywords indicate that the Html block consists of only the text that follows the
+These keywords indicate that the <var>Html</var> block consists of only the text that follows the
-keyword on the logical line: that is, there is no End Html statement to end the block.
+keyword on the logical line: that is, there is no <var>End Html</var> statement to end the block.
-The Print, Audit, and Trace keywords provide the same functionality as the PrintText, AuditText, TraceText
+The <var>Print</var>, <var>Audit</var>, and <var>Trace</var> keywords provide the same functionality as the <var>PrintText</var>, <var>AuditText</var>, <var>TraceText</var>
-statements. These statements, along with ReturnText, and SetText (which don't have Text/Html statement keyword equivalents) are sometimes called [[Targeted Text statements|targeted Text statements]].
+statements. These statements, along with <var>ReturnText</var>, and <var>SetText</var> (which don't have <var>Text</var>/<var>Html</var> statement keyword equivalents) are sometimes called [[Targeted Text statements|targeted Text statements]].
-Prior to Sirius Mods version 7.2, only the Data keyword had this effect, and the Print,
+Prior to Sirius Mods version 7.2, only the <var>Data</var> keyword had this effect, and the <var>Print</var>,
-Audit, and Trace keywords did not exist. The ReturnText and SetText stetements were added to the Text statement in Sirius Mods version 7.8.
+<var>Audit</var>, and <var>Trace</var> keywords did not exist. The <var>ReturnText</var> and <var>SetText</var> stetements were added to the <var>Text</var> statement in <var class="product">Sirius Mods</var> version 7.8.
-Any Html statement keywords that appear after a Data, Print, Audit, or Trace keyword
+Any <var>Html</var> statement keywords that appear after a <var>Data</var>, <var>Print</var>, <var>Audit</var>, or <var>Trace</var> keyword
 are processed not as keywords but simply as text. If you want to specify keywords in
-addition to a Data, Print, Audit, or Trace keyword, they must appear before Data, Print,
+addition to a <var>Data</var>, <var>Print</var>, <var>Audit</var>, or <var>Trace</var> keyword, they must appear before <var>Data</var>, <var>Print</var>,
-Audit, or Trace to be treated as a keyword.
+<var>Audit</var>, or <var>Trace</var> to be treated as a keyword.
-All other Html block processing, including expression processing, is performed on the
+All other <var>Html</var> block processing, including expression processing, is performed on the
-line as if it were inside an Html block. The exception is Nodummy processing, because
+line as if it were inside an <var>Html</var> block. The exception is <var>Nodummy</var> processing, because
-dummy string replacement is performed before the Html statement is parsed.
+dummy string replacement is performed before the <var>Html</var> statement is parsed.
 ====Data or Print====
 Either of these keywords can be thought of as providing a single-line
-Html/Text statement which can still be much easier to type and read
+<var>Html</var>/<var>Text</var> statement which can still be much easier to type and read
-than a User Language PRINT statement, as in:
+than a <var class="product">User Language</var> <var>Print</var> statement, as in:
+<p class="code">html data Don't need to worry about apostrophes
-  html data Don't need to worry about apostrophes
+text print {%i} + {%j} = {%i + %j}
-  test print {%i} + {%j} = {%i + %j}
+</p>
 The following is an equivalent alternative to the second statement in the
-preceding example.
+preceding example:
+<p class="code">[[PrintText statement|PrintText]] {%i} + {%j} = {%i + %j}
-  [[PrintText statement|PrintText]] {%i} + {%j} = {%i + %j}
+</p>
-The ''PrintText'' statement has the same effect as a Text Print statement.
+The <var>PrintText</var> statement has the same effect as a <var>Text Print</var> statement.
-The ''PrintText'' keyword is simply a merging and reordering of ''Text
+The <var>PrintText</var> keyword is simply a merging and reordering of <var>Text
-Print'' to emphasize the principle action. The lone difference between
+Print</var>to emphasize the principle action. The lone difference between
-PrintText and Text Print is that PrintText cannot be used if you want to
+<var>PrintText</var> and <var>Text Print</var> is that <var>PrintText</var> cannot be used if you want to
-include other Html/Text options, as in:
+include other <var>Html</var>/<var>Text</var> options, as in:
+<p class="code">text noexpr print The set is {2, 3, 5, 8, 13, ...}
-  text noexpr print The set is {2, 3, 5, 8, 13, ...}
+</p>
-The Data keyword is available in ''Sirius Mods 6.2'' and later. The Print keyword
+The <var>Print</var> keyword and the <var>PrintText</var> statement are available in <var class="product">Sirius Mods</var> 7.2 and later.
-and the PrintText statement are available in ''Sirius Mods 7.2'' and later.
 ====Audit====
-This keyword provides a single-line Html/Text statement that functions
+This keyword provides a single-line <var>Html</var>/<var>Text</var> statement that functions
-like a User Language AUDIT statement, that is, routing subsequent text
+like a <var class="product">User Language</var> <var>Audit</var> statement, that is, routing subsequent text
 to the audit trail.
 For example, this statement directs the text content to the audit trail:
+<p class="code">text audit It ({$time}) was the best of times
-  text audit It ({$time}) was the best of times
+</p>
 The following is an equivalent alternative to the preceding example.
+<p class="code">[[AuditText statement|AuditText]] It ({$time}) was the best of times
-  [[AuditText statement|AuditText]] It ({$time}) was the best of times
+</p>
+As with the <var>PrintText</var> keyword above, the <var>AuditText</var> statement has the
-As with the PrintText keyword above, the AuditText statement has the
+same effect as a <var>Text Audit</var> statement, except it cannot be used if you
-same effect as a Text Audit statement, except it cannot be used if you
+want to include additional <var>Html</var>/<var>Text</var> <var>Options</var>.
-want to include additional Html/Text options.
+The <var>Audit</var> keyword and the <var>AuditText</var> statement are available as of <var class="product">Sirius Mods</var> 7.2.
-The Audit keyword and the AuditText statement are available as of ''Sirius Mods 7.2''.
 ====Trace====
-This keyword provides a single-line <var>Html/Text</var> statement that is the
+This keyword provides a single-line <var>Html</var>/<var>Text</var> statement that is the
-same as a User Language <var>[[Trace statement|Trace]]</var> statement, that is, routing
+same as a <var class="product">User Language</var> <var>[[Trace statement|Trace]]</var> statement, that is, routing
 subsequent text to the trace destination (which may be the audit trail,
-print device, or CCATEMP trace table, or a combination of them).
+print device, or CCATEMP trace table, or a combination of them, as specified in the <var>[[ULTRACE parameter]]</var>).
 For example, this statement directs the text content by default to the
 audit trail:
@@ Line 174: / Line 182: @@
 <p class="code"> [[TraceText statement|TraceText]] This day ({$date}) is unlike any other
 </p>
-As with the <code>PrintText</code> keyword above, the <var>TraceText</var>
+As with the <var>PrintText</var> keyword above, the <var>TraceText</var>
 statement has the same effect as a <var>Text Trace</var> statement, except it
-cannot be used if you want to include additional <var>Html/Text</var> options.
+cannot be used if you want to include additional <var>Html</var>/<var>Text</var> options.
-The <var>Trace</var> keyword and the <var>TraceText</var> statement are available as of <var class="product>Sirius Mods</var> version 7.2.
+The <var>Trace</var> keyword and the <var>TraceText</var> statement are available as of <var class="product">Sirius Mods</var> version 7.2.
 ===Ent_print===
-The Ent_print keyword overrides the current $ENT_PRINT setting for character entity
+The <var>Ent_print</var> keyword overrides the current <var>[[$Ent_Print]]</var> setting for character entity
-translation over the Html block. Ent_print must be followed by one of these keywords:
+translation over the <var>Html</var> block. <var>Ent_print</var> must be followed by one of these keywords:
 <table>
-<tr><td>'''Off'''</td><td>No character entity translation will occur over the Html block.</td></tr>
+<tr><td><var>Off</var></td><td>No character entity translation will occur over the Html block.</td></tr>
-<tr><td>'''On'''</td><td>All data printed by the Html statement will undergo character entity translation.</td></tr>
+<tr><td><var>On</var></td><td>All data printed by the Html statement will undergo character entity translation.</td></tr>
-<tr><td>'''Var'''</td><td>Only the results of expressions will undergo character entity translation.</td></tr></table>
+<tr><td><var>Var</var></td><td>Only the results of expressions will undergo character entity translation.</td></tr></table>
 Character entity translation is the process of converting a single character that might be
 problematic in certain contexts to a more verbose but non-problematic equivalent. For
-example, if a “less than” sign ('''<''') appears in HTML text, it should typically be represented
+example, if a "less than" sign (<tt><</tt>) appears in HTML text, it should typically be represented
-as <nowiki>“&lt;”</nowiki> to prevent an HTML processor from mistakenly interpreting it as the start of an
+as <code>&amp;lt;</code> to prevent an HTML processor from mistakenly interpreting it as the start of an
 HTML tag.
-When entity translation is performed, the default translations are “&” to <nowiki>“&amp;”</nowiki>, “<” to
+When entity translation is performed, the default translations are "ampersand" (<tt>&</tt>) to <code>&amp;amp;</code>, "less than" (<tt><</tt>) to <code>&amp;lt;</code>, and "double quotation mark" (<tt>"</tt>) to <code>&amp;quot;</code>. These defaults should
-<nowiki>“&lt;”</nowiki> and the double quotation mark character (") to <nowiki>“&quot;”</nowiki>. These defaults should
 be sufficient for most HTML and XML applications (though XML might also require
-translation of the single quotation mark character (') to <nowiki>“&apos;”</nowiki> if attributes are
+translation of the single quotation mark character (<tt>'</tt>) to <code>&amp;apos;</code> if attributes are
-enclosed in single quotation marks), but they can be modified with the $ENT_TAB
+enclosed in single quotation marks, but they can be modified with the <var>[[$Ent_Tab]]</var> function.
-function.
+The <var>Ent_print</var> keyword is a compile-time option that affects only what is inside the <var>Html</var>
+block and that is not affected by evaluation time setting of <var>$Ent_Print</var>, even within the
+<var>Html</var> block. If no <var>Ent_print</var> keyword is present on the <var>Html</var> statement, character entity
+translation is controlled by the evaluation-time <var>$Ent_Print</var> setting.
-The Ent_print keyword is a compile-time option that affects only what is inside the Html
-block and that is not affected by evaluation time setting of $ENT_PRINT, even within the
-Html block. If no Ent_print keyword is present on the Html statement, character entity
-translation is controlled by the evaluation-time $ENT_PRINT setting.
-Automatic character entity translation and the Ent_print keyword on the Html/Text
-statement are only available in ''Sirius Mods 6.2'' and later.
 ===LiteralsToTemp===
-The LiteralsToTempt option indicates that the literal data in the statement is stored in
+The <var>LiteralsToTemp</var> option indicates that the literal data in the statement is stored in
 CCATEMP rather than STBL, avoiding excessive demands on STBL space. Designed
-for a Text statement with an unusually large amount of literal data, this is an alternative
+for a <var>Text</var> statement with an unusually large amount of literal data, this is an alternative
-to setting the X'01' bit of the SIRCOMP user parameter (which performs the same
+to setting the X'01' bit of the <var>[[SIRCOMP parameter|SIRCOMP]]</var> user parameter (which performs the same function).
-function).
 ===Nocom or Nocomments===
-The Nocomments (abbreviated Nocom) option indicates that lines beginning with an
+The <var>Nocomments</var> (abbreviated <var>Nocom</var>) option indicates that lines beginning with an
-asterisk (*) are not comment lines. For example:
+asterisk (<tt>*</tt>) are not comment lines. For example:
+<p class="code"><nowiki>HTML NOCOM
-  <nowiki> HTML NOCOM
+* This line will go to the output
-  * This line will go to the output
+END HTML</nowiki> </p>
-  END HTML</nowiki>
 ===Nocont or Nocontinuations===
-The Nocontinuations (abbreviated Nocont) option causes trailing dashes to cease
+The <var>Nocontinuations</var> (abbreviated <var>Nocont</var>) option causes trailing dashes to cease
 being treated as line continuations. For example, the following statement will cause the
 output to appear on two separate lines:
+<p class="code"><nowiki>HTML NOCONT
- <nowiki> HTML NOCONT
+English:             B-
-  English:             B-
+Social Studies:      C
-  Social Studies:      C
+END HTML</nowiki>
-  END HTML</nowiki>
+</p>
 ===Nodum or Nodummy===
-The Nodummy (abbreviated Nodum) option stops dummy string substitution. For
+The <var>Nodummy</var> (abbreviated <var>Nodum</var>) option stops dummy string substitution. For
-example, the following statement will cause the literal string ?&W to be output without
+example, the following statement will cause the literal string <code>?&W</code> to be output without
 global variable substitution:
+<p class="code">HTML NODUM
-  HTML NODUM
+Hello, ?&W
-  Hello, ?&W
+END HTML  </p>
-  END HTML
 ===Noell or Noellipses===
-With the Noellipses (abbreviated Noell) option, a trailing ellipsis (...) is not treated as
+With the <var>Noellipses</var> (abbreviated <var>Noell</var>) option, a trailing ellipsis (<tt>...</tt>) is not treated as
 a concatenation operator. For example:
+<p class="code">HTML NOELL
-  HTML NOELL
+These lines are not joined...
-  These lines are not joined...
+They will appear on different lines.
-  They will appear on different lines.
+END HTML  </p>
-   END HTML
 ===Noexpr or Noexpressions===
-If you do not want expression substitution, specify Noexpr or Noexpressions. For
+If you do not want expression substitution, specify <var>Noexpr</var> or <var>Noexpressions</var>. For example:
-example:
+<p class="code">HTML NOEXPR
-  HTML NOEXPR
+{This will be sent directly to output}
-  {This will be sent directly to output}
+END HTML  </p>
-  END HTML
 ===Raw===
-The Raw option acts as Nocom, Nocont, Nodum, Noell, and Noexpr all at once.
+The <var>Raw</var> option acts as <var>Nocom</var>, <var>Nocont</var>, <var>Nodum</var>, <var>Noell</var>, and <var>Noexpr</var> all at once.
 ===Noend===
-The Noend option eliminates the block end line. Thus, the block will terminate at the
+The <var>Noend</var> option eliminates the block end line. Thus, the block will terminate at the
 end of the procedure. For example:
-  PROC FOO
+<p class="code">PROC FOO
-  HTML NOEND
+HTML NOEND
-  Now we are in HTML.
+Now we are in HTML.
-  END HTML
+END HTML
-  Still in HTML.
+Still in HTML.
-  END PROC
+END PROC  </p>
 ===Exprs or Exprstart===
-The Exprstart (abbreviated Exprs) option specifies a string, up to three characters
+The <var>Exprstart</var> (abbreviated <var>Exprs</var>) option specifies a string, up to three characters
-long, that begins an expression within the block body. The default is a left curly brace
+long, that begins an expression within the block body. The default is a left curly brace (<b>{</b>). For example:
-( { ). For example:
+<p class="code">html exprs go expre stp
-<pre>
-html exprs go expre stp
    The answer is go8*9stp
 end html
-</pre>
+</p>
 It is probably best to use start and end sequences that are not likely to occur in the literal
-text in the Html/Text block and that clearly demarcate expressions from literal text. The
+text in the <var>Html</var>/<var>Text</var> block and that clearly demarcate expressions from literal text. The
-"go" and "stp" in the example above are actually not very good choices.
+<code>go</code> and <code>stp</code> in the example above are actually not very good choices.
-If the expression start string occurs in the input text, you can “double” the expression
+If the expression start string occurs in the input text, you can "double" the expression
-start string, instead of using the Exprs option. For example:
+start string, instead of using the <var>Exprs</var> option. For example:
-<pre>
+<p class="code"><nowiki>html
-<nowiki>html
     <script>
       {{alert("User error")}
     </script>
 end html</nowiki>
-</pre>
+</p>
-Note that because the double open-curly-brace is not treated as an expression start, the close-curly-brace is not treated as an expression end since the compiler is not processing an expression where it appears. This illustrates the point that generally there is no need to change the expression end character as its presence is irrelevant in non-expression contexts and an unquoted close-curly-brace cannot occur in a User Language expression. Probably the only compelling reason to change the expression end characters is aesthetics or readability &mdash; one might want the expression end to mirror the expression start:
+Note that because the double open-curly-brace (<b>{{</b>) is not treated as an expression start, the close-curly-brace (<b>}</b>) is not treated as an expression end, since the compiler is not processing an expression where it appears.
-<pre>
+This illustrates the point that generally there is no need to change the expression end character as its presence is irrelevant in non-expression contexts and an unquoted close-curly-brace cannot occur in a <var class="product">User Language</var> expression. Probably the only compelling reason to change the expression end characters is aesthetics or readability &mdash; one might want the expression end to mirror the expression start.
-<nowiki>html exprs '{<' expre '>}'
+<p class="code"><nowiki>html exprs '{<' expre '>}'
     <script>
       var foobar = "{<%foobar>}"
@@ Line 293: / Line 296: @@
     <script>
 end html</nowiki>
-</pre>
+</p>
 One can even use the same set of characters as expression start and end characters:
-<pre>
+<p class="code"><nowiki>html exprs // expre //
-<nowiki>html exprs // expre //
     <script>
       var foobar = "//%foobar//"
@@ Line 302: / Line 304: @@
     <script>
    end html</nowiki>
-</pre>
+</p>
 The above example is simply intended to illustrate a point and should not be considered a recommendation.
 '''Note:''' If you use multiple special characters to demarcate expressions, you are advised
-to enclose those characters in single quotation marks (as above) in your Exprs and
+to enclose those characters in single quotation marks (as above) in your <var>Exprs</var> and
-Expre specifications. Otherwise, multiple-character combinations involving certain
+<var>Expre</var> specifications. Otherwise, multiple-character combinations involving certain
-special characters (including these six, for example: = ¬ ( ) < > ) cause M204.0580
+special characters (including these six, for example: <code>= , ( ) < ></code> ) cause M204.0580 errors.
-errors.
 ===Expre or Exprend===
-The Exprend (abbreviated Expre) option specifies a string that ends an expression
+The <var>Exprend</var> (abbreviated <var>Expre</var>) option specifies a string that ends an expression
-within the block body. The default is a right curly brace ( } ).
+within the block body. The default is a right curly brace (<b>}</b>).
 ===End===
-To set your own block_end_line, you can use the End option. If the text of the line you
+To set your own <var class="term">block_end_line</var>, you can use the <var>End</var> option.  For example:
-are specifying contains spaces, enclose it in single quotation marks, as in:
+<p class="code">text to %list end listEnd
-  End 'END TEXT BLOCK'
+   Four score
-The default block_end_line value is '''End Html''' (for the Html block) or '''End Text''' (for the
+   and seven
-Text block).
+listEnd
+</p>
+If the text of the line you
+are specifying contains spaces, enclose it in single quotation marks. For example:
+<p class="code">text to %list end 'end text block'
+   Our
+   forebears
+end text block
+</p>
+The default <var class="term">block_end_line</var> value is <code>End Html</code> (for the <var>Html</var> block) or <code>End Text</code> (for the <var>Text</var> block).
+<div id="toOption"></div>
+===To %stringlist, To Audit, To Print, or To Trace===
+The <var>To</var> option lets you direct the contents of the <var>Html</var> or <var>Text</var> block to a <var>Stringlist</var> or to the destinations associated with the <var class="product">User Language</var> statements <var>Audit</var>, <var>Print</var>, or <var>Trace</var>.
+====To %stringlist [= New]====
+The <var>To</var> option, when used to add data to a <var>Stringlist</var>, has an optional <code>= New</code> clause following the <var>Stringlist</var>, which first creates a new <var>Stringlist</var> instance.  Without <code>= New</code>, the data is appended to the <var>Stringlist</var>.
-===To %stringList | Audit | Print | Trace===
+Here is how <var>Text To</var> populates a <var>Stringlist</var> with some names:
-The To option lets you direct the contents of the Html or Text block to a StringList or to
+<p class="code">%jumps is object stringList
-the destinations associated with the User Language statements Audit, Print, or Trace.
+...
-To %stringlist
+text to %jumps = new
-Here is how Text To populates a StringList with some names:
-  %jumps is object stringList
-  ...
-  %jumps = new
-  text to %jumps
    Axel
    Flip
@@ Line 336: / Line 352: @@
    Toe Loop
    Wally
-  end text
+end text
+</p>
-There are many advantages to using Html To or Text To over a plain Html statement
-wih $LIST_CAPTURE:
+The <code>text to %jumps = new</code> statement above is an optional simplification (as of <var class="product">Sirius Mods</var> version 7.6) of the sequence:
-* $LIST_CAPTURE or an equivalent is not available for StringLists.
+<p class="code">%jumps = new
-* Because Html To does not go through generic Print processing, it has a somewhat more efficient processing path, that is, it uses less CPU.
+text to %jumps
-* Because Html To does not go through generic Print processing, the generated quads take somewhat less space.
+</p>
-* An Html To block does not affect the current $LIST_CAPTURE setting, so it eliminates the need to worry about saving and restoring the $LIST_CAPTURE setting.
-* A To option on an Html statement is simply less and cleaner code than an Html statement inside a $LIST_CAPTURE bracket.
+There are many advantages to using <var>Html To</var> or <var>Text To</var> over a plain <var>Html</var> statement
-* If an expression inside an Html To block invokes a User Language method, and that method does a Print statement, the output of that Print statement does not end up on the StringList target of the Html statement. Inside a $LIST_CAPTURE bracket, the output of such a Print statement ends up on the $LIST_CAPTURE's target $list.
+wih <var>$List_Capture</var>:
+<ul>
-The To option of the Html/Text statement appends to the target StringList, so it does not
+<li> <var>$List_Capture</var> or an equivalent is not available for <var>Stringlists</var>.
-instantiate the stringList if it is null. In fact, a null StringList target for an Html To results
+<li> Because <var>Html To</var> does not go through generic Print processing, it has a somewhat more efficient processing path, that is, it uses less CPU.
+<li> Because <var>Html To</var> does not go through generic Print processing, the generated quads take somewhat less space.
+<li> An <var>Html To</var> block does not affect the current <var>$List_Capture</var> setting, so it eliminates the need to worry about saving and restoring the <var>$List_Capture</var> setting.
+<li> A <var>To</var> option on an <var>Html</var> statement is simply less and cleaner code than an <var>Html</var> statement inside a <var>$List_Capture</var> bracket.
+<li> If an expression inside an <var>Html To</var> block invokes a User Language method, and that method does a Print statement, the output of that <var>Print</var> statement does not end up on the <var>Stringlist</var> target of the <var>Html</var> statement. Inside a <var>$List_Capture</var> bracket, the output of such a <var>Print</var> statement ends up on the <var>$List_Capture</var>'s target $list.
+</ul>
+The <var>To</var> option of the <var>Html</var> or <var>Text</var> statement appends to the target <var>Stringlist</var>, so it does not
+instantiate the <var>Stringlist</var> if it is null. In fact, a null <var>Stringlist</var> target for an <var>Html To</var> results
 in a null-pointer request-cancelling error.
-Even if the ultimate target of an Html/Text statement is a plain $list, the Html To can still
+Even if the ultimate target of an <var>Html</var> or <var>Text</var> statement is a plain $list, the <var>Html To</var> can still
 be used to gain some of the benefits of this structure without much extra code by using
-the Stringlist object MoveFromId and MoveToId methods:
+the <var>Stringlist</var> object <var>[[MoveFromId (Stringlist subroutine)|MoveFromId]]</var> and <var>[[MoveToId (Stringlist subroutine)|MoveToId]]</var> methods:
-  %htmlList is object stringList
+<p class="code">%htmlList is object stringList
-  %list is float
+%list is float
-  ...
+...
-  %list = $listNew
+%list = $listNew
-  ...
+...
-  %htmlList = new
+%htmlList = new
-  %htmlList:modeFromId(%list)
+%htmlList:modeFromId(%list)
-  text to %htmlList
+text to %htmlList
    This gets added to the $list.
-  end text
+end text
-  %htmlList:modeToId(%list)
+%htmlList:modeToId(%list)
+</p>
-'''To Audit, To Print, To Trace'''
+====To Audit, To Print, To Trace====
-These options direct the contents of an Html or Text block or line to the destinations
+These options direct the contents of an <var>Html</var> or <var>Text</var> block or line to the destinations
-associated with the User Language statements Audit, Print, or Trace. Respectively
+associated with the <var class="product">User Language</var> statements <var>Audit</var>, <var>Print</var>, or <var>Trace</var>. Respectively
 these destinations are the journal/audit trail, the current print output device, or the trace
 destination (which may be the audit trail, print device, or CCATEMP trace table, or a
 combination of them).
-For example, the following statement directs the Text block content to the audit trail:
+For example, the following statement directs the <var>Text</var> block content to the audit trail:
-  text to audit
+<p class="code">text to audit
    Now ({$time}) is the time for all good men
    to come to the aid of their company.
-  end text
+end text
+</p>
+To direct a single line of output, you can use the <var>Data</var> keyword ([[#Data, Print, Audit, or Trace|"Data, Print, Audit, or Trace"]]) as in the following:
+<p class="code">text to audit Data It ({$time}) was the best of times
+</p>
+Or, simpler, you can use the <var>Audit</var> keyword like this:
+<p class="code">text Audit It ({$time}) was the best of times
+</p>
+Furthermore, the [[Targeted Text statements|targeted Text statements]] provide an alternative syntax, in which the "target" (<var>Print</var>, <var>Audit</var>, <var>Trace</var>) is at the start of the statement, making them more "natural" analogues of the <var>Print</var>, <var>Audit</var> and <var>Trace</var> statements.  For example:
+<p class="code">auditText It ({$time}) was the best of times
+</p>
+==Body: Html or Text block body==
+Each line of an <var>Html</var> or <var>Text</var> block, up to the block_end_line, creates a line of literal
+output, with the following substitutions:
+<table border="1">
+<tr><td>Expressions</td>
+<td>An expression is begun by a left brace (<b>{</b>) or a user-defined string specified with the <var>Exprs</var> option, and it is ended by a right brace (<b>}</b>) or a user-defined string specified with the <var>Expre</var> option. Text within the expression is evaluated as if it were the right-hand side of a <var class="product">User Language</var> assignment; that value is produced, rather than literal output.</td></tr>
-To direct a single line of output, you can use the Data keyword (''Data, Print, Audit, or
+<tr><td nowrap>Dummy strings</td>
-Trace'')  as in the following:
+<td>Normally, as in other <var class="product">Model 204</var> input, dummy strings are substituted under the control of the <var>SUB</var> parameter. This can be suppressed with the <var>Nodummy</var> option, which may be useful if your block contains strings like "what the heck??!!".</td></tr>
-  text to audit Data It ({$time}) was the best of times
+<tr><td>Continuation</td>
+<td>Continuation allows text from multiple lines to be printed on one line by adding a hyphen (<b>-</b>) to all preceding lines in the block. All spacing and indentation following the hyphen is ignored. This option works inside an expression.</td></tr>
-Or, simpler, you can use the Audit keyword like this:
+<tr><td>Ellipses</td>
+<td>Ellipses allow text from multiple command lines to be printed on one line by adding three dots (<b>...</b>)  to all preceding command lines. Leading spaces will be included. This option will not work inside an expression.</td></tr>
-  text Audit It ({$time}) was the best of times
+<tr> <td>Indentation</td>
-==Body: Html or Text block body==
+<td>Except for continuation lines, the output of a line is indented by as many spaces as the input is indented relative to the <var>Html</var> or <var>Text</var> statement that begins the block.</td></tr></table>
-Each line of an Html or Text block, up to the block_end_line, creates a line of literal
-output, with the following substitutions:
-<table border="1">
-<tr><td>Expressions</td><td> An expression is begun by a left brace ( { ) or a user-defined string specified with the Exprs option, and it is ended by a right brace ( } ) or a user-defined string specified with the Expre option. Text within the expression is evaluated as if it were the right-hand side of a User Language assignment; that value is produced, rather than literal output.</td></tr>
-<tr><td>Dummy strings</td><td>  Normally, as in other Model 204 input, dummy strings are substituted under the control of the SUB parameter. This can be suppressed with the Nodummy option, which may be useful if your block contains strings like “what the heck??!!”.</td></tr>
-<tr><td>Continuation</td><td>  Continuation allows text from multiple lines to be printed on one line by adding a hyphen (-) to all preceding lines in the block. All spacing and indentation following the hyphen is ignored. This option works
-inside an expression.</td></tr>
-<tr><td>Ellipses</td><td> Ellipses allow text from multiple command lines to be printed on one line by adding three dots (...) to all preceding command lines. Leading spaces will be included. This option will not work inside an expression.</td></tr>
-<tr><td>Indentation</td><td> Except for continuation lines, the output of a line is indented by as many spaces as the input is indented relative to the Html or Text statement that begins the block.</td></tr></table>
 ===block_end_line: Html or Text block end===
-By default, the line that ends an Html or Text block is End Html for an Html block, or it
+By default, the line that ends an <var>Html</var> or <var>Text</var> block is <var>End Html</var> for an <var>Html</var> block, or it
-is End Text for a Text block. You can specify your own end line with the End option,
+is <var>End Text</var> for a <var>Text</var> block. You can specify your own end line with the <var>End</var> option,
-as described above in “End”.
+as described above in [[#End|End]].
 ===Printing of expression results===
-Model 204 expressions enclosed in the expression start and end characters are printed
+<var class="product">Model 204</var> expressions enclosed in the expression start and end characters are printed
 as if the result of the expression were placed literally in the place of the expression in the
-HTML block. For example, Text Print {$date} produces a result like 08-02-29.
+HTML block. For example, <code>Text Print {$date}</code> produces a result like <code>08-02-29</code>.
 ===Character entity substitution===
-Under ''Sirius Mods 6.2'' and later, the result of the expression might undergo character
+The result of the expression might undergo character
-entity substitution under control of the $ENT_PRINT setting or the Ent_print parameter
+entity substitution under control of the <var>$Ent_Print</var> setting or the <var>Ent_print</var> parameter
-on the Html/Text statement. An expression can explicitly override the default
+on the <var>Html</var>/<var>Text</var> statement. An expression can explicitly override the default
-$ENT_PRINT and Ent_print processing by immediately following the expression start
+<var>$Ent_Print</var> and <var>Ent_print</var> processing by immediately following the expression start
 character(s) with one of the following special characters:
-<table border="1">
+<table class="thJustBold">
-<tr><td>'''&'''</td><td> Perform character entity substitution regardless of the current $ENT_PRINT
+<tr><th>&</th>
-setting and the Ent_print setting on the Html statement.</td></tr>
+<td>Perform character entity substitution regardless of the current <var>$Ent_Print</var>
-<tr><td>'''!''' </td><td>Do not perform character entity substitution, regardless of the current
+setting and the <var>Ent_print</var> setting on the <var>Html</var> statement.</td></tr>
-$ENT_PRINT setting and the Ent_print setting on the Html statement.</td></tr>
-<tr><td>'''*'''</td><td>Do not print the results of the expression. This can be useful if embedding a $function that itself prints output, such as $LIST_PRINT or $WEB_SEL, or a $function that simply sets some environmental parameter (such as $WEB_SET or $RESETN) whose return value should not be displayed.</td></tr></table>
-'''Note:''' The asterisk (*) suppresses the printing of the return code but not the
+<tr><th>!</th>
-output from a $LIST_PRINT or $WEB_SEL function.
+<td>Do not perform character entity substitution, regardless of the current
+<var>$Ent_Print</var> setting and the <var>Ent_print</var> setting on the <var>Html</var> statement.</td></tr>
+<tr><th>*</th><td>Do not print the results of the expression. This can be useful if
+embedding a $function that itself prints output, such as <var>[[$List_Print]]</var> or <var>[[$Web_Sel]]</var>, or a $function that simply sets some environmental parameter (such as <var>[[$Web_Set]]</var> or <var>[[$Resetn]]</var>) whose return value should not be displayed.</td></tr></table>
+<p class="note">'''Note:''' The asterisk (<tt>*</tt>) suppresses the printing of the return code but not the
+output from a <var>$List_Print</var> or <var>$Web_Sel</var> function. </p>
 In the following example, character entity substitution is explicitly suppressed for the
-contents of %FONT and explicitly forced for %COMMENT, and the return code from
+contents of <code>%FONT</code> and explicitly forced for <code>%COMMENT</code>, and the return code from
-$LIST_PRINT is suppressed:
+<code>$LIST_PRINT</code> is suppressed:
-  <nowiki>HTML
-  {!%FONT}This is in a fancy font</font>
-  <input type="text" name="comment" value="{&%COMMENT}">
-  <br>And here's some stuff<br>
-  {*$LIST_PRINT(%LIST)}
-  END HTML
-</nowiki>
-<div id="tilde">
-===The {~} directive===
-The special expression {~} directs the compiler to replace this expression with the literal
-chartacter content of the next expression appearing on the same line. So
-  printText {~} = {1234:nextPrime}
-produces "''1234:nextPrime = 1237''". The evaluation of the expression following {~} is carried out as usual. As of Sirius Mods 7.8, one can also specific a ~= directive, as in
-  printText {~=1234:nextPrime}
-which produces "''1234:nextPrime=1237''". The ~= directive can optionally be followed by spaces before the expression but will always produce no spaces before or after the equals sign on output. If more control of spacing is required, the simple {~} directive should be used, instead.
-==Table Usage==
+<p class="code"><nowiki>HTML
-While the '''Html/Text''' statement can provide a convenient typing shorthand relative to a
+{!%FONT}This is in a fancy font</font>
-host of Print statements, and it can make code considerably more readable, it does not
+<input type="text" name="comment" value="{&%COMMENT}">
-necessarily use any less table space than the comparable Print statements.
+<br>And here's some stuff<br>
+{*$LIST_PRINT(%LIST)}
-Under ''Sirius Mods version 6.6'' and later, however, table space can be saved with the
+END HTML</nowiki> </p>
-Html/Text statement, as follows:
+<div id="tilde"></div>
-* By using the To clause and sending the Html/Text statement output directly to a StringList, the amount of QTBL space used is reduced.
+<div id="tildeDirectives"></div>
-* If the X'01' bit is set in the SIRCOMP user parameter when a program is compiled, string literals are saved in CCATEMP rather than STBL. Since Html/Text statements often have a large quantity of literal text, they can use a lot of STBL space, so the STBL space savings of the SIRCOMP X'01' bit can be great.
+===The {~} and {~= ...} directives===
+The special expression <b>{~}</b> directs the compiler to replace this expression with the literal
+character content of the next expression appearing on the same line. So:
+<p class="code">printText {~} = {1234:nextPrime}
+</p>
+displays:
+<p class="output">1234:nextPrime = 1237
+</p>
+The evaluation of the expression following <b>{~}</b> is carried out as usual. As of Sirius Mods 7.8, you can also specific a <b>~=</b> directive, as in:
+<p class="code">printText {~=1234:nextPrime}
+</p>
+This displays:
+<p class="output">1234:nextPrime=1237
+</p>
+The expression after the <b>~=</b> directive can be preceded or followed by blanks.
+Blanks before the expression appear in the output before the expression result (after the equal sign), and spaces after the expression appear in the output after the expression literal (before the equal sign). For example,
+<p class="code">printText {~= 100:nextPrime   }
+</p>
+displays:
+<p class="output">100:nextPrime   = 101
+</p>
+If more control of spacing is required, the simple <b>{~}</b> directive should be used, instead.
+As mentioned at the end of the [[#To Audit, To Print, To Trace|To Audit, To Print, To Trace]] section above, the <var>PrintText</var> statement is a synonym for the <var>Text Print</var> statement.
+==Table usage==
+While the <var>Html</var>/<var>Text</var> statement can provide a convenient typing shorthand relative to a
+host of <var>Print</var> statements, and it can make code considerably more readable, it does not
+necessarily use any less table space than the comparable <var>Print</var> statements.
+Table space can be saved with the <var>Html</var>/<var>Text</var> statement, as follows:
+<ul>
+<li>By using the <var>[[#toOption|To]]</var> clause and sending the <var>Html</var>/<var>Text</var> statement output directly to a <var>Stringlist</var>, the amount of QTBL space used is reduced.
+<li>If the X'01' bit is set in the <var>[[SIRCOMP parameter|SIRCOMP]]</var> user parameter when a program is compiled, string literals are saved in CCATEMP rather than STBL. Since <var>Html</var>/<var>Text</var> statements often have a large quantity of literal text, they can use a lot of STBL space, so the STBL space savings of the <var>SIRCOMP</var> X'01' bit can be great.
 The drawback to having string literals in CCATEMP rather than STBL is that the access path to the data is somewhat longer, that is, slightly more CPU is required to
-access it. When the Html/Text statement uses a To clause, the extra overhead of
+access it. When the <var>Html</var>/<var>Text</var> statement uses a <var>To</var> clause, the extra overhead of
-CCATEMP data access is reduced, because Html/Text To processing keeps the
+CCATEMP data access is reduced, because <var>Html</var>/<var>Text</var> To processing keeps the
 CCATEMP pages holding literal data open over as many literals as possible.
+<p>
 Furthermore, for pre-compiled APSY procedures, the literals in CCATEMP do not
 need to be APSY loaded, and they are shared among all users of a procedure.
-Finally, if a user with a large number of Html/Text statement literals is serverswapped,
+Finally, if a user with a large number of <var>Html</var>/<var>Text</var> statement literals is server-swapped,
 there is less data to server-swap if literals are kept in CCATEMP
-(although, the data in CCATEMP does take buffer pool space and might require
+(although, the data in CCATEMP does take buffer pool space and might require CCATEMP I/O).  </p>
-CCATEMP I/O).
+</ul>
-So there is probably no good general rule of thumb regarding whether the SIRCOMP
+So there is probably no good general rule of thumb regarding whether the <var>SIRCOMP</var>
 X'01' bit should be set. Probably, unless a site is struggling with server size problems, it
 is best and simplest to just keep the literals in STBL.
+==See also==
+<ul>
+<li>[[Targeted Text statements]]
+</ul>
 [[Category:User Language statements]]