Re: Where to put images for JavaDoc?

[Arnaud Vandyck]

Brian Jones <address@hidden> wrote:
> Sascha Brawer <address@hidden> writes:
> 
> > Hi,
> > 
> > I would like to illustrate the JavaDoc for some classes with images.
> > Where can I put the image files?
> > 
> > For example,  I think it  is much easier  to explain the  purpose of
> > javax.swing.border.BevelBorder with  the attached image  -- in text,
> > it would be pretty hard to describe in text which pixels get painted
> > in what color. ASCII art would not work in all cases.
> 
> Hmm... how could  we handle this?  I think  make an 'images' directory
> in doc/api/ and we'll eventually fix it up to copy that directory into
> the generated documentation directory.   Your links would then need to
> be relative to  the root of the  docs... which I think are  all in one
> directory anyway so like img src="images/swing1.png" alt="[blah]".

First, Sascha, the image is very nice ;-)

Maybe  classpath can follow  the Sun's  recommendations for  the javadoc
from here:

http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#images

The  following  are the  Java  Software  proposals  for conventions  for
including images in doc comments.  The master images would be located in
the source tree; when the Javadoc  tool is run with the standard doclet,
it would copy those files to the destination HTML directory. 

Images in Source Tree

    * Naming  of   doc  images  in   source  tree  -  Name   GIF  images
      <class>-1.gif, incrementing  the integer for  subsequent images in
      the same class. Example: Button-1.gif

    * Location  of doc  images in  source  tree -  Put doc  images in  a
      directory called "doc-files". This  directory should reside in the
      same package  directory where the  source files reside.  (The name
      "doc-files" distinguishes it as documentation separate from images
      used by the  source code itself, such as  bitmaps displayed in the
      GUI.) Example: A  screen shot of a button,  Button-1.gif, might be
      included in  the class  comment for the  Button class.  The Button
      source file and the image would be located at:
      java/awt/Button.java (source file)
      java/awt/doc-files/Button-1.gif (image file)

    Images in HTML Destination

        * Naming of doc  images in HTML destination -  Images would have
          the  same name  as  they  have in  the  source tree.  Example:
          Button-1.gif

        * Location of doc images in HTML destination -
              o  With hierarchical  file  output, such  as Javadoc  1.2,
              directories  would  be located  in  the package  directory
              named "doc-files". For example:

  api/java/awt/doc-files/Button-1.gif

              o With flat file  output, such as Javadoc 1.1, directories
              would  be  located  in  the package  directory  and  named
              "images-<package>". For example:

  api/images-java.awt/
  api/images-java.awt.swing/

...

-- Arnaud Vandyck, STE fi, ULg
   Formateur Cellule Programmation.