Bug#300884: fop: slightly ambiguous jimi instructions

Tue Mar 22 14:54:02 2005

[Cc th ebug report for the record]

Many thanks Gordon, I think I'll copy/paste your README.

Tue, 22 Mar 2005 10:15:55 -0700, 
Gordon Haverland <ghaverla@shaw.ca> wrote: 

> On Tuesday 22 March 2005 09:42, you wrote:
>> Tue, 22 Mar 2005 07:21:09 -0700,
>>
>> Gordon Haverland <ghaverla@materialisations.com> wrote:
>> > At the following URL
>> > http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsy
>> >stem/build/tutorials/docbooksys/docbooksys.html#DocBookSys-Cha
>> >pter3-XML-Install-Fop-Jimi I find the following paragraph
>> > which I think describes how to get Jimi support in a better
>> > way.
>> > 3.5.1. Install Jimi
>>
>> Excuse me but except the word PNG, I don't see where it's
>> better explain ;-)
>
> I hadn't even noticed the PNG business specifically.  I believe 
> you are assuming that whoever installs fop, already knows quite a 
> bit about java, jars, etc.
>
> : FOP is built with Jimi support
> : ------------------------------
>
> : As fop is in contrib, we can built it with libraries not in
> : Debian. That's what I did with fop and jimi. So you only have to
> : download jimi for the Sun web site:
>
> : http://java.sun.com/products/jimi/
>
> Okay, so feel I need to visit java.sun.com to view download 
> something.  If one knows that this is a licensing issue, then you 
> can probably figure out that you want to click the download link 
> on that page, and will probably be shown some kind of license 
> agreement.  Some people will not know this, and will be confused.
>
> Fine, we get past the license.  What do we download?  There is no 
> file listed that looks like jimi-1.0.jar.  We do have jimi1_0.zip 
> and jimi1_0.tar.Z.  People new to Linux are probably familiar 
> with Zip archives, and may not know that they are seldom used to 
> distribute things to UN*X machines.  There will be a number of 
> people confused by the ".Z" extension on the tarball.  Gzip and 
> bzip2 are relatively common, compress isn't that common any more.
>
> Telling them in the README.Debian that they should download one of 
> those 2 files (which one depending on whether they have unzip or 
> uncompress (or something else)) would help.  Also telling them 
> that they are actually just looking for one small file inside 
> that archive, the jar would help as well.
>
>
>> > Jimi is needed if you want to use PNG images with FOP,
>> > download it from http://java.sun.com/products/jimi/# and open
>> > the archive.
>> >
>> > On Windows, rename JimiProClasses.zip from the archive to
>> > jimi-1.0.jar and place it in the
>> > /directory/where/you/unzipped/fop/lib directory.
>>
>> I think we don't need this paragraph ;-)
>
> That's true.  I was doing cut and paste.
>
>> > On Unix, rename JimiProClasses.zip from the archive to
>> > JimiProClasses.jarand place it in the
>> > /directory/where/you/unzipped/fop/lib directory.
>>
>> /usr/share/java can do it. The thing is: it must be in your
>> classpath.
>
> Yes, but nowhere in the README, do you mention that the jar inside 
> the archive has a different name from the jar that you want to 
> reside in /usr/share/java.
>
> Is that a little clearer?  I wasn't submitting a patch so much as 
> trying to point out that your instructions were a little 
> ambiguous, and that someone else had worded things perhaps a bit 
> better.
>
> But, going back to the README.Debian file, you might want to 
> mention some example reasons as to why someone might want to 
> specify JAVA_OPTS.  As for the rest of the file, how about:
>
> ----------
> This version of FOP is built with Jimi support to allow fop to 
> work with images in your documents.
>
> As fop is part of the contrib stream of Debian, we can build it 
> for distribution with libraries that are not in the Debian 
> system.  In this particular case, that is what I did with fop by 
> compiling it with support for jimi.  You will however need to 
> download jimi from the Sub web site:
>
> http://java.sun.com/products/jimi/
>
> You will need to agree to Sun's licensing terms in order to be 
> shown a link to a file to download.  At the time this was 
> written, the jimi support was present as both a Zip archive and 
> as "compressed" tar archive.  You will either need Zip tools, or 
> uncompress and tar to work with this archive. 
>
> The name of the file to download is something like:
>
> jimi1_0.zip   (or jimi1_0.tar.Z)
>
> Inside that archive is a single jar (java archive, which is a 
> special kind of zip file) of the name JimiProClasses.zip that you 
> will need to extract.  Put a copy of that jar (zip file) 
> under /usr/share/java with the name jimi-1.0.jar if you want fop 
> to work normally with images on Debian.  
>
> If you don't want to put a copy of this jar file 
> under /usr/share/java/, you can either put a symlink to the real 
> location of the jar file under /usr/share/java (with the name 
> jimi-1.0.jar), or you can edit the /usr/bin/fop shell script for 
> how you would rather have things work.
> ----------------------
>
> It's quite a bit wordier than your README.Debian.  Hopefully it is 
> more understandable.  If nothing else, it might give you some 
> ideas on how to possibly change your existing README.Debian.
>
> Have a great day!
> Gord
>

-- 
  .''`. 
 : :' :rnaud
 `. `'  
   `-    
Java Trap: http://www.gnu.org/philosophy/java-trap.html