docs/org.eclipse.wst.doc.isv/README_HOWTO_pacakge_overview.txt

Each API package is required to have a package overview document describing
at a high level the problem solved by the API, how the API is meant to be used, 
and where applicable diagrams and images explaining the expected and correct 
usage. 

Like the design of the WTP website, the package overviews are stored as 
XML files within the root of the package that they describe. The file
name must always be "package.xml". The XSLT stylesheet that runs as part 
of the Javadoc process will transform this file into a "package.html" file,
which is expected by the javadoc tool. 

Developers have four tags to be aware of, in addition to the normal
tag redefinitions that occur for the website (e.g. some header tags 
are redefined as white text with light blue backgrounds that span 
the page, like the Eclipse style). These four tags are:

<p> tag: Each paragraph tag will be wrapped in a table that forces 
a fixed width for the text lines. Overviews that choose to add images 
can often stretch the text out into a width that is difficult or at a 
minimum inconvenient to read. Each <p> tag will be formatted consistently
across all overview documents. Please refrain from adding extra formatting
around paragraph tags.

<img src="" caption=""> tag: Each image will be displayed in a specialized table format, with
a caption. The <img> tag has an attribute "caption" that will be displayed
just under the image explaining in text what the picture intends to
convey graphically. For example:

<img src=".." caption="This sample text" />

__________
|         |
|  img    |
|_________|
|__text___|

*Also note that all images used in a package overview must be placed in the 
root of the project under a directory named "javadoc-images". Whenever an
image is linked to, the link must escape to the root package level
to reference the image, and include "overview" in the path. So if you want to 
link "model_overview.jpg" into package overview for "com.acme.model":

(1) Place "model_overview.jpg" in <project>\javadoc-images
(2) Add the following element to your document: 
	<img src="../../../overview/model_overview.jpg" caption="An overview of the Acme Model API" />  
	--> Note that the three "../" escapes is the same number of elements in the 
		package path: com/acme/model/. 
	--> "overview/" is required as all images will be pushed into the "overview" 
		directory in the final javadoc layout. 

		
<codesnippet caption=""> tag: The codesnippet is provided to allow quick addition of code 
snippet examples or usage patterns for API. The content of the <codesnippet />
tag should be the actual source code. The tag will use the text exactly as it 
appears in an HTML <pre> tag, and will wrap the snippet in a table for formatting.
The codesnippet tag allows for a caption just as the img tag does. 

<abstract> tag: The abstract tag should always occur first in your content, and should 
contain a brief synopsis of your package overview ("package overview overview"). The 
contents of this tag will be displayed in the full API overview page beside the linked
package name. The tag should contain no extra HTML formatting.