[Mac OS X TeX] WARMreader and the Marked Objects Adobe Illustrator plug-in

[Ross Moore]

> Ross (or anybody that can help):
> 
> Before we even begin, we want to thank Ross and Wendy for taking the 
> time and effort to create WARMreader as a tool for including labels 
> in graphics. The comments and questions below are things that we hope 
> will help others in using WARMreader and provide feedback to the 
> authors so that WARMreader can be improved.

These are very good questions, most of which we have considered
already in developing the package and plug-in.
 
> After taking the time to learn about WARMreader, Gary Gray and I have 
> the following comments to report:
> 
> [1] The help available (paper: W. McKay and R. Moore, "Convenient 
> Labeling of Graphics, The WARMreader Way; and the examples available 
> on line) does not tell the whole story. For example, we had to look 
> in the file warmread.sty to understand that
> 
> - the default reference point for text labels is the lower left 
> corner of an enlarged text box, as opposed to the center of the box 
> (default for math labels).

Yes; but there are macros which determine this.
You can redefine them at will, as is done in some of the examples
on our web site.

> - there are a multitude of "formats" for .bb files which have to be 
> selected using commands of the type
>       \let\xyWARMprocess\xyWARMprocessMo
>       \let\WARMprocessEPS\WARMprocessMoEPS
> 
> - many of the commands that are placed in the preamble of the LaTeX 
> files provided as examples by Ross Moore at:
> 
> <http://www-texdev.mpce.mq.edu.au/WARM/WARMhome/ILLUS902/>
> 
> are not essential for using WARMreader. In this sense, said examples 
> are not good examples to get started. We would consider them advanced 
> examples provided that a few comments lines be added to explain the 
> effect of the WARMreader commands used.

Sure; these are advanced examples, primarily for use with pdfLaTeX.
In particular, they show how to get "Encapsulated PDF";
i.e. a PDF page with MediaBox adapted to the size of the graphic image.
They are from an actual text-book that is in the process of being revised
>from its previous (1988 ?) edition.


> It would be nice if there were some documentation that would get 
> people like us (people that have used TeX/LaTeX for years but are not 
> interested in deciphering style files) started (i.e., covering the 
> bare essentials) with the bare essentials (for example, describing 
> why $$ ... $$ (displaymath mode) are used to make sure that the 
> imported figure is centered) of the package and then point to 
> documentation for more advanced usage.

The $$...$$ is not essential.
As \begin{xy}...\end{xy} creates an \hbox then you ought to
be able to use \centerline or \begin{center}....\end{center} 
according to how much space you want above/below the images.
However, it may be necessary to use \null or \leavevmode to
ensure that you are in TeX's 'horizontal' mode.

Since these are math diagrams, using $$...$$ seemed quite natural.

 
> 
> [2] Why is the .bb file format generated by the Marked Objects 
> plug-in in Illustrator 9.0.2 different from the default format of .bb 
> files? Why have more than one format? With only one format the "\let" 
> commands shown above are not necessary.

In a word (or 2):  future expansion.
The new format has an extra field, which currently is   point(0,0) .
In future, we want to be able to have also  rect(<width>,<height>)
and  ellipse(<major>,<minor>)  etc.  so that arbitrary objects
may be "marked", with their sizes fully specified.


> [3] Instead of the commands
>      \let\xyWARMreader\xyWARMreaderMo
>      \let\WARMreaderEPS\WARMreaderMoEPS
> placed in the preamble of a LaTeX file to instruct WARDMreader to use 
> the Marked Object plug-in syntax in reading the .bb file, why not 
> define an option to the warmreader package? That is, something along 
> the lines of
>      \usepackage[AIMarkedObject]{warmreader}.

The warmread package is currently not dependent upon LaTeX at all, except
that the default macro for including an image is \includegraphics .
But this is easily changed to \epsbox or whatever.

We have chosen *not* to use options for package-loading, to preserve
this independence. However, it might be nice to have a separate file
that (a) reads and processes options
     (b) loads the current one,
     (c) customises for the input format, according to these options.
This would be for LaTeX only, of course.

> 
> [4] Depending on how the .bb files is created, the internal numbering 
> scheme used by WARMreader to identify the entries in the .bb file has 
> NOTHING to do with the "number" labels placed in the .bb file;

Yes; this is a known deficiency at present.
The numbering used by WaRMreader is the order of occurrence in the .bb
file. This can agree with the order of creation of the marked-points,
but that order is easily changed as you edit the information in
Illustrator.
We have asked Tom to provide alternatives for the sorting order.
 
> [5] Provided that we understand why, for example, !D moves the text 
> UP instead of DOWN, would it be difficult to change the internals of 
> WARMreader so that  the nudging commands become intuitive (e.g., U 
> mean UP and D means DOWN)?

Aaah; you haven't read the Xy-pic documentation, have you.  :-)
!D does not mean *move* Down. In fact the ! should not be thought
of as *moving* at all.

Think of your label (with its margins and any frames) as being
a rectangular (or elliptical) piece of paper, and the current
point in the diagram as being a pin-head or glob of glue.
You slide the paper around the picture until you've selected exactly
where you want it to be, then press hard to make it stick.

Now  !D means the Down edge (or bottom) of the rectangle is the place
of attachment (hence the text appears above the current-point).
Similarly !L means attach at the Left-hand edge, so the text appears
to the right of the current-point.
!R(.3) means attach at .3 of the distance to the Right-hand edge.
(Note that slidings can be combined, so that !L!R(.3)  and  !R(.3) 
 give different results.)

As a mathematician, you should see that this is a much better way
of determining how to position the <object>, since it is intrinsic
to the <object> itself and allows for an easy calculus of slidings. 


> COMMENTS on the Marked Objects plug-in for illustrator, which can be found at
> 
> <http://www.cds.caltech.edu/~wgm/WARM/reader2001.html>
> 
> [1] Would it be possible to contact Tom Ruark (the author of the plug 
> in) directly to give him our feedback?

Wendy will do this, if she hasn't done so already.

> [2] Will the Marked Objects plug-in for Adobe Illustrator 9.0.2 work 
> with the forthcoming release of Illustrator for MacOS X?

I would expect so.
This should be ensured by the modularity of the plug-in's construction.
As I understand it, there is no platform dependence in the internal coding
of the plug-in itself --- just in the format of the file for different
operating systems.

> [3] The way the plug-in renumbers objects is such that if you have 
> more than 9 objects, the objects will not appear in a sequential 
> order in the resulting .bb file. This is because of the fact that it 

Yep; that's why we've asked Tom to provide alternative sorting orders.

Personally, I prefer to not use numbers at all for the IDs.
You probably noticed that my examples all use names that relate to
the place being labelled. This makes it easier to construct the
Xy-pic code for the labels within you (La)TeX source.

> orders objects in the following manner:
> 1
> 10
> 11
> 12
> ...
> 100
> ...
> 2
> 20
> ...
> 200

> [4] In the Marked Objects plug-in dialog window there is a pop-up 
> menu with the following items:
> - point
> - rectangle
> - polygon
> - ellipse
> - oval
> 
> The selection of one of these items seems irrelevant from the 
> viewpoint of the .bb file creation. Is there an explanation as to why 
> said menu is available?

future expansion.
See the earlier comments on this.
 

> [5] Why are the "Character" and "Paragraph" pallets always attached 
> to the Marked Objects dialog window? We have to keep removing them 
> ... and it gets a little tedious after a while.

You can use these to adjust aspects of how the ID and text-string
appear in the marked-objects layer, when this is visible.
In particular, you can alter the font size and face used for these.

Yes, there are some interface problems with the current plug-in.
Hopefully they'll be fixed in the next version that Tom produces.


> [6] We have found that with certain files (it appears to only happen 
> when we begin with pre-Illustrator 9.x files, although we are not 
> 100% sure of this) the bounding box which is reported in the .bb file 
> does not have the format %%BoundingBox: 0 0 xxx yyy
> but it has the format
> %%BoundingBox: xx1 yy1 xx2 yy2
> (I hope this is not confusing)

This is a known bug.
It happens, as you say, with graphics constructed from earlier versions
of Illustrator.

> Is this a problem for WARMreader?

Yes; but the work-around is simple.
Just copy the %%BoundingBox from the .eps file itself,
and paste this into the .bb file using any text editor.

I've done this many times, with the  ILLUS902/ examples.

In fact there is another problem relating to the %%BoundingBox
that gets written into the .bb file, when there are objects
in invisible layers that fall outside the BB for the visible
parts of the artwork. (The Marked Objects layer itself does 
not cause this problem.) In this case, the .bb file gets
a %%BoundingBox which includes the invisible bits, whereas
the .eps file has a smaller BB. Provided the extra bits do
not fall below or to the left, then copying the BB from
the .eps file fixes this.


> [6] We have found that with certain files (it appears to only happen 
> when we begin with pre-Illustrator 9.x files, although we are not 
> 100% sure of this) the coordinates of some of the marked objects (but 
> not all), AT SOME POINT, start looking like (12200, -11971) (meaning 
> COMPLETELY OUT OF RANGE WITH RESPECT TO THE FIGURE), although 

Yep; that's a bug I've seen also.
No word back from Tom on the cause of this yet.
It happens when you drag the label position around in the artwork,
keeping the point itself fixed, I think.
Does this agree with your experiences?

> appearing in the right position in the Illustrator file. One can 
> re-enter the right coordinates of the and "update" the marked object 
> record (by using the "Transform" pallet for example). However, after 
> saving the file and re-opening it, the updated coordinates go back to 
> taking on the absolutely screwed-up values.

You should be able to type directly into the X and Y fields in the
Marked Objects window. However currently these do not take,
as you've probably observed. Again, we've reported this to Tom.

 
> We would be more than glad to work with Ross, Wendy, and/or Tom to 
> improve these tools and/or fix any of these problems.

It would be great if Adobe would release sufficient information about
the APIs in Illustrator to allow for easier development of plug-ins.
This would greatly speed-up further development.
Besides, Adobe's image is not good in the free/open software communities
at present. This might help a bit.


> -- 
> Best Regards,
> Francesco Costanzo
> Associate Professor

Thanks very much for the feedback.
I hope my answers help you to work better with the Marked Objects tool,
which is still really in the alpha stage of development, due to
interface bugs. Yet much productive work can be done with it.


All the best,

	Ross Moore


> %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
> Address: Engineering  Science and  Mechanics  Department
>           The Pennsylvania State University
>           212 Earth and Engineering Sciences Bldg.
>           University Park, PA 16802-1401
>           USA
> Phone:   (814)863-2030
> Fax:     (814)863-7967
> mailto:costanzo at engr.psu.edu
> http://www.esm.psu.edu/HTMLs/Faculty/FCostanzo.html
> %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
> 
> -----------------------------------------------------------------
> To UNSUBSCRIBE, send email to <info at email.esm.psu.edu> with
> "unsubscribe macosx-tex" (no quotes) in the body.
> For additional HELP, send email to <info at email.esm.psu.edu> with
> "help" (no quotes) in the body.
> This list is not moderated, and I am not responsible for
> messages posted by third parties.
> -----------------------------------------------------------------


-----------------------------------------------------------------
To UNSUBSCRIBE, send email to <info at email.esm.psu.edu> with
"unsubscribe macosx-tex" (no quotes) in the body.
For additional HELP, send email to <info at email.esm.psu.edu> with
"help" (no quotes) in the body.
This list is not moderated, and I am not responsible for
messages posted by third parties.
-----------------------------------------------------------------