Conference vaxuum::document_ft

118.0. "<EXAMPLE> problem - Bug?" by DECWET::CUSTER () Mon Mar 16 1987 20:16

    In one of my files, I'm getting the error message "Error found by
    TEX on page 2-10."  The output is incorrectly produced and I can't
    figure out if I've coded something incorrectly or if it's a bug.
    
    The problem occurs in a formal example that contains callouts. The
    example itself is not printed at all, but the callout list following it
    is printed.  The output page where the example should be is the same
    page where the TEX error occurs.  I've extracted the example and the
    callout list from the rest of the file and it will not run by itself
    either. 
    
    Here's the extracted text that's producing the bug (Sorry for the
    length of the example, but it's a difficult example to shorten.
    Presumably, the callout list can be ignored since it doesn't seem to be
    producing the problem).  In addition to the file shown below, I've
    also added an <EXAMPLE_ATTRIBUTES> tag using both the MULTIPAGE
    and the KEEP parameters (in different runs).  Both of those trials
    also produced the same TEX error on the same page.

    Does anyone see a problem with this example?
    
    ############################################################### 
    
<P>
<REFERENCE>(sample_cmd_proc) presents a command procedure that can be
used for <REFERENCE>(C) program development and testing.

<EXAMPLE>(A Sample Command Procedure\sample_cmd_proc)
<CALLOUTS>(1\PREFIX)
<code_example>
<callout>$ !  This command procedure compiles, links, and executes
$ !       a program specified by the user, and then
$ !       deletes old versions of files from the user's
$ !       directories (purges).
<callout>$ on warning then exit
<callout>$ define LNK$LIBRARY  SYS$LIBRARY:VAXCRTL.OLB
<callout>$ if p1 .eqs. "" then goto DONE
<callout>$ cc  'p1
$ link  'p1
<callout>$ run  'p1
555.444
33.22
11
'alphabetic string'
<callout>$ count = 0
$ LOOP:
$ count = count + 1
$ if count .eqs. 1 then set default [EDMUND.WHITE]
$ if count .eqs. 2 then set default [EDMUND.BLACK]
$ if count .eqs. 3 then set default [EDMUND.GREY]
$ purge *.*
<callout>$ if count .nes. 3 then goto LOOP
$ DONE:
<callout>$ EXIT
<endcode_example>
<endcallouts>
<ENDEXAMPLE>


<p>
The following numbers correspond to the numbers in the previous example:

<LIST>(CALLOUT)
<LE>The exclamation point <parendchar>(!) is a comment delimiter.
<X>(ON DCL command)
<X>(EXIT DCL command)

<LE>The ON command establishes an error-handling routine for the command
procedure. This command specifies that the procedure is to exit if any error
occurs with a severity of warning or greater. Thus, if the CC command returns
with an unsuccessful status, the procedure executes an EXIT command that
causes the procedure to terminate immediately. Otherwise, the procedure
continues with the LINK command. If that command issues a warning or error,
the procedure exits. Otherwise, the RUN command executes.

<X>(LNK$LIBRARY logical name)
<X>(Libraries<XS>LNK$LIBRARY)
<X>(Libraries<XS>specifying to the linker)

<LE>The DEFINE command specifies a value for the logical name, LNK$LIBRARY, so
that the linker can resolve any references to a <REFERENCE>(C_RTL) function.  See
<REFERENCE>(linklibs) for more information concerning default object
libraries.

<X>(Command procedures<XS>parameters of)

<LE>The identifier, <VARIABLE>(p1), is the name of the first parameter
specified when invoking the command procedure.  The name for parameters is
p<emphasis>(n), where <emphasis>(n) is the position of the parameter in the
command line.  For example, the procedure may be executed as follows:

<interactive>
<s>($ )<u>(@EXAMPLE  SOURCE_FILE<key>(RETURN))
<endinteractive>

<p> In this execution, the parameter, SOURCE_FILE, is the only parameter. The
symbol, <VARIABLE>(p1), is given a value of SOURCE_FILE. In this procedure,
SOURCE_FILE is the name of a <REFERENCE>(C) source file, specified <emphasis>(without) a
file extension.  The procedure uses this name, along with the appropriate
default file extensions, to compile, link, and execute the program.

<LE>The apostrophe character <parendchar>(<single_quote>) tells the CC command
to compile the translated symbol. If you specify the parameter, <VARIABLE>(p1),
without the apostrophe character, DCL passes the file name P1.C to the compiler
instead of SOURCE_FILE.C.

<X>(Command procedures<XS>data for)
<LE>The lines that do not begin with a dollar sign prompt <parendchar>($)
contain input for the executing image.  When a command procedure executes, the
default input device is the command procedure itself, not standard input
(SYS$INPUT, the terminal).  Thus, the executing program reads the data from
the procedure file.  In a command procedure, any line that does not begin with
a dollar sign prompt is input data for the previous command or program.  The
input terminates and an actual end-of-file condition occurs when the
procedure encounters a new line beginning with the dollar sign prompt.

<LE>The assignment character <parendchar>(=) assigns values to a variable
(which is also known as a command symbol).  If you assign variables with the
equal sign <parendchar>(=), they appear in the local symbol table; they are
valid only within the command procedure.  If you assign variables with a
double equal sign <parendchar>(==), they appear on the global symbol table;
you can use the symbols after the command procedure has executed.

<X>(Command procedures<XS>looping within)
<LE>This IF statement tests to see if the value of variable <VARIABLE>(count)
is equal to <VALUE>(3).  If it is not, control is diverted back to the line
containing the LOOP label.  In this way, you can execute a series of DCL
commands repeatedly in a loop, until the procedure meets a certain condition.
In this example, the procedure deletes old versions of files in the user's
directories (purges); when all three directories have been purged, incrementing
the variable count by one with each execution of the loop, the loop terminates
and control passes to the next line in the command procedure.

<LE>The EXIT command terminates a command procedure.
<ENDLIST>

    

    While continuing to track down this bug, I've discovered that *none* of
    my formal examples containing callouts will process properly under
    DOCUMENT.  I receive the message mentioned in .0, then I get seemingly
    infinite "page too long" and "line too long" TeX errors.  The page
    numbers specified in the "page too long" errors are continually
    incremented.  Therefore, I can get "page too long at page 1-3566" in a
    bookrun that contains only 600 pages.  The same is true for individual
    files. 
    
    The formal example, as mentioned before, does not appear in the
    output file, but the callout list following the example does appear.
    
    Has anyone gotten formal examples containing callouts to work under
    DOCUMENT T1.0?   The conversion of my manual has come to a standstill
    now, as I can't find a way to get around this error.  Any assistance
    would be greatly appreciated.
    
    
    	-Helen

    
    There is a bug in the sensitivity to the positioning of the
    <callouts> tag. The file contains:
    
    <example>
    <callouts>
       .
       .
       .
    <endcallouts>
    <endexample>
    
    and these are appropriately nested, but the bug doesn't know it.
    The error doesn't occur if the tags are rearranged:
    
    <callouts>
    <example>
    
       .
       .
       .
    <endexample>
    <endcallouts>
    
    As far as the looping goes, I've put this in other notes. MULTIPAGE
    as a figure/example attribute and KEEP on a code example causes
    an infinite loop. I processed Helen's file with neither keyword
    and it comes out fine. 

I am having problems with the <example> tag.

With the following .gnc file:

<example>(title\acct_relation_ex)
The primary access path for the realtion is on the field account.
<endexample>

Run with the command:

DOCUMENT test S.S LN03/NOPRINT

----------------------------
The following messages appear at sys$output:

%DOC-I-IDENT, VAX DOCUMENT T1.0-001
[ T a g   T r a n s l a t i o n ]...
%TAG-I-TAG_IDENT, T1.0
%TAG-I-DEFSLOADD, End of Loading of Tag Definitions
%TAG-I-ENDPASS_1, End of first pass over the input
%TAG-I-CPU_USAGE, Pass 1: 2.3  Pass 2: 0.3  Total: 2.6 seconds
[ T e x t   F o r m a t t i n g ]...
%TEX-I-IDENT, T1.1











%TEX-E-TEXERROR, Error found by TeX
%TEX-I-ONPAGE, on page [1]
%TEX-I-OUTFILENAME, 'disk$fig_4:[prohaska.das]TEST.DVI_LN3'




%TEX-I-PAGESOUT, 1 page written.
%TEX-I-OUTFILENAME, 'disk$fig_4:[prohaska.das]TEST.DVI_LN3'
%DOC-E-ERROR_FORMATTER, Errors found by Text Formatter.
------------------------------------

The .lis file contains:

(DISK$FIG_4:[PROHASKA.DAS]TEST.TEX;4 (DOC$BL07_ROOT:[TEX.FORMATS]DOC$STARTUP.TE
X;1 (DOC$BL07_ROOT:[LOCAL.FORMATS]CUP$LOCAL_ELEMENTS.TEX;1) (DOC$BL07_ROOT:[TEX
.FORMATS]TAG$S_SPECIFICATION.DTP;1 (DOC$BL07_ROOT:[TEX.FORMATS]TAG$STANDARD_FON
TS.LN;1)) (DOC$BL07_ROOT:[TEX.LN03.FONTS]LN03CHARS.TEX;1))
%TEX-E-TEXERROR, Error found by TeX

%TEX-I-ONPAGE, on page [1]

%TEX-I-OUTFILENAME, 'disk$fig_4:[prohaska.das]TEST.DVI_LN3'
\endgroup.
\endfigure ...goal =\MACdimenA \fi \par \endgroup 
                                                  \vsize =\figsavevsize 
l.8 \endfigure
              
Things are pretty mixed up, but I think the worst is over.

) [1]
%TEX-I-PAGESOUT, 1 page written.

%TEX-I-OUTFILENAME, 'disk$fig_4:[prohaska.das]TEST.DVI_LN3'

--------------------

The .tex file contains:
\begintexinput
%This file created using VAX DOCUMENT Version T1.0 on 20-MAR-1987 13:29:50.30
%The SDML doctype is: SOFTWARE
\gdef\figuretocentry{%
\contentsentry{\tocEXstream}{\the\TOCexample}
{1}{title}}
The primary access path for the realtion is on the field account.
\endfigure

-----------------

A .dvi_ln3 file is produced, but no .ln3 file.

    It's not explicitly stated in the <example> tag documentation, but
    it is suggested that the stuff between example and endexample must
    be of a type code_example or interactive. 
    
    For example, this file processes smoothly:
    
   <example>(title\acct_relation_ex)
-> <code_example>
   The primary access path for the realtion is on the field account.
-> <endcode_example>
   <endexample>
    
    The documentation apparently needs to make this more explicit.

    
    yes, it does. I have already made some comments for the documentation.
    the following are treated as 'figure elements' so are handled correctly
    in the context of a figure:
    
    1. <figure_space>
    2. <figure_file>
    3. <code_example>, <display>, <line_art>, <interactive>
    4. <sample_text> (which is probably what .0 wanted)
    
    ditto <example> with the correct substitutions in the list above.
    
    patti anklam
    

    
    re: .3
    
    See also Note #360. This is corrected for V1.0; a message is issued
    if there are not valid tags in an <example> or <figure> sequence,
    and reasonable things are passed to the text formatter so it doesn't
    end with errors.
    
    -pa