Conference vaxuum::document_ft

769.0. "<FIGURE_FILE> and LINE; TEX-W-INSERTED msg" by DSSDEV::EPPES (I&#039;m not making this up, you know) Thu Aug 06 1987 14:01

    I just ran into a problem with <FIGURE_FILE> that seems to be due to
    faulty documentation.  Also, it generated a "submit an SPR" error.

    This is what was in my SDML file:

	<figure>(Run-Time Structure of the FIMS\run_time_fig)
	<figure_file>(ln03\fims_handout_fig.six\6)
	<figure_file>(postscript\fims_handout_fig.ps\8)
	<figure_file>(line_printer\run_time_fig\8)
	<endfigure>

    Note that the 2nd argument with the line_printer tag is the symbolic
    name (as is the case in one of the examples for the <figure_file> tag
    in the DOCUMENT User Manual, Part 1, Field Test Update Draft, p. 10-95).
    The file processed for LN03 and POSTSCRIPT destinations with no problem.
    But when I processed it for the LINE destination, this is what happened:
    (doctype is REPORT)

$ if F$MODE() .eqs. "NETWORK" then exit
$ if F$MODE() .eqs. "BATCH" then set noverify
Welcome to the multi-baselevel world of VAX DOCUMENT on DSSDEV
 Defining logicals and symbols for VAX DOCUMENT Base Level 06... 

====> DOCUMENT, Version 0.9 -- Base Level 6
====> SDMLINFO describes procedures for using VAX DOCUMENT, Version T1.0

...Logical names and symbols for VAX DOCUMENT BL06 defined
Switching from BL06 to BL08
 Deassigning logicals and symbols for VAX DOCUMENT Base Level 06... 
...Logical names and symbols for VAX DOCUMENT BL06 deassigned
Defining logicals for VAX DOCUMENT BL08 tree...
...Logicals for VAX DOCUMENT BL08 tree defined
$ verify_context = 0 ! SYS$SCRATCH:DOC$FIMS_HANDOUT.TMP - Start
$ d = "document"
$ set = "set"
$ set noon
$ set default sys$login_device:[eppes.forms]
$ D /BATCH=(NOTIFY,NOPRINT,LOG=SYS$DISK:[],NAME=FIMS_HANDOUT,KEEP)/TAG/TEXT
/DEVICE/NOPRINT/LOG/MAP USERF$:[EPPES.FORMS]FIMS_HANDOUT.SDML; REPORT LINE
%DOC-I-IDENT, VAX DOCUMENT T1.0-008
[ T a g   T r a n s l a t i o n ]...
%TAG-I-TAG_IDENT, T1.0-002
%TAG-I-DEFSLOADD, End of Loading of Tag Definitions
%TAG-W-NONEWFILE, at tag <CONTENTS_FILE> on line 20 in file
USERF$:[EPPES.FORMS]FIMS_HANDOUT.SDML;
<CONTENTS_FILE> specified without /CONTENTS. No new file will be generated.
%TAG-I-ENDPASS_1, End of first pass over the input
%TAG-I-CPU_USAGE, Pass 1: 9.9  Pass 2: 4.2  Total: 14.0 seconds
[ T e x t   F o r m a t t i n g ]...
%TEX-I-IDENT, T1.0-005

%TEX-I-INFO, Line printer does not support graphics output. Leaving space. -on
page [PART1-7]
%TEX-W-INSERTED, Missing '$' inserted
%TEX-I-SHOWCONTEXT, '                $'
%TEX-I-SHOWCONTEXT, '                   _'
%TEX-I-SHOWCONTEXT, '-> run_'
%TEX-I-SHOWCONTEXT, '                   time_fig '
%TEX-I-SHOWCONTEXT, '...pace.} \vbox to #3{\vss #2'
%TEX-I-SHOWCONTEXT, '                                          \vss }\or\special {lpr:dv...'
%TEX-I-SHOWCONTEXT, '...2}{0}{0}{0}{0}{0}{0}'
%TEX-I-SHOWCONTEXT, '                                          \vss } \or \vbox to #2{\cen...'
%TEX-I-SHOWCONTEXT, '...{#3}{\graphicsposition }'
%TEX-I-SHOWCONTEXT, '                                           } \or \def \tempcsA {0}\de...'
%TEX-I-LINE, Error occurred on or around line number: 327
%TEX-I-SHOWCONTEXT, '{10.0pc}'
%TEX-I-SHOWCONTEXT, '        \fi'
%TEX-I-FILENAME, 'fims_handout'
-TEX-I-ONPAGE, on page [PART1-7]
%TEX-W-INSERTED, Missing '$' inserted
%TEX-I-SHOWCONTEXT, '                $'
%TEX-I-SHOWCONTEXT, '                   \vss '
%TEX-I-SHOWCONTEXT, '...} \vbox to #3{\vss #2\vss '
%TEX-I-SHOWCONTEXT, '                                          } \or \special {lpr:dvifile...'
%TEX-I-SHOWCONTEXT, '...2}{0}{0}{0}{0}{0}{0}'
%TEX-I-SHOWCONTEXT, '                                          \vss } \or \vbox to #2{\cen...'
%TEX-I-SHOWCONTEXT, '...{#3}{\graphicsposition }'
%TEX-I-SHOWCONTEXT, '                                           } \or \def \tempcsA {0}\de...'
%TEX-I-LINE, Error occurred on or around line number: 327
%TEX-I-SHOWCONTEXT, '{10.0pc}'
%TEX-I-SHOWCONTEXT, '        \fi'
%TEX-I-FILENAME, 'fims_handout'
-TEX-I-ONPAGE, on page [PART1-7]
%TEX-W-LINETOOSHORT, Line too short - on page [PART1-7]

%TEX-I-INFO, Possible table paging problem. - on page [PART1-15]

%TEX-I-PAGESOUT, 21 pages written.
-TEX-I-OUTFILENAME, 'sys$login_device:[eppes.forms]FIMS_HANDOUT.DVI_LINE'
%DOC-E-ERROR_FORMATTER, Errors found by the Text Formatter.
$ exit ($status + (0 * f$verify(verify_context))) ! SYS$SCRATCH:DOC$FIMS_HANDOUT.TMP - End
  EPPES        job terminated at  6-AUG-1987 12:40:40.56
Accounting information:
  Buffered I/O count:          169      Peak working set size:  3858
  Direct I/O count:            424      Peak page file size:    8562
  Page faults:                3689      Mounted volumes:           0
  Charged CPU time:     0 00:00:38.16   Elapsed time:     0 00:01:06.32


    Well, I was perplexed.  So I reread the description of the <FIGURE_FILE>
    tag.  Lo and behold, under "Restrictions" it says:

	If you use the <FIGURE_FILE> tag in a file that you process for
	multiple output devices, you must supply a tag for each device,
	using the SPACE keyword for devices for which you do not have graphics.

    So I changed the 2nd keyword to my line-printer <figure_file> as follows:

	<figure>(Run-Time Structure of the FIMS\run_time_fig)
	<figure_file>(ln03\fims_handout_fig.six\6)
	<figure_file>(postscript\fims_handout_fig.ps\8)
	<figure_file>(line_printer\SPACE\8)
	<endfigure>

    The file processed with no errors for the LINE destination.  It appears,
    therefore, that supplying the symbolic name as the 2nd argument to
    <figure_file> for line-printer output is a no-no, even though one of the
    examples shows exactly that.  Also confusing is the fact that the
    documentation says, for the LINE_PRINTER keyword, "If specified, the
    file-spec argument is ignored, and blank space is output."  But, if you
    specify text as that argument (for example, "Illus. of Santa Claus" as
    is shown in Example 3 under the <FIGURE_FILE> description), that text
    is output, centered in the figure space.  The documentation doesn't say
    anything about that.  In short, the documentation is not complete, and
    the examples are misleading.

    The error for which the user action is "submit an SPR" is this one, taken
    from the log file above:

		%TEX-W-INSERTED, Missing '$' inserted

    As the documentation says, "this should not happen."  It also says
    (in addition to "submit an SPR") to examine the context and attempt
    to determine why text formatter expected to see that command (in this
    case, a dollar sign).  Since TeX is largely a mystery to me, I'm making no
    such attempt.  I'll leave that to braver and more knowledgeable souls...!

							-- Nina

    
    The bug is related to the translation of special characters; it
    will be a bit tricky to fix. Here is what is happening:
    
    1. Normally, all  _ characters are transformed during tag translation
       to \_ so that TeX will accept them (_ all by itself means something
       special to TeX in math mode).
    
    2. When an argument to a tag that is passed to TeX or a device driver,
       the underscores are left alone, because in the context of opening
       a file, the characters are not processed by TeX. So, the file-spec
       argument RUN_TIME_FIG is left alone.
    
    3. The documentation is correct that if a file-spec is specified
       for a line printer device, you get a message saying that the
       file won't be included. Then TeX writes the file-spec string
       in the space left for the figure. But OUCH! it wasn't translated
       to RUN\_TIME\_FIG, which is needed for TeX to print the characters
       correctly. The 'missing $' error means that TeX expects to be
       in math mode when it sees a naked underscore...
    
    You are correct that the documentation in the parameter description
    of file-spec should be corrected to indicate that the file-spec
    argument is printed in the blank space if LINE_PRINTER is specified.
    
    In other words, until the bug is fixed: don't use any characters
    other than alphanumeric and periods in the second argument to
    <FIGURE_FILE> when the destination is LINE_PRINTER.
    
    -patti
    

    Thanks, Patti.

    Another question about <FIGURE_FILE>:  why can't you use it to
    include a line-art drawing for line printer output?  Many figures
    can be drawn crudely on the terminal.  It would be nice if you could
    use <FIGURE_FILE> to include a file that contains <LINE_ART>
    and <ENDLINE_ART> tags around a drawing.

						-- Nina

    <FIGURE_FILE> is a pass-thru command.  That is, the file name is
    passed through to the device converter, and it passes through the
    contents of the file with little or no interpretation.  So the figure
    file contents cannot be processed as SDML tags, because tag translation
    and text formatting have long ago occurred by the time you get to
    the device converter.
    
    Precisely what we *could* support as figures for a monospaced device
    depends on the type of device (line printer, dot matrix printer,
    VT100, VT220, VT241, etc.).  There is another note "back there
    somewhere" that discusses such possibilities at length, and concludes
    that this is definitely wishlist stuff for consideration in future
    versions.
    
    (Separate from the specific implementation via <FIGURE_FILE> is
    the matter of providing for other kinds of line graphics, such as
    VT100 line drawing.  This, too, is something for the wishlist.)
    
    --Mark

    Ah, so.  Thanks.
					-- Nina

RE: .3

Good example of probable confusion when customers read about <table_file>, 
then expect (and I think rightfully so) that <figure_file> should work the
same for all output devices.


Rose