From: <wda...@us...> - 2012-09-10 20:25:04
|
Revision: 8396 http://sourceforge.net/p/oorexx/code-0/8396 Author: wdashley Date: 2012-09-10 20:25:00 +0000 (Mon, 10 Sep 2012) Log Message: ----------- Add example tags to example listings. Still not done with rexxref yet. Modified Paths: -------------- docs/trunk/publican/rexxref/en-US/instrc.xml docs/trunk/publican/rexxref/en-US/intro.xml docs/trunk/publican/rexxref/en-US/iostrms.xml docs/trunk/publican/rexxref/en-US/numarit.xml docs/trunk/publican/rexxref/en-US/oneof.xml docs/trunk/publican/rexxref/en-US/parsingch.xml docs/trunk/publican/rexxref/en-US/provide.xml Modified: docs/trunk/publican/rexxref/en-US/instrc.xml =================================================================== --- docs/trunk/publican/rexxref/en-US/instrc.xml 2012-09-10 03:08:58 UTC (rev 8395) +++ docs/trunk/publican/rexxref/en-US/instrc.xml 2012-09-10 20:25:00 UTC (rev 8396) @@ -170,30 +170,36 @@ <secondary>example</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>ADDRESS instruction</secondary></indexterm> -<para><emphasis role="bold">Windows Example:</emphasis></para> <indexterm><primary>CMD command environment</primary></indexterm> +<example> +<title>Instructions - ADDRESS (Windows)</title> <programlisting> ADDRESS CMD "DIR C:\CONFIG.SYS" </programlisting> -<para><emphasis role="bold">Linux Example:</emphasis></para> +</example> +<example> +<title>Instructions - ADDRESS (Linux)</title> <indexterm><primary>bash command environment</primary></indexterm> <programlisting> ADDRESS "bash" "ls /usr/lib" </programlisting> +</example> <para>If you specify only <emphasis role="italic">environment</emphasis>, a lasting change of destination occurs: all commands (see <xref linkend="commnds" />) that follow are routed to the specified command environment, until the next ADDRESS instruction is processed. The previously selected environment is saved.</para> -<para><emphasis role="bold">Examples:</emphasis></para> <para>Assume that the environment for a Windows text editor is registered by the name <computeroutput>EDIT</computeroutput>:</para> +<example> +<title>Instructions - ADDRESS environments</title> <programlisting> address CMD "DIR C:\AUTOEXEC.BAT" if rc=0 then "COPY C:\AUTOEXEC.BAT C:\*.TMP" address EDIT </programlisting> +</example> <para>Subsequent commands are passed to the editor until the next ADDRESS instruction.</para> <para>Similarly, you can use the VALUE form to make a lasting change to the @@ -204,10 +210,12 @@ does not begin with a literal string or symbol, that is, if it starts with a special character such as an operator character or parenthesis.</para> -<para><emphasis role="bold">Example:</emphasis></para> +<example> +<title>Instructions - ADDRESS environments</title> <programlisting> ADDRESS ("ENVIR"||number) /* Same as ADDRESS VALUE "ENVIR"||number */ </programlisting> +</example> <para>With no arguments, commands are routed back to the environment that was selected before the previous change of the environment, and the current environment name is saved. After changing the environment, repeated execution of ADDRESS @@ -294,11 +302,12 @@ <para>You can use the ARG and PARSE ARG instructions repeatedly on the same source objects (typically with different templates). The source objects do not change. </para> -<para><emphasis role="bold">Example:</emphasis></para> <indexterm><primary>ARG instruction</primary> <secondary>example</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>ARG instruction</secondary></indexterm> +<example> +<title>Instructions - ARG</title> <programlisting> /* String passed is "Easy Rider" */ Arg adjective noun . @@ -306,6 +315,7 @@ /* Now: ADJECTIVE contains "EASY" */ /* NOUN contains "RIDER" */ </programlisting> +</example> <para>If you expect more than one object to be available to the program or routine, you can use a comma <indexterm><primary>, (comma)</primary> @@ -314,7 +324,8 @@ <secondary>in parsing template list</secondary></indexterm> in the parsing <emphasis role="italic">template_list</emphasis> so each template is selected in turn.</para> -<para><emphasis role="bold">Example:</emphasis></para> +<example> +<title>Instructions - ARG</title> <programlisting> /* Function is called by FRED("data X",1,5) */ Fred: Arg string, num1, num2 @@ -323,6 +334,7 @@ /* NUM1 contains "1" */ /* NUM2 contains "5" */ </programlisting> +</example> <para><emphasis role="bold">Notes:</emphasis></para> <orderedlist> @@ -509,10 +521,13 @@ <computeroutput>CALL</computeroutput>, the function name (with <emphasis>no parenthesis</emphasis>) and any arguments:</para></note> +<example> +<title>Instructions - CALL</title> <programlisting> call length "string" /* Same as length("string") */ say result /* Produces: 6 */ </programlisting> +</example> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">External routines</emphasis></term> <listitem><para>Users can write or use routines that are external to the @@ -568,11 +583,12 @@ <indexterm><primary>recursive call</primary></indexterm> <indexterm><primary>call, recursive</primary></indexterm> </para> -<para><emphasis role="bold">Example:</emphasis></para> <indexterm><primary>CALL instruction</primary> <secondary>example</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>CALL instruction</secondary></indexterm> +<example> +<title>Instructions - CALL</title> <programlisting> /* Recursive subroutine execution... */ arg z @@ -584,7 +600,8 @@ if n=0 then return 1 call factorial n-1 return result * n - </programlisting> +</programlisting> +</example> <indexterm><primary>tracing</primary> <secondary>action saved during subroutine calls</secondary></indexterm> <para>During @@ -829,25 +846,29 @@ variable is named (see <xref linkend="keyExpose" /> and <xref linkend="keyProcedure" />), then the original variable is dropped.</para> -<para><emphasis role="bold">Example:</emphasis></para> <indexterm><primary>DROP instruction</primary> <secondary>example</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>DROP instruction</secondary></indexterm> +<example> +<title>Instructions - DROP</title> <programlisting> j=4 Drop a z.3 z.j /* Drops the variables: A, Z.3, and Z.4 */ /* so that reference to them returns their names. */ </programlisting> +</example> <para>Here, a variable name in parentheses is used as a subsidiary list.</para> -<para><emphasis role="bold">Example:</emphasis></para> +<example> +<title>Instructions - DROP</title> <programlisting> mylist="c d e" drop (mylist) f /* Drops the variables C, D, E, and F */ /* Does not drop MYLIST */ </programlisting> +</example> <indexterm><primary>stem of a variable</primary> <secondary>used in DROP instruction</secondary></indexterm> <para> Specifying a stem @@ -890,16 +911,18 @@ <para>If you specify <emphasis role="italic">expression</emphasis>, it is evaluated and the object resulting from the evaluation is passed back to the caller when the program stops.</para> -<para>Example:</para> <indexterm><primary>EXIT instruction</primary> <secondary>example</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>EXIT instruction</secondary></indexterm> +<example> +<title>Instructions - EXIT</title> <programlisting> j=3 Exit j*4 /* Would exit with the string "12" */ </programlisting> +</example> <para>If you do not specify <emphasis role="italic">expression</emphasis>, no data is passed back to the caller. If the program was called as a function, this is detected @@ -974,11 +997,12 @@ <para>Variables are exposed in sequence from left to right. It is not an error to specify a name more than once, or to specify a name that has not been used as a variable.</para> -<para><emphasis role="bold">Example:</emphasis></para> <indexterm><primary>EXPOSE instruction</primary> <secondary>example</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>EXPOSE instruction</secondary></indexterm> +<example> +<title>Instructions - EXPOSE</title> <programlisting> /* Example of exposing object variables */ myobj = .myclass~new @@ -999,11 +1023,13 @@ say "Z is:" z return </programlisting> +</example> <para>You can expose an entire collection of compound variables (see <xref linkend="compsym" />) by specifying their stem in the variable list or a subsidiary list. The variables are exposed for all operations.</para> -<para><emphasis role="bold">Example:</emphasis></para> +<example> +<title>Instructions - EXPOSE</title> <programlisting> expose j k c. d. /* This exposes "J", "K", and all variables whose */ @@ -1012,6 +1038,7 @@ /* variable pool, even if it did not */ /* previously exist. */ </programlisting> +</example> </section> <section id="keyForward"><title>FORWARD</title> @@ -1104,18 +1131,21 @@ of an existing message invocation to another method. For example, the FORWARD instruction can forward a message to a different target object, using the same message name and arguments.</para> -<para><emphasis role="bold">Example:</emphasis></para> <indexterm><primary>FORWARD instruction</primary> <secondary>example</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>FORWARD instruction</secondary></indexterm> +<example> +<title>Instructions - FORWARD</title> <programlisting> ::method substr forward to (self~string) /* Forward to the string value */ </programlisting> +</example> <para>You can use FORWARD in an UNKNOWN method to reissue to another object the message that the UNKNOWN method traps.</para> -<para><emphasis role="bold">Example:</emphasis></para> +<example> +<title>Instructions - FORWARD</title> <programlisting> ::method unknown use arg msg, args @@ -1123,10 +1153,12 @@ /* passing along the arguments */ forward to (self~string) message (msg) arguments (args) </programlisting> +</example> <para>You can use FORWARD in a method to forward a message to a superclass's methods, passing the same arguments. This is very common usage in object INIT methods.</para> -<para><emphasis role="bold">Example:</emphasis></para> +<example> +<title>Instructions - FORWARD</title> <programlisting> ::class savings subclass account ::method init @@ -1135,6 +1167,7 @@ type = "Savings" /* Now complete initialization */ penalty = "1% for balance under 500" </programlisting> +</example> <para>In the preceding example, the CONTINUE option causes the FORWARD message to continue with the next instruction, rather than exiting the Savings class INIT method.</para> @@ -1187,11 +1220,12 @@ the method resumes running. If the <emphasis role="italic">expression</emphasis> evaluates to false, GUARD resumes waiting.</para> -<para><emphasis role="bold">Example:</emphasis></para> <indexterm><primary>GUARD instruction</primary> <secondary>example</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>GUARD instruction</secondary></indexterm> +<example> +<title>Instructions - GUARD</title> <programlisting> <![CDATA[ ::method c @@ -1207,6 +1241,7 @@ say "Method D" ]]> </programlisting> +</example> <para>If you specify WHEN and the method has exclusive access to the object's variable pool, then the exclusive access is released while GUARD is waiting for an object variable to change. Exclusive access is reacquired before the @@ -1276,7 +1311,8 @@ <para>ELSE binds to the nearest IF at the same level. You can use the NOP instruction to eliminate errors and possible confusion when IF constructs are nested, as in the following example.</para> -<para><emphasis role="bold">Example:</emphasis></para> +<example> +<title>Instructions - IF</title> <programlisting> If answer = "YES" Then If name = "FRED" Then @@ -1286,6 +1322,7 @@ Else say "Why not?" </programlisting> +</example> <para>The <emphasis role="italic">expression</emphasis> may also be a list of expressions separated by ",". Each subexpression must evaluate to @@ -1295,22 +1332,27 @@ will be returned as the condition result. If all of the subexpressions evaluate to <computeroutput>1</computeroutput>, then the condition result is also <computeroutput>1</computeroutput>.</para> -<para><emphasis role="bold">Example:</emphasis></para> +<example> +<title>Instructions - IF</title> <programlisting> If answer~datatype('w'), answer//2 = 0 Then say answer "is even" Else say answer "is odd" </programlisting> +</example> <para>The example above is not the same as using the following</para> +<example> +<title>Instructions - IF</title> <programlisting> If answer~datatype('w') & answer//2 = 0 Then say answer "is even" Else say answer "is odd" </programlisting> +</example> <para>The logical & operator will evaluate both terms of the operation, so the term "answer//2" will result in a syntax error if answer is a non-numeric value. With the list conditional form, evaluation will stop with the first false result, so the @@ -1366,11 +1408,12 @@ also contains the whole repetitive DO...END or LOOP...END construct.</para> <para>A semicolon is implied at the end of the expression during execution, if one was not supplied.</para> -<para><emphasis role="bold">Examples:</emphasis></para> <indexterm><primary>INTERPRET instruction</primary> <secondary>example</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>INTERPRET instruction</secondary></indexterm> +<example> +<title>Instructions - INTERPRET</title> <programlisting> /* INTERPRET example */ data="FRED" @@ -1386,7 +1429,8 @@ /* Hello there! */ /* Hello there! */ /* Hello there! */ - </programlisting> +</programlisting> +</example> <para><emphasis role="bold">Notes:</emphasis></para> <orderedlist> @@ -1398,11 +1442,12 @@ <computeroutput>TRACE I</computeroutput> can be helpful in interpreting the results you get.</para> -<para><emphasis role="bold">Example:</emphasis></para> <indexterm><primary>INTERPRET instruction</primary> <secondary>example</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>INTERPRET instruction</secondary></indexterm> +<example> +<title>Instructions - INTERPRET</title> <programlisting> /* Here is a small Rexx program. */ Trace Int @@ -1435,6 +1480,7 @@ >>> "Hello Kitty!" Hello Kitty! </programlisting> +</example> <para>Lines 3 and 4 set the variables used in line 5. Execution of line 5 then proceeds in two stages. First the string to be interpreted is built up, using a literal string, a variable @@ -1451,9 +1497,12 @@ (see <xref linkend="bifValue" />) instead of the INTERPRET instruction. The following line could, therefore, have replaced line 5 in the previous example: </para> +<example> +<title>Instructions - INTERPRET</title> <programlisting> say "Hello" value(indirect)"!" </programlisting> +</example> <para>INTERPRET is usually required only in special cases, such as when two or more statements are to be interpreted together, or when an expression is to be evaluated dynamically.</para></listitem> @@ -1495,11 +1544,12 @@ active loop, which can be the innermost, and this is the loop that is stepped. Any active loops inside the one selected for iteration are ended (as though by a LEAVE instruction).</para> -<para><emphasis role="bold">Example:</emphasis></para> <indexterm><primary>ITERATE instruction</primary> <secondary>example</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>ITERATE instruction</secondary></indexterm> +<example> +<title>Instructions - ITERATE</title> <programlisting> loop label MyLabelName i=1 to 4 /* label set to 'MYLABELNAME' */ if i=2 then iterate @@ -1511,6 +1561,7 @@ 4 */ </programlisting> +</example> <para><emphasis role="bold">Notes:</emphasis></para> <orderedlist> @@ -1569,11 +1620,12 @@ inside it, are then ended. Control then passes to the clause following the END that matches the instruction of the selected block.</para> -<para><emphasis role="bold">Example:</emphasis></para> <indexterm><primary>LEAVE instruction</primary> <secondary>example</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>LEAVE instruction</secondary></indexterm> +<example> +<title>Instructions - LEAVE</title> <programlisting> max=5 do label myDoBlock /* define a label 'MYDOBLOCK' */ @@ -1590,6 +1642,7 @@ after looping 4 times */ </programlisting> +</example> <para><emphasis role="bold">Notes:</emphasis></para> <orderedlist> @@ -1760,11 +1813,12 @@ <para>NOP is a dummy instruction that has no effect. It can be useful as the target of a THEN or ELSE clause.</para> -<para><emphasis role="bold">Example:</emphasis></para> <indexterm><primary>NOP instruction</primary> <secondary>example</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>NOP instruction</secondary></indexterm> +<example> +<title>Instructions - NOP</title> <programlisting> Select when a=c then nop /* Do nothing */ @@ -1772,6 +1826,7 @@ otherwise say "A < C" end </programlisting> +</example> <note><title>Note</title> <para>Putting an extra semicolon instead of the NOP would @@ -2252,11 +2307,12 @@ Therefore, some of the caller's variables can be made accessible and can be changed, or new variables can be created. All these changes are visible to the caller upon RETURN from the routine.</para> -<para><emphasis role="bold">Example:</emphasis></para> <indexterm><primary>PROCEDURE instruction</primary> <secondary>example</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>PROCEDURE instruction</secondary></indexterm> +<example> +<title>Instructions - PROCEDURE</title> <programlisting> /* This is the main Rexx program */ j=1; z.1="a" @@ -2270,13 +2326,15 @@ k=7; m=3 /* Note: M is not exposed */ return </programlisting> +</example> <para>Note that if <computeroutput>Z.J</computeroutput> in the EXPOSE list is placed before <computeroutput>J</computeroutput>, the caller's value of <computeroutput>J</computeroutput> is not visible, so <computeroutput>Z.1</computeroutput> is not exposed.</para> <para>The variables in a subsidiary list are also exposed from left to right. </para> -<para><emphasis role="bold">Example:</emphasis></para> +<example> +<title>Instructions - PROCEDURE</title> <programlisting> /* This is the main Rexx program */ j=1;k=6;m=9 @@ -2289,10 +2347,12 @@ say a j k m /* Displays "j k m 1 6 9" */ return </programlisting> +</example> <para>You can use subsidiary lists to more easily expose a number of variables at a time or, with the VALUE built-in function, to manipulate dynamically named variables.</para> -<para><emphasis role="bold">Example:</emphasis></para> +<example> +<title>Instructions - PROCEDURE</title> <programlisting> /* This is the main Rexx program */ c=11; d=12; e=13 @@ -2310,12 +2370,14 @@ f=9 /* F was explicitly exposed */ return </programlisting> +</example> <indexterm><primary>stem of a variable</primary> <secondary>used in PROCEDURE instruction</secondary></indexterm> <para>Specifying a stem as <emphasis role="italic">name</emphasis> exposes this stem and all possible compound variables whose names begin with that stem. (See .)</para> -<para><emphasis role="bold">Example:</emphasis></para> +<example> +<title>Instructions - PROCEDURE</title> <programlisting> /* This is the main Rexx program */ a.=11; i=13; j=15 @@ -2334,6 +2396,7 @@ /* previously exist. */ return </programlisting> +</example> <note><title>Note</title> <para>Variables can be exposed through several generations @@ -2460,16 +2523,18 @@ a discussion of Rexx input and output.)</para> <para>If you do not specify <emphasis role="italic">expression</emphasis>, a null string is stacked.</para> -<para><emphasis role="bold">Example:</emphasis></para> <indexterm><primary>PUSH instruction</primary> <secondary>example</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>PUSH instruction</secondary></indexterm> +<example> +<title>Instructions - PUSH</title> <programlisting> a="Fred" push /* Puts a null line onto the queue */ push a 2 /* Puts "Fred 2" onto the queue */ </programlisting> +</example> <para> The QUEUED built-in function (described in <xref linkend="bifQueued" />) returns the number of lines currently in the external data queue.</para> @@ -2500,16 +2565,18 @@ for a discussion of Rexx input and output.)</para> <para>If you do not specify <emphasis role="italic">expression</emphasis>, a null string is queued.</para> -<para><emphasis role="bold">Example:</emphasis></para> <indexterm><primary>QUEUE instruction</primary> <secondary>example</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>QUEUE instruction</secondary></indexterm> +<example> +<title>Instructions - QUEUE</title> <programlisting> a="Toft" queue a 2 /* Enqueues "Toft 2" */ queue /* Enqueues a null line behind the last */ </programlisting> +</example> <para> The QUEUED built-in function (described in <xref linkend="bifQueued" />) returns the number of lines currently in the external data queue.</para> @@ -2667,11 +2734,12 @@ <xref linkend="atwcnt" />). If specified, the result value can be obtained from the RESULT entry of the condition object.</para> -<para><emphasis role="bold">Examples:</emphasis></para> <indexterm><primary>RAISE instruction</primary> <secondary>example</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>RAISE instruction</secondary></indexterm> +<example> +<title>Instructions - RAISE</title> <programlisting> raise syntax 40 /* Raises syntax error 40 */ raise syntax 40.12 array (1, number) /* Raises syntax error 40, subcode 12 */ @@ -2680,13 +2748,15 @@ /* as the syntax error number */ raise user badvalue /* Raises user condition BADVALUE */ </programlisting> +</example> <para>If you specify PROPAGATE, and there is a currently trapped condition, this condition is raised again in the caller (for a routine) or sender (for a method). Any ADDITIONAL, DESCRIPTION, ARRAY, RETURN, or EXIT information specified on the RAISE instruction replaces the corresponding values for the currently trapped condition. A SYNTAX error occurs if no condition is currently trapped. </para> -<para><emphasis role="bold">Example:</emphasis></para> +<example> +<title>Instructions - RAISE</title> <programlisting> signal on syntax a = "xyz" @@ -2698,6 +2768,7 @@ syntax: raise propagate /* Propagates SYNTAX information to caller */ </programlisting> +</example> </section> <section id="keyReply"><title>REPLY</title> @@ -2725,17 +2796,18 @@ <para>Unlike RETURN or EXIT, the method issuing REPLY continues to run after the REPLY until it issues an EXIT or RETURN instruction. The EXIT or RETURN must not specify a result expression.</para> -<para><emphasis role="bold">Example:</emphasis></para> <indexterm><primary>REPLY instruction</primary> <secondary>example</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>REPLY instruction</secondary></indexterm> +<example> +<title>Instructions - REPLY</title> <programlisting> reply 42 /* Returns control and a result */ call tidyup /* Can run in parallel with sender */ return </programlisting> -<para></para> +</example> <para><emphasis role="bold">Notes:</emphasis></para> <orderedlist> @@ -2876,11 +2948,12 @@ </itemizedlist> <para>See <xref linkend="bifLineout" /> for details of the LINEOUT function.</para> -<para><emphasis role="bold">Example:</emphasis></para> <indexterm><primary>SAY instruction</primary> <secondary>example</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>SAY instruction</secondary></indexterm> +<example> +<title>Instructions - SAY</title> <programlisting> <![CDATA[ data=100 @@ -2888,6 +2961,7 @@ /* Displays: "100 divided by 4 => 25" */ ]]> </programlisting> +</example> <para><emphasis role="bold">Notes:</emphasis></para> <orderedlist> @@ -2951,11 +3025,12 @@ to the instructions, if any, after OTHERWISE. In this situation, the absence of an OTHERWISE produces an error, however, you can omit the instruction list that follows OTHERWISE.</para> -<para><emphasis role="bold">Example:</emphasis></para> <indexterm><primary>SELECT instruction</primary> <secondary>example</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>SELECT instruction</secondary></indexterm> +<example> +<title>Instructions - SELECT</title> <programlisting> <![CDATA[ balance=100 @@ -2977,6 +3052,7 @@ end /* Select */ ]]> /</programlisting> +</example> <para>The <emphasis role="italic">expression</emphasis> may also be a list of expressions separated by ",". Each subexpression must evaluate to @@ -2986,7 +3062,8 @@ will be returned as the condition result. If all of the subexpressions evaluate to <computeroutput>1</computeroutput>, then the condition result is also <computeroutput>1</computeroutput>.</para> -<para><emphasis role="bold">Example:</emphasis></para> +<example> +<title>Instructions - SELECT</title> <programlisting> select when answer~datatype('w'), answer//2 = 0 Then @@ -3010,6 +3087,7 @@ say answer "is not a number" end </programlisting> +</example> <para>The logical & operator will evaluate both terms of the operation, so the term "answer//2" will result in a syntax error if answer is a non-numeric value. With the list conditional form, evaluation will stop with the first false result, so the @@ -3141,17 +3219,19 @@ and <emphasis role="italic">usercondition</emphasis> are single symbols, which are taken as constants. The <emphasis role="italic">trapname</emphasis> is a string or symbol taken as a constant.</para> -<para><emphasis role="bold">Example:</emphasis></para> <indexterm><primary>SIGNAL instruction</primary> <secondary>example</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>SIGNAL instruction</secondary></indexterm> +<example> +<title>Instructions - SIGNAL</title> <programlisting> Signal fred; /* Transfer control to label FRED below */ .... .... Fred: say "Hi!" </programlisting> +</example> <para>If there are duplicates, control is always passed to the first occurrence of the label in the program. </para> @@ -3378,6 +3458,7 @@ number of clauses. For example, <computeroutput>TRACE -100</computeroutput> means that the next 100 clauses that would usually be traced are not displayed. After that, tracing resumes as before.</para> +</section> <section id="trnotes"><title>Tracing Tips</title> <indexterm><primary>tracing</primary> @@ -3397,19 +3478,20 @@ function, and method calls. See <xref linkend="keyCall" /> for more details. </para></listitem></itemizedlist> -</section> -<section id="traceexmp"><title>Example</title> <indexterm><primary>TRACE instruction</primary> <secondary>example</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>TRACE instruction</secondary></indexterm> <para>One of the most common traces you will use is: </para> +<example> +<title>Instructions - TRACE</title> <programlisting> TRACE ?R /* Interactive debugging is switched on if it was off, */ /* and tracing results of expressions begins. */ </programlisting> +</example> </section> <section id="tracfor"><title>The Format of Trace Output</title> @@ -3604,9 +3686,7 @@ in error is always traced.</para> </section> </section> -</section> - <section id="keyUse"><title>USE</title> <indexterm><primary>USE instruction</primary> <secondary>description</secondary></indexterm> @@ -3661,11 +3741,12 @@ defining a minimum amount of arguments that must be supplied or for which there are default values defined and that may be followed optionally by any additional arguments.</para> -<para><emphasis role="bold">Example:</emphasis></para> <indexterm><primary>USE instruction</primary> <secondary>example</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>USE instruction</secondary></indexterm> +<example> +<title>Instructions - USE</title> <programlisting> /* USE Example */ /* FRED("Ogof X",1,5) calls function */ @@ -3700,10 +3781,12 @@ /* NUM1 contains "1" */ /* NUM2 contains "4" */ </programlisting> +</example> <para>In the above example, a call to the function FRED may have either 2 or 3 arguments. The STRICT keyword on the USE instruction will raise a syntax error for any other combination of arguments.</para> -<para><emphasis role="bold">Example:</emphasis></para> +<example> +<title>Instructions - USE</title> <programlisting> call test "one" call test "one", "two" @@ -3735,8 +3818,11 @@ arg # 5=[five] -- </programlisting> +</example> <para>The assignment targets may be any term that can be on the left side of -an assignment statement. For example,</para> +an assignment statement.</para> +<example> +<title>Instructions - USE</title> <programlisting> expose myArray myDirectory use arg myArray[1], myDirectory~name @@ -3746,6 +3832,7 @@ myArray[1] = arg(1) myDirectory~name = arg(2) </programlisting> +</example> <para>You can retrieve or check the arguments by using the ARG built-in function (see <xref linkend="bifArg" />). The ARG and PARSE ARG instructions are alternative Modified: docs/trunk/publican/rexxref/en-US/intro.xml =================================================================== --- docs/trunk/publican/rexxref/en-US/intro.xml 2012-09-10 03:08:58 UTC (rev 8395) +++ docs/trunk/publican/rexxref/en-US/intro.xml 2012-09-10 20:25:00 UTC (rev 8396) @@ -289,11 +289,14 @@ <secondary>aquiring</secondary></indexterm> <indexterm><primary>polymorphism</primary></indexterm> <para>Rexx lets you send the same message to objects that are different:</para> +<example> +<title>Polymorphism</title> <programlisting> "!iH"~reverse /* Reverses the characters "!iH" to form "Hi!" */ pen~reverse /* Reverses the direction of a plotter pen */ ball~reverse /* Reverses the direction of a moving ball */ </programlisting> +</example> <para>As long as each object has its own REVERSE method, REVERSE runs even if the programming implementation is different for each object. This @@ -583,6 +586,8 @@ <computeroutput>/*</computeroutput> or <computeroutput>*/</computeroutput> as part of a literal string. Consider the following program segment: </para> +<example> +<title>Comments</title> <programlisting> 01 parse pull input 02 if substr(input,1,5) = "/*123" @@ -597,6 +602,7 @@ 03 then call process 04 */ dept = substr(input,32,5) </programlisting> +</example> <para>This is incorrect because the language processor would interpret the <computeroutput>/*</computeroutput> that is part of the literal string <computeroutput>/*123</computeroutput> as the start @@ -610,21 +616,27 @@ if substr(input,1,5) = "/" || "*123" </programlisting> <para>You could comment out lines 2 and 3 correctly as follows: </para> +<example> +<title>Comments</title> <programlisting> 01 parse pull input 02 /* if substr(input,1,5) = "/" || "*123" 03 then call process 04 */ dept = substr(input,32,5) </programlisting> +</example> <para>Both types of comments can be mixed and nested. However, when you nest the two types, the type of comment that comes first takes precedence over the one nested. Here is an example:</para> +<example> +<title>Comments</title> <programlisting> "Fred" "Don't Panic!" 'You shouldn''t' /* Same as "You shouldn't" "" -- The null string */ </programlisting> +</example> <para>In this example, the language processor ignores everything after <computeroutput>'You shouldn''t'</computeroutput> up to the end of the last line. In this case, the standard comment has precedence over the line comment. @@ -632,13 +644,15 @@ <para>When nesting the two comment types, make sure that the start delimiter of the standard comment <computeroutput>/*</computeroutput> is not in the line commented out with the line comment signs.</para> -<para><emphasis role="bold">Example:</emphasis></para> +<example> +<title>Comments</title> <programlisting> "Fred" "Don't Panic!" 'You shouldn''t' -- Same as /* "You shouldn't" "" The null string */ </programlisting> +</example> <para>This example produces an error because the language processor ignores the start delimiter of the standard comment, which is commented out using the line comment.</para> @@ -698,12 +712,15 @@ <computeroutput>0</computeroutput>) is called a <emphasis>null string</emphasis>.</para> <para>These are valid strings: </para> +<example> +<title>Valid strings</title> <programlisting> "Fred" "Don't Panic!" 'You shouldn''t' /* Same as "You shouldn't" */ "" /* The null string */ </programlisting> +</example> <para><emphasis role="bold">Implementation maximum:</emphasis> <indexterm><primary>implementation maximum</primary> <secondary>literal strings</secondary></indexterm> @@ -756,11 +773,14 @@ cannot directly enter the characters themselves. These are valid hexadecimal strings: </para> +<example> +<title>Valid hexadecimal strings</title> <programlisting> "ABCD"x "1d ec f8"X "1 d8"x </programlisting> +</example> <note><title>Note</title> <para>A hexadecimal string is <emphasis>not</emphasis> a representation @@ -817,6 +837,8 @@ allow you to specify characters explicitly, bit by bit. These are valid binary strings: </para> +<example> +<title>Valid binary strings</title> <programlisting> "11110000"b /* == "f0"x */ "101 1101"b /* == "5d"x */ @@ -824,6 +846,7 @@ "10000 10101010"b /* == "0001 0000 1010 1010"b */ ""b /* == "" */ </programlisting> +</example> <para><emphasis role="bold">Implementation maximum:</emphasis> <indexterm><primary>binary</primary> <secondary>strings</secondary> @@ -870,11 +893,14 @@ <computeroutput>A</computeroutput>-<computeroutput>Z</computeroutput>) before use.</para> <para>These are valid symbols: </para> +<example> +<title>Valid symbols</title> <programlisting> Fred Albert.Hall WHERE? </programlisting> +</example> <para>If a symbol does not begin with a digit or a period, you can use it as a variable and can assign it a value. If you have not assigned a value to it, its value is the characters of the symbol itself, translated to uppercase @@ -900,16 +926,22 @@ <para>These are valid numbers in exponential notation: </para> <indexterm><primary>exponential notation</primary> <secondary>example</secondary></indexterm> +<example> +<title>Valid exponential numbers</title> <programlisting> 17.3E-12 .03e+9 </programlisting> +</example> <para>These are not valid numbers in exponential notation, but rather multiple tokens with an operator between:</para> +<example> +<title>Invalid exponential numbers</title> <programlisting> .E-12 -- no digits 3ae+6 -- non-digit character 3..0e+9 -- more than one '.' </programlisting> +</example> </section> <section id="numbrs"><title>Numbers</title> @@ -941,6 +973,8 @@ number cannot be the name of a variable. </para> <para>These are valid numbers: </para> +<example> +<title>Valid numbers</title> <programlisting> 12 "-17.9" @@ -948,6 +982,7 @@ 73e+128 " + 7.9E5 " </programlisting> +</example> <para>You can specify numbers with or without quotation marks around them. Note that the sequence <computeroutput>-17.9</computeroutput> (without quotation marks) in an expression @@ -999,12 +1034,15 @@ used to indicate assignment. Whitespace characters adjacent to operator characters are removed. Therefore, the following are identical in meaning: </para> +<example> +<title>White space and numbers</title> <programlisting> 345>=123 345 >=123 345 >= 123 345 > = 123 </programlisting> +</example> <para>Some of these characters (and some special characters—see the next section) might not be available in all character sets. In this case, appropriate translations can be used. @@ -1079,9 +1117,12 @@ example shows how a clause is composed of tokens:</para> <indexterm><primary>examples</primary> <secondary>special characters</secondary></indexterm> +<example> +<title>Special characters</title> <programlisting> "REPEAT" A + 3; </programlisting> +</example> <para>This example is composed of six tokens—a literal string (<computeroutput>"REPEAT"</computeroutput>), a blank operator, a symbol (<computeroutput>A</computeroutput>, which can have an assigned @@ -1160,6 +1201,8 @@ <secondary>example</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>continuation</secondary></indexterm> +<example> +<title>Continuations</title> <programlisting> say "You can use a comma", -- this line is continued "to continue this clause." @@ -1168,6 +1211,7 @@ say "You can use a minus"- -- this line is continued "to continue this clause." </programlisting> +</example> </section> </section> @@ -1831,7 +1875,6 @@ </tbody> </tgroup> </informaltable> -<para><emphasis role="bold">Examples:</emphasis></para> <para>Suppose the symbol <computeroutput>A</computeroutput> is a variable whose value is <computeroutput>3</computeroutput>, <computeroutput>DAY</computeroutput> is a variable whose value is @@ -1841,6 +1884,8 @@ <secondary>expressions</secondary></indexterm> <indexterm><primary>expressions</primary> <secondary>examples</secondary></indexterm> +<example> +<title>Arithmetic</title> <programlisting> <![CDATA[ A+5 -> "8" @@ -1864,6 +1909,7 @@ "!"xxx"!" -> "!XXX!" ]]> </programlisting> +</example> <note><title>Note</title> <para>The Rexx order of precedence usually causes no difficulty because it is the @@ -1875,11 +1921,15 @@ <listitem><para>Power operators (like other operators) are evaluated from left to right.</para></listitem></itemizedlist></para> <para>For example: </para> +<example> +<title>Arithmetic</title> <programlisting> -3**2 == 9 /* not -9 */ -(2+1)**2 == 9 /* not -9 */ 2**2**3 == 64 /* not 256 */ -</programlisting></note> +</programlisting> +</example> +</note> </section> <section id="mssg"><title>Message Terms</title> @@ -1976,12 +2026,15 @@ <para>For example, the message [] is valid for arrays (see <xref linkend="clsArray" />) and you could code:</para> +<example> +<title>Arrays</title> <programlisting> a = .array~of(10,20) say "Second item is" a[2] /* Same as: a~at(2) */ /* or a~"[]"(2) */ /* Produces: "Second item is 20" */ </programlisting> +</example> <indexterm><primary>arguments</primary> <secondary>passing in messages</secondary></indexterm> <para>A message can have a variable number of arguments. You need to specify @@ -2010,6 +2063,8 @@ <computeroutput>~</computeroutput> returns the result of the method. Using <computeroutput>~~</computeroutput> returns the object that received the message. Here is an example: </para> +<example> +<title>Messages</title> <programlisting> /* Two ways to use the INSERT method to add items to a list */ /* Using only ~ */ @@ -2028,6 +2083,7 @@ say "First on the team is:" team~firstitem /* Bob */ say "Last on the team is:" team~lastitem /* Steve */ </programlisting> +</example> <para>Thus, you would use ~ when you want the returned result to be the receiver of the next message in the sequence. </para> @@ -2255,12 +2311,14 @@ However, if it is a compound symbol (described in <xref linkend="compsym" />), its value is the derived name of the symbol.</para> -<para><emphasis role="bold">Example:</emphasis></para> +<example> +<title>Derived symbol names</title> <programlisting> /* If Freda has not yet been assigned a value, */ /* then next line gives FRED the value "FREDA" */ Fred=Freda </programlisting> +</example> <indexterm><primary>symbol</primary> <secondary>classifying</secondary></indexterm> <indexterm><primary>symbol</primary> @@ -2316,6 +2374,8 @@ consisting of the characters of the symbol (that is, with any lowercase alphabetic characters translated to uppercase).</para> <para>These are constant symbols: </para> +<example> +<title>Constants</title> <programlisting> 77 827.53 @@ -2324,6 +2384,7 @@ 3D 17E-3 </programlisting> +</example> <para>Symbols where the first character is a period and the second character is alphabetic are environment symbols (<xref linkend="ensym" />) and @@ -2344,11 +2405,14 @@ to uppercase). If the symbol has been assigned a value, it names a variable and its value is the value of that variable.</para> <para>These are simple symbols: </para> +<example> +<title>Simple symbols</title> <programlisting> FRED Whatagoodidea? /* Same as WHATAGOODIDEA? */ ?12 </programlisting> +</example> </section> <section id="stems"><title>Stems</title> @@ -2360,10 +2424,14 @@ a symbol that contains a single period as the last character of the name. It cannot start with a digit.</para> <para>These are stems: </para> +<example> +<title>Stems</title> <programlisting> FRED. A. -</programlisting><para>The value of a stem is always a Stem object. (See +</programlisting> +</example> +<para>The value of a stem is always a Stem object. (See <xref linkend="clsStem" />.) The stem variable's Stem object is automatically created the first time you use the stem variable or a @@ -2385,7 +2453,8 @@ the new Stem object will replace the the Stem object that is currently associated with the stem variable. This can result in multiple stem variables referring to a the same Stem object, effectively creating a variable alias.</para> -<para><emphasis role="bold">Example:</emphasis></para> +<example> +<title>Stems</title> <programlisting> hole. = "empty" hole.19 = "full" @@ -2398,6 +2467,7 @@ /* Also says "empty empty full" */ </programlisting> +</example> <para>If the new value is not a Stem object, a new Stem object is created and assigned to the stem variable, replacing the Stem object currently associated with the stem variable.</para> @@ -2407,13 +2477,15 @@ the assignment, a reference to any compound symbol with that stem variable returns the new value until another value is assigned to the stem, the Stem object, or the individual compound variable.</para> -<para><emphasis role="bold">Example:</emphasis></para> +<example> +<title>Stems</title> <programlisting> hole. = "empty" hole.19 = "full" say hole.1 hole.mouse hole.19 /* says "empty empty full" */ </programlisting> +</example> <indexterm><primary>initialization</primary> <secondary>of arrays</secondary></indexterm> <indexterm><primary>initialization</primary> @@ -2421,7 +2493,8 @@ <para>Thus, you can initialize an entire collection of compound variables to the same value.</para> <para>You can pass stem collections as function, subroutine, or method arguments.</para> -<para><emphasis role="bold">Example:</emphasis></para> +<example> +<title>Stems</title> <programlisting> /* CALL RANDOMIZE count, stem. calls routine */ Randomize: Use Arg count, stem. @@ -2430,6 +2503,7 @@ end return </programlisting> +</example> <para>The USE ARG instruction functions as an assignment instruction. The variable STEM. in the example above is functionally equivalent to:</para> <programlisting> @@ -2441,7 +2515,8 @@ <para>Stems can also be returned as function, subroutine, or method results. The resulting return value is the Stem object associated with the stem variable. </para> -<para><emphasis role="bold">Example:</emphasis></para> +<example> +<title>Stems</title> <programlisting> /* RANDOMIZE(count) calls routine */ Randomize: Use Arg count @@ -2450,25 +2525,32 @@ end return stem. </programlisting> +</example> <para>When a stem. variable is used in an expression context, the stem variable reference returns the associated Stem object. The Stem object will forward many object messages to it's default value. For example, the STRING method will return the Stem object's default value's string representation:</para> +<example> +<title>Stems</title> <programlisting> total. = 0 say total. /* says "0" */ </programlisting> +</example> <para>The [] method with no arguments will return the currently associated default value. variables can always be obtained by using the stem. However, this is not the same as using a compound variable whose derived name is the null string.</para> +<example> +<title>Stems</title> <programlisting> total. = 0 null = "" total.null = total.null + 5 say total.[] total.null /* says "0 5" */ </programlisting> +</example> <para>You can use the DROP, EXPOSE, and PROCEDURE instructions to manipulate collections of variables, referred to by their stems. <computeroutput>DROP FRED.</computeroutput> assigns @@ -2551,11 +2633,14 @@ with embedded signs (for example, 12.3E+5) after a stem; in this case the whole symbol would not be valid.</para> <para>These are compound symbols: </para> +<example> +<title>Compound symbols</title> <programlisting> FRED.3 Array.I.J AMESSY..One.2. </programlisting> +</example> <para>Before the symbol is used, that is, at the time of reference, the language processor substitutes in the compound symbol the character string values of any simple @@ -2595,6 +2680,8 @@ no limit on the length of the evaluated name.</para> <para>Some examples of simple and compound symbols follow in the form of a small extract from a Rexx program: </para> +<example> +<title>Compound symbols</title> <programlisting> a=3 /* assigns "3" to the variable A */ z=4 /* "4" to Z */ @@ -2608,6 +2695,7 @@ /* displays the string: */ /* "3 4 Fred A.3 Fred Bill C.3 5 Annie" */ </programlisting> +</example> <para>You can use compound symbols to set up arrays and lists of variables in which the subscript is not necessarily numeric, thus offering a great scope for the creative programmer. A useful application is to set up an array in @@ -2621,7 +2709,8 @@ and []= methods used by other collection classes. The [] method provides an alternate means of accessing compound variables that also allows embedded subexpressions.</para> -<para><emphasis role="bold">Examples:</emphasis></para> +<example> +<title>Evaluated compound variables</title> <programlisting> a=3 /* assigns "3" to the variable A */ z=4 /* "4" to Z */ @@ -2637,6 +2726,7 @@ /* displays the string: */ /* "3 4 Fred A.3 Fred Rick Bill C.3 5 Annie" */ </programlisting> +</example> </section> </section> @@ -2649,6 +2739,8 @@ to uppercase). If the symbol identifies an object in the current environment, its value is the mapped object.</para> <para>These are environment symbols: </para> +<example> +<title>Environment symbols</title> <programlisting> .method // A reference to the Rexx Method class @@ -2656,6 +2748,7 @@ .xyz // Normally the value .XYZ </programlisting> +</example> <para>When you use an environment symbol, the language processor performs a series of searches to see if the environment symbol has an assigned value. The search locations and their ordering are: @@ -2737,12 +2830,14 @@ A message term using ~~ is sometimes referred to as a <emphasis role="italic">cascading message</emphasis>. </para> -<para><emphasis role="bold">Example:</emphasis></para> <indexterm><primary>examples</primary> <secondary>message instructions</secondary></indexterm> +<example> +<title>Message instructions</title> <programlisting> mytable~add("John",123) </programlisting> +</example> <para>This sends the message ADD to the object MYTABLE. The ADD method need not return a result. If ADD returns a result, the result is assigned to the variable RESULT.</para> @@ -2753,22 +2848,25 @@ message name. The result of evaluating the expression is passed as the first argument of the message.</para> -<para><emphasis role="bold">Example:</emphasis></para> - +<example> +<title>Message instructions</title> <programlisting> person~age = 39 /* Same as person~"AGE="(39) */ table[i] = 5 /* Same as table~"[]="(5,i) */ </programlisting> +</example> <para>The expressions are evaluated in the order in which the arguments are passed to the method. That is, the language processor evaluates the <computeroutput>=expression</computeroutput> first. Then it evaluates the argument expressions within any [] pairs from left to right.</para> <para>The extended assignment form may also be used with messaging terms.</para> -<para><emphasis role="bold">Example:</emphasis></para> +<example> +<title>Message instructions</title> <programlisting> table[i] += 1 -- Same as table[i] = table[i] + 1 </programlisting> +</example> <para>See <xref linkend="extassign" /> for more details</para> </section> @@ -2874,18 +2972,24 @@ <computeroutput>0</computeroutput>.</para> <para>Here is an example of submitting a command. Where the default environment is Windows, the sequence:</para> +<example> +<title>Commands</title> <programlisting> fname = "CHESHIRE" exten = "CAT" "TYPE" fname"."exten </programlisting> +</example> <para>would result in passing the string <computeroutput>TYPE CHESHIRE.CAT</computeroutput> to the command processor, CMD.EXE. The simpler expression:</para> +<example> +<title>Commands</title> <programlisting> "TYPE CHESHIRE.CAT" </programlisting> +</example> <para>has the same effect.</para> <para>On return, the return code placed in RC will have the value 0 if the file CHESHIRE.CAT were typed, or a nonzero value if the file could @@ -2895,7 +2999,8 @@ <para>Remember that the expression is evaluated before it is passed to the environment. Constant portions of the command should be specified as literal strings.</para></note> -<para><emphasis role="bold">Windows Example:</emphasis></para> +<example> +<title>Commands - Windows</title> <programlisting> delete "*".lst /* not "multiplied by" */ var.003 = anyvalue @@ -2904,7 +3009,9 @@ w = any dir"/w" /* not "divided by ANY" */ </programlisting> -<para><emphasis role="bold">Linux Example:</emphasis></para> +</example> +<example> +<title>Commands - Linux</title> <programlisting> rm "*".lst /* not "multiplied by" */ var.003 = anyvalue @@ -2913,6 +3020,7 @@ w = any ls "/w" /* not "divided by ANY" */ </programlisting> +</example> <para> Enclosing an entire message instruction in parentheses causes @@ -2942,12 +3050,14 @@ If you call another program by a Rexx command, the program is executed in a new process and therefore does not share .environment, .local, or the Windows/Unix shell environment.</para> -<para><emphasis role="bold">Examples:</emphasis></para> +<example> +<title>Calling other Rexx scripts</title> <programlisting> call "other.REX" /* runs in the same process */ "rexx other.REX" /* runs in a new child process */ "start rexx other.REX" /* runs in a new detached process */ </programlisting> +</example> <para>When Rexx programs call other Rexx programs as commands, the return code of the command is the exit value of the called program provided that this value is a whole number in the range -32768 to 32767. Otherwise, the exit Modified: docs/trunk/publican/rexxref/en-US/iostrms.xml =================================================================== --- docs/trunk/publican/rexxref/en-US/iostrms.xml 2012-09-10 03:08:58 UTC (rev 8395) +++ docs/trunk/publican/rexxref/en-US/iostrms.xml 2012-09-10 20:25:00 UTC (rev 8396) @@ -75,15 +75,21 @@ of both stream objects, or overlays occur.</para> <para>To obtain a stream object (for example, <computeroutput>MYFIL</computeroutput>), you could use: </para> +<example> +<title>Obtaining a stream object</title> <programlisting> MyStream = .stream~new("MYFIL") </programlisting> +</example> <para>You can manipulate stream objects with character or line methods: </para> <indexterm><primary>character input and output</primary></indexterm> +<example> +<title>Performing input on a stream object</title> <programlisting> nextchar = MyStream~charin() nextline = MyStream~linein() </programlisting> +</example> <para>In addition to stream objects, the language processor defines an external data queue object for interprogram communication. This queue object understands line functions only.</para> @@ -315,7 +321,8 @@ </itemizedlist> <para>Here is an example of using a queue:</para> -<figure><title>Sample Rexx Procedure Using a Queue</title> +<example> +<title>Sample Rexx Procedure Using a Queue</title> <programlisting> /* */ /* push/pull WITHOUT multiprogramming support */ @@ -342,7 +349,7 @@ call RXQUEUE "Delete",newq /* destroy unique queue created */ call RXQUEUE "Set",oq /* reset to default queue (not required) */ </programlisting> -</figure> +</example> <para>Special considerations:</para> <itemizedlist> <listitem><para>External programs that must communicate with a @@ -557,6 +564,8 @@ <secondary>FILECOPY program</secondary></indexterm> <indexterm><primary>examples</primary> <secondary>of program</secondary></indexterm> +<example> +<title>FILECOPY program</title> <programlisting> /* FILECOPY.CMD */ /* This routine copies, as lines, the stream or */ @@ -580,6 +589,7 @@ notready: return </programlisting> +</example> <para>As long as lines remain in the named input stream, a line is read and is then immediately written to the named output stream. This program is easy to change so that it filters the lines before writing them.</para> @@ -591,6 +601,8 @@ <secondary>COLLECTOR program</secondary></indexterm> <indexterm><primary>programs</primary> <secondary>examples</secondary></indexterm> +<example> +<title>COLLECT program</title> <programlisting> /* COLLECT.CMD */ /* This routine collects characters from the stream */ @@ -610,6 +622,7 @@ end queue buffer /* place it on the external data queue */ </programlisting> +</example> <para>Here each line is built up in a variable called <computeroutput>BUFFER</computeroutput>. When the line is complete (for example, when the user presses the Enter key) the Modified: docs/trunk/publican/rexxref/en-US/numarit.xml =================================================================== --- docs/trunk/publican/rexxref/en-US/numarit.xml 2012-09-10 03:08:58 UTC (rev 8395) +++ docs/trunk/publican/rexxref/en-US/numarit.xml 2012-09-10 20:25:00 UTC (rev 8396) @@ -60,6 +60,8 @@ characters are permitted, and exponential notation can be used. Valid numbers are, for example: </para> +<example> +<title>Numbers</title> <programlisting> 12 /* a whole number */ "-76" /* a signed whole number */ @@ -70,6 +72,7 @@ 4E9 /* exponential notation */ 0.73e-7 /* exponential notation */ </programlisting> +</example> <para>A number in Rexx is defined as follows:</para> <programlisting> <![CDATA[ @@ -132,12 +135,15 @@ For example, the division of 2 by 3 results in 0.666666667.</para></listitem> <listitem><para>Except for division and power, trailing zeros are preserved. For example: +<example> +<title>Arithmetic</title> <programlisting> 2.40 + 2 -> 4.40 2.40 - 2 -> 0.40 2.40 * 2 -> 4.80 2.40 / 2 -> 1.2 </programlisting> +</example> If necessary, you can remove trailing zeros with the STRIP method (see <xref linkend="mthStringStrip" />), the @@ -151,10 +157,13 @@ before the decimal point exceeds the NUMERIC DIGITS setting, or the number of places after the point exceeds twice the NUMERIC DIGITS setting, the number is expressed in exponential notation: +<example> +<title>Arithmetic</title> <programlisting> 1e6 * 1e6 -> 1E+12 /* not 1000000000000 */ 1 / 3E10 -> 3.33333333E-11 /* not 0.0000000000333333333 */ </programlisting> +</example> </para></listitem></itemizedlist> <section id="prec"><title>Precision</title> @@ -282,7 +291,8 @@ <indexterm><primary>examples</primary> <secondary>operator examples</secondary></indexterm> <indexterm><primary>basic operator examples</primary></indexterm> -<para></para> +<example> +<title>Operators</title> <programlisting> /* With: NUMERIC DIGITS 5 */ 12+7.00 -> 19.00 @@ -309,6 +319,7 @@ 10//0.3 -> 0.1 3.6//1.3 -> 1.0 </programlisting> +</example> </section> </section> @@ -371,6 +382,8 @@ <secondary>exponential, example</secondary></indexterm> <indexterm><primary>operator</primary> <secondary>examples</secondary></indexterm> +<example> +<title>Exponential notation</title> <programlisting> 12E7 = 120000000 /* Displays "1" */ 12E-5 = 0.00012 /* Displays "1" */ @@ -378,6 +391,7 @@ 0e123 = 0e456 /* Displays "1" */ 0e123 == 0e456 /* Displays "0" */ </programlisting> +</example> <para>The results of calculations are returned in either conventional or exponential form, depending on the setting of <indexterm><primary>NUMERIC instruction</primary> @@ -418,6 +432,8 @@ </programlisting> <para> Scientific notation is the default. </para> +<example> +<title>Scientific notation</title> <programlisting> /* after the instruction */ Numeric form scientific @@ -429,6 +445,7 @@ 123.45 * 1e11 -> 12.345E+12 </programlisting> +</example> </section> <section id="numcom"><title>Numeric Comparisons</title> @@ -500,7 +517,6 @@ to 8 significant digits, just as though <computeroutput>NUMERIC DIGITS 8</computeroutput> had been put in effect for the duration of the operation.</para> -<para><emphasis role="bold">Example:</emphasis></para> <indexterm><primary>arithmetic</primary> <secondary>numeric comparisons example</secondary> <tertiary>examples</tertiary></indexterm> @@ -510,6 +526,8 @@ <secondary>numeric, example</secondary></indexterm> <indexterm><primary>numeric</primary> <secondary>comparisons, example</secondary></indexterm> +<example> +<title>Comparison</title> <programlisting> <![CDATA[ Numeric digits 5 @@ -521,6 +539,7 @@ say 4.9999 < 5 /* Displays "0" */ ]]> </programlisting> +</example> </section> <section id="nudbr"><title>Limits and Errors when Rexx Uses Numbers Directly</title> Modified: docs/trunk/publican/rexxref/en-US/oneof.xml =================================================================== --- docs/trunk/publican/rexxref/en-US/oneof.xml 2012-09-10 03:08:58 UTC (rev 8395) +++ docs/trunk/publican/rexxref/en-US/oneof.xml 2012-09-10 20:25:00 UTC (rev 8396) @@ -58,8 +58,8 @@ Environment use the same name as the corresponding environment symbol, but without a leading period. For example: </para> <programlisting> - say .true -- Displays "1" - say .environment~true -- Also displays "1" + say .true -> Displays "1" + say .environment~true -> Also displays "1" </programlisting> <para>The Environment object directory contains all of the Rexx built-in classes (Array, etc.), plus special Rexx constants such as .NIL, .TRUE, and .FALSE.</para> @@ -142,7 +142,8 @@ retrievable via the BIF ARG(1). The array supplied by the .LOCAL environment is a direct collection of the individual C arguments passed to the program. The name of this array is SYSCARGS.</para> -<para><emphasis role="bol... [truncated message content] |