images, images and more images

["Robert P. J. Day" <rp...@mindspring.com>]

  ok, i've made some progress so i'm just going to write out
everything i've gone through, and i'd appreciate any clarification
for questions i have.

  scenario:  a simple website (variation of avalon-tigris skin),
with exactly three images, all listed in skinconf.xml:

  1)  <project-logo>images/tinytux.png</project-logo>
      <credits>...
  2)     images/built-with-forrest-button.png
  3)     images/linuxpower.jpeg

note that i have to supply 1) and 3), while i've deduced that 2)
is pulled by forrest out of the forresthome directory so i don't have
to worry about it.  so far, so good.

  ok, first point.  i found it initially confusing that the file
"forrest.properties" defines an explicit project.images-dir directory,
whose name is conveniently "images/", yet the references to images
in skinconf.xml must (apparently) be listed relative to the parent
"resources" directory.  this is not at all intuitive.

  second point.  although i mentioned this before, forrest does bad
things with files that end with ".jpg", but not ".jpeg".  definitely
non-intuitive.

  next major point.  i'm assuming that, except for images that i can
drag out of the forresthome directory (like "Built with Apache Forrest"), 
i have to supply all images i use, and as i read it, it's sufficient to 
place those images in src/.../resources/images, right?

  (digression:  what is the rationale for the "images/" directory
under the specific skins/ directory?  so far, i'm ignoring it.  should
i be doing something with it if i create a custom skin?)

  ok, so i've copied *my* two images into .../resources/images, and
i figure i should be good to go.  i run "forrest", it runs to completion,
i load the index.html file into mozilla and ... while the tinytux.png
file is rendered nicely up top, and the apache forrest logo looks good,
the linuxpower.jpeg file is not displayed, only the alt "Powered by 
Linux".  so why is that graphics file not being rendered?

  check the page source for index.html, the src= value for that
image looks good: "src=images/linuxpower.jpeg".  so what's the
problem?

  here, i need a clarification.  if i go under the new build/
directory, is my *entire* site upload found under build/site?
that is, is that directory and all of its subdirectories entirely
self-contained?  because if i look in the images/ directory in that
directory, i find exactly:

  built-with-forrest-button.png
  tinytux.png

and *no* linuxpower.jpeg file.  why not?

  if i look further up, under build/tmp, i find what i assume
are all sorts of intermediate results, including the directory
build/tmp/context/resources/images, which contains a pile of
image files, including my linuxpower.jpeg.  so why is that file
sitting here but not in my build/site/images directory where it
would do some good?  if i copy it down manually, then suddenly,
i have my graphic.  why isn't it being copied there already?

  and in conclusion, things i'm curious about:

1) what does forrest have against files that end with ".jpg"?
2) what is the purpose of the images/ directory in the skins/ directories,
   and when should they be used (if ever)?
3) is the build/site directory a wholly self-contained web site?
4) why is my linuxpower.jpeg file not being copied into build/site/images,
   where it can be displayed?

rday

Re: images, images and more images

[Jeff Turner <je...@apache.org>]

On Thu, Jul 10, 2003 at 08:34:51AM -0400, Robert P. J. Day wrote:
> On Thu, 10 Jul 2003, Jeff Turner wrote:
> 
> > On Wed, Jul 09, 2003 at 09:40:40PM -0400, Robert P. J. Day wrote:
> 
> > >   ok, first point.  i found it initially confusing that the file
> > > "forrest.properties" defines an explicit project.images-dir directory,
> > > whose name is conveniently "images/", yet the references to images
> > > in skinconf.xml must (apparently) be listed relative to the parent
> > > "resources" directory.  this is not at all intuitive.
> > 
> > What should it be relative to?  If it helps, in 0.6 we're planning to
> > make it relative to content/.
> 
> one would think that, if the "forrest.properties" file defines an
> explicit directory called the images directory, why wouldn't it
> be relative to that?  what is the function of that option in the
> forrest.properties file, if not to identify where images are to be
> found?
...
> > Currently, project.images-dir locates the images directory in the
> > _source_.  Forrest then builds a webapp in the standardized format the
> > the sitemap expects.  In this standardized format, the directory is
> > always called 'images'.
> > 
> > The easiest way to see how things work is to build a webapp ('forrest
> > webapp'), and then look at the sitemaps. 
> 
> sorry, i'm not sure what you're saying here.  i'll go back and read
> the docs more carefully, but from my perspective as a newbie, i look
> at it as that my images *are* in the "source".  i just think this 
> distinction needs to be explained more carefully somehow.  as a newbie,
> if i see something identifying an images directory, i naturally assume
> that's where i should put my images and that's where the app will look
> for them.

And you'd be right.  The only thing is, within your XML, the
${project.images-dir} files are accessed with an 'images/' prefix.  Why?
Because in XML, you refer to other files by their _URL_, not their
filesystem location.  The Forrest sitemap maps from filesystem
(${project.images-dir}) to URL ('images/').  Thus, no matter where your
images appear on the filesystem, they will always be accessible with
'images/*' URLs.

Another example may help.  You mentioned the skin images/ directory.
Which skin is currently in use is determined by the ${project.skins-dir}
and ${project.skin} variables.  However, within the sitemap, skin images
are always available through the URL 'skin/images/...'.

Graphically:

    [ FILESYSTEM ]                                         [ URI SPACE ]

${project.images-dir}/...                -->  Forrest  --> 'images/...'
${project.skins-dir}/${project.skin}...  -->  Forrest  --> 'skins/images/...'

So in effect, Forrest sites are built on a virtual filesystem (the URL
space), not the _actual_ filesystem.  Every link (image or href) must be
to a URL, not a filesystem file.

...
> believe me, i flogged this for most of yesterday evening.

Ah, fun..

> if i replaced the reference to linuxpower.jpeg with a PNG file, it
> rendered nicely.  when i switched it back, the generated HTML *did*
> refer to the linuxpower file, but that file was never copied into the
> build/site hierarchy, thus no image.  so the generated HTML was, in
> fact, correct.  it was just the file that was never copied over.

As I'm sure you've noticed by now, Forrest's command-line rendering
sucks.  It is painfully slow business making a change, rerendering, then
checking the output.  For any sort of debugging work, I find its best to
launch a webapp ('forrest run'), then check the output on
http://localhost:8888/.  A temporary copy of the files can then be edited
in realtime in $PROJECT/build/webapp/

In your case, I think you would have found that the image was broken on
localhost:8888.  Cocoon never saw the image, so never spidered it, so
never copied it to build/site/.

> is there any possible way that this spidering fails to copy the .jpeg
> file, while successfully copying, say, a .png file?  i'll test it some
> more later today.

Btw, in the webapp, you can see exactly what links a page has by
requesting (say):

http://localhost:8888/index.html?cocoon-view=links

That should include all the images in the page.


--Jeff

> rday
> 
> --
> 
> Robert P. J. Day
> Eno River Technologies
> Unix, Linux and Open Source training
> Waterloo, Ontario
> 
> www.enoriver.com
> 

Re: images, images and more images

["Robert P. J. Day" <rp...@mindspring.com>]

On Thu, 10 Jul 2003, Jeff Turner wrote:

> On Wed, Jul 09, 2003 at 09:40:40PM -0400, Robert P. J. Day wrote:

> >   ok, first point.  i found it initially confusing that the file
> > "forrest.properties" defines an explicit project.images-dir directory,
> > whose name is conveniently "images/", yet the references to images
> > in skinconf.xml must (apparently) be listed relative to the parent
> > "resources" directory.  this is not at all intuitive.
> 
> What should it be relative to?  If it helps, in 0.6 we're planning to
> make it relative to content/.

one would think that, if the "forrest.properties" file defines an
explicit directory called the images directory, why wouldn't it
be relative to that?  what is the function of that option in the
forrest.properties file, if not to identify where images are to be
found?
 
> Currently, project.images-dir locates the images directory in the
> _source_.  Forrest then builds a webapp in the standardized format the
> the sitemap expects.  In this standardized format, the directory is
> always called 'images'.
> 
> The easiest way to see how things work is to build a webapp ('forrest
> webapp'), and then look at the sitemaps. 

sorry, i'm not sure what you're saying here.  i'll go back and read
the docs more carefully, but from my perspective as a newbie, i look
at it as that my images *are* in the "source".  i just think this 
distinction needs to be explained more carefully somehow.  as a newbie,
if i see something identifying an images directory, i naturally assume
that's where i should put my images and that's where the app will look
for them.
 
> >   second point.  although i mentioned this before, forrest does bad
> > things with files that end with ".jpg", but not ".jpeg".  definitely
> > non-intuitive.
> 
> If you update to CVS Forrest, this should now be fixed.  Forrest will no
> longer rewrite extensions.

excellent.
 
> > that is, is that directory and all of its subdirectories entirely
> > self-contained?  because if i look in the images/ directory in that
> > directory, i find exactly:
> > 
> >   built-with-forrest-button.png
> >   tinytux.png
> > 
> > and *no* linuxpower.jpeg file.  why not?
> 
> Is that file ever referred to in the XML?  Forrest spiders the site, so
> if it never encountered a reference to 'images/linuxpower.jpeg' it
> wouldn't appear in build/site/images/.  Perhaps you are referring to it
> as 'images/linuxpower.jpg'?

believe me, i flogged this for most of yesterday evening.  if i replaced
the reference to linuxpower.jpeg with a PNG file, it rendered nicely.
when i switched it back, the generated HTML *did* refer to the linuxpower
file, but that file was never copied into the build/site hierarchy,
thus no image.  so the generated HTML was, in fact, correct.  it was
just the file that was never copied over.

is there any possible way that this spidering fails to copy the .jpeg
file, while successfully copying, say, a .png file?  i'll test it some
more later today.


rday

--

Robert P. J. Day
Eno River Technologies
Unix, Linux and Open Source training
Waterloo, Ontario

www.enoriver.com

Re: images, images and more images

[Jeff Turner <je...@apache.org>]

On Wed, Jul 09, 2003 at 09:40:40PM -0400, Robert P. J. Day wrote:
> 
>   ok, i've made some progress so i'm just going to write out
> everything i've gone through, and i'd appreciate any clarification
> for questions i have.
> 
>   scenario:  a simple website (variation of avalon-tigris skin),
> with exactly three images, all listed in skinconf.xml:
> 
>   1)  <project-logo>images/tinytux.png</project-logo>
>       <credits>...
>   2)     images/built-with-forrest-button.png
>   3)     images/linuxpower.jpeg
> 
> note that i have to supply 1) and 3), while i've deduced that 2)
> is pulled by forrest out of the forresthome directory so i don't have
> to worry about it.  so far, so good.
> 
>   ok, first point.  i found it initially confusing that the file
> "forrest.properties" defines an explicit project.images-dir directory,
> whose name is conveniently "images/", yet the references to images
> in skinconf.xml must (apparently) be listed relative to the parent
> "resources" directory.  this is not at all intuitive.

What should it be relative to?  If it helps, in 0.6 we're planning to
make it relative to content/.

Currently, project.images-dir locates the images directory in the
_source_.  Forrest then builds a webapp in the standardized format the
the sitemap expects.  In this standardized format, the directory is
always called 'images'.

The easiest way to see how things work is to build a webapp ('forrest
webapp'), and then look at the sitemaps. 

>   second point.  although i mentioned this before, forrest does bad
> things with files that end with ".jpg", but not ".jpeg".  definitely
> non-intuitive.

If you update to CVS Forrest, this should now be fixed.  Forrest will no
longer rewrite extensions.

>   next major point.  i'm assuming that, except for images that i can
> drag out of the forresthome directory (like "Built with Apache Forrest"), 
> i have to supply all images i use, and as i read it, it's sufficient to 
> place those images in src/.../resources/images, right?

Yes, that's where all images should live.

>   (digression:  what is the rationale for the "images/" directory
> under the specific skins/ directory?  so far, i'm ignoring it.  should
> i be doing something with it if i create a custom skin?)

Skin images are for images referenced only by the skin *.xsl files.  It's
for images classed as "presentation", rather than "content".

<snip things-I-hope-are-fixed>

>   here, i need a clarification.  if i go under the new build/
> directory, is my *entire* site upload found under build/site?

Yes.

> that is, is that directory and all of its subdirectories entirely
> self-contained?  because if i look in the images/ directory in that
> directory, i find exactly:
> 
>   built-with-forrest-button.png
>   tinytux.png
> 
> and *no* linuxpower.jpeg file.  why not?

Is that file ever referred to in the XML?  Forrest spiders the site, so
if it never encountered a reference to 'images/linuxpower.jpeg' it
wouldn't appear in build/site/images/.  Perhaps you are referring to it
as 'images/linuxpower.jpg'?

>   if i look further up, under build/tmp, i find what i assume
> are all sorts of intermediate results, including the directory
> build/tmp/context/resources/images, which contains a pile of
> image files, including my linuxpower.jpeg.  so why is that file
> sitting here but not in my build/site/images directory where it
> would do some good?  if i copy it down manually, then suddenly,
> i have my graphic.  why isn't it being copied there already?
> 
>   and in conclusion, things i'm curious about:
> 
> 1) what does forrest have against files that end with ".jpg"?

.jpg is not the 'canonical' extension for the image/jpeg MIME type.
Cocoon takes responsibility for assigning serialized URLs an appropriate
extension.  In some cases, this is a Good Thing:

 - if you're following best practices [1], image URLs won't have
   extensions at all, but you wouldn't want _serialized_ URLs to have no
   extension.  So here it's good that Cocoon adds an extension.
 - it allows extensions to be centrally managed.  Say I'm writing an
   article about JSP, and serve a sample 'foo.jsp' file as MIME type
   text/plain.  Cocoon will render this as foo.jsp.txt.  Your Tomcat
   instance will then take the hint, and serve it as text, rather than
   interpret it as a JSP (with perhaps disastrous effect).

What I don't understand is why, in your case, Cocoon wasn't writing out a
linuxpowered.jpg.jpeg file, and linking to that.  It would have been
non-optimal, but not a _major_ problem.

Anyway, I've cleared the recognized-MIME-type list now, so this is all
academic :)

--Jeff


[1] http://www.w3.org/Provider/Style/URI.html

> 
> rday
>