sorry about the length of this, but i have at least a little
honor left to defend ...
On Sun, 11 May 2003, Victor Mote wrote:
> Robert P. J. Day wrote:
>
> > oh, i'm *long* past the point of personal embarrassment here.
> > although i'm willing to admit that some of my difficulties were
> > my fault, i think i've also established that there are some definite
> > deficiencies in the docs for graphics support. where to start?
>
> Sorry Robert, Joerg is right. There may be some deficiencies in the doc, and
> I am considering what further changes we should make to clean it up, but the
> bottom line is that you are asking us to make it "stupid-proof", and I don't
> think we can do that.
i was not suggesting making it "stupid-proof", since such a thing is
clearly infeasible. what was becoming frustrating was asking a question
regarding why something didn't work, and told, "ah, you have to do X",
when X was not at all clearly spelled out in the docs.
and after i did "X", and it still didn't work, i was told, "ah, once
you do X, you have to do Y."
> > (first, since i made it clear that i was working with the CVS
> > tree, to clean that tree requires "build.sh clean", not
> > "build clean" as you wrote above. a picky detail, but the sort
> > of thing that has been costing me time and forced me to dig
> > around when i didn't have to.)
>
> Wrong. If you were running in a Windows environment, it would be
> "build.bat". Joerg's answer was the correct generic answer. The fact that
> you are digging around is your fault. The fact that you blame it on Joerg
> should be yet another cause for embarrassment.
note that i *did* admit right up front that it was a picky detail,
all i noted was that joerg told me to "build clean", so i had to
realize that what he really meant was "build.sh clean" for my
circumstances.
but i'm totally baffled by the accusation that it's my fault
that i'm "digging around." this so-called "digging around" is
nothing more than trying to figure out what it takes to build a
new fop.jar, which as we've established by now is something i
*have* to do.
how is it that you (and joerg) can, on the one hand, be adamant that
i have to build a new fop.jar, then chide me for "digging around"
when i try to do exactly that?
> > next, and as i've already mentioned, there is *nothing* i can see
> > in the docs that suggest that, if you build in JAI support, JIMI
> > support is simply dropped. *that* really deserves a prominent
> > place in the docs.
>
> Duly noted.
thank you. now we're making progress which, i should point out,
is a direct result of my "digging around."
> > next, regarding a build, there's *nothing* that suggests you need
> > to do a "build.sh clean" to actually get a new "fop.jar". early on,
> > as part of my tests, i explicitly deleted {fop}/build/fop.jar,
> > and watched the output from "build.sh" carefully to confirm that,
> > yes, the support i wanted was being built in. afterwards, i
> > verified that a new "fop.jar" had been created under {fop}/build.
> > was i really supposed to suspect that the messages being printed
> > by the build process didn't actually correspond to the new fop.jar
> > file? this is pretty thoroughly non-intuitive for anyone used to
> > the "make" system.
>
> First, please see:
> http://xml.apache.org/fop/compiling.html#Troubleshooting
> Second, you seem to think that we should know that you are familiar with
> "make". That would be a documentation failure on your part. Third, you want
> Ant to conform its behavior to make. That's not going to happen. You
> embarrass yourself to suggest that it should.
and i quote from http://xml.apache.org/fop/compiling.html:
The most useful targets are:
...
clean: Cleans the build directory. This is useful for making sure
that any build errors are cleaned up before starting a new
build. ***It should not ordinarily be needed***, but may be
helpful if you are having problems with the build process itself.
[emphasis mine]
now, this is a fascinating description of the "clean" operation. note
carefully how it first suggests that it is not ordinarily needed, unless
you are "having problems". but how does one realize that one is having
problems?
as i described in an earlier post, when i tried to change whether
JIMI or JAI support was built in, the "build" step ran without error,
the confirmation during that process did indeed confirm the support
i thought i was building in, and a new "fop.jar" appeared as i expected
in the "build" directory.
given that all of that happened smoothly and without incident, at what
point exactly was i supposed to suddenly realize that the build had
in fact failed? there was not a single notification, warning or error
that the new fop.jar was, in fact, not what i was expecting.
this has nothing to do with whether the Ant package should emulate
make. it has to do with, when a program runs, confirms everything you
selected and, in the end, produces an executable just as you expected
it would, it's reasonable to expect that that program is the one
you asked for.
so far, i'm still not feeling embarrassed. if Ant, or any other
software package, behaves in such a manner, it's my contention that
it's broken and has to be fixed. no program should tell you it
succeeded if it clearly didn't.
> > > > but again, according to the online docs, SVG support is handled by
> > > > batik, which i definitely have on my CLASSPATH.
> > >
> > > PCX files are not SVG, and can't be handled by Batik, therefore
> > > the errors.
> > > Take a closer look at the output.
> >
> > and once i did a clean, and built with only JIMI support, here's
> > the output (or at least an excerpt of it):
> >
> > [INFO] Failed to load JAI, using Jimi instead <-- looks good ...
> >
> > ....
> >
> > [ERROR] Could not load external SVG: Content is not allowed in prolog.
> > [ERROR] Error while creating area : No ImageReader for this type
> > of image (file:xclock.pcx)
> > [INFO] [30]
> > [ERROR] Could not load external SVG: Content is not allowed in prolog.
> > [ERROR] Error while creating area : No ImageReader for this type
> > of image (file:xclock.pict)
> > [INFO] [31]
> > [INFO] [32]
> > [ERROR] Could not load external SVG: Content is not allowed in prolog.
> > [ERROR] Error while creating area : No ImageReader for this type
> > of image (file:xclock.pnm)
> > [INFO] [33]
> > [ERROR] Could not load external SVG: Content is not allowed in prolog.
> > [ERROR] Error while creating area : No ImageReader for this type
> > of image (file:xclock.psd)
> > [INFO] [34]
> > [ERROR] Could not load external SVG: Content is not allowed in prolog.
> > [ERROR] Error while creating area : No ImageReader for this type
> > of image (file:xclock.ras)
> > [INFO] [35]
> > [ERROR] Could not load external SVG: Content is not allowed in prolog.
> > [ERROR] Error while creating area : No ImageReader for this type
> > of image (file:xclock.tga)
> > [INFO] [36]
> > [ERROR] Error while creating area : Error while loading image
> > file:xclock.tiff : class java.lang.Exception - Image error
> > [INFO] [37]
> > [ERROR] Could not load external SVG: Content is not allowed in prolog.
> > [ERROR] Error while creating area : No ImageReader for this type of image
> > (file:xclock.xbm)
> > [INFO] [38]
> > [ERROR] Could not load external SVG: Content is not allowed in prolog.
> > [ERROR] Error while creating area : No ImageReader for this type of image
> > (file:xclock.xpm)
> >
> >
> > and you can see that a number of formats that are documented as being
> > supported through JIMI failed to be rendered.
>
> The messages being generated here probably need some work. The normal
> approach with open source is to submit a patch.
that is most emphatically *not* the point. the point is that, as you can
see above, Jimi is being loaded, and yet a number of graphics formats that
are *clearly* listed online as being supported through Jimi are not being
rendered in the final PDF document. (see the list of allegedly supported
formats at http://xml.apache.org/fop/graphics.html to see what i mean.)
i have no idea what you mean by saying that the error messages "probably
need some work", since it's not clear why they're being generated in the
first place.
> > i'm using, as my guide, http://xml.apache.org/fop/graphics.html, so if
> > something in that table suggests it's supported by JIMI, i figure i have a
> > right to be confused if it doesn't work.
>
> Only if you follow the instructions everywhere else. You still have a
> problem either in your build or in your runtime environment. I frankly will
> not take the time to help you find it.
in the first place, the major problem here is that those instructions
are, in some critical cases, misleading or just plain missing.
more to the point, as you may recall, one of your earlier pieces of
advice was to not run FOP directly, but to invoke it through fop.sh,
which turned out to make no difference whatever and was a script you
turned out not to fully understand anyway.
i've never found it terribly useful when people try to give me advice
along the lines of "just do it this way, don't ask why, it's magic."
it doesn't enlighten anyone, and it still doesn't explain why a number
of Jimi-supported formats are still not being rendered.
if anyone else has had the patience to still be reading this, i'd like
to chat with anyone who has managed to render any of those formats
properly, so we can figure out what the trick is, so i can document it.
> > while i appreciate your assistance thus far, i could really do without
> >the smug, condescending tone about how i'm embarrassing myself.
> >
> > i'm trying *really* hard to point out deficiencies in the docs so that
> > others after me don't have to go throught what i went through. and your
> > attitude i can really live without.
>
> What you are asking us to do is to place a sign in the windshield of the car
> saying "do not drive this car off the cliff." That might be useful, but it
> would also obscure the vision of the driver which can cause a lot of other
> problems.
bad analogy. a better analogy would be promising that "this car will not
unexpectedly, and without warning, drive off a cliff." and then,
unexpectedly and without warning, it does just that.
any time you want some help improving the documentation, let me know.
i've written a *lot* of documentation and courseware in my time, and
i'm pretty good at it.
but i have no interest in writing anything along the lines of, "just
do it this way and don't ask questions."
rday
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
