Mike Edwards Apache Tuscany - How To Build Site

The Tuscany website is built using the site plugin of Maven 2.0. A general guide to the Maven site plugin can be found here.

The website is held in the site subproject of Tuscany, with a set of source files in tuscany/src/site directory. The website project has its own POM file, held in the main site directory. The site is generated using the following command while in site directory. 

	mvn site
This will generate target/site directory. When you make changes to files intended for the website, please check out the results on your local machine by opening site/target/site/index.htm. You should be able to reach all the other pages from this location.

The actual live website for Tuscany is at the URL http://incubator.apache.org/tuscany/. The files for the live website are held on the machine people.apache.org in the directory /www/incubator.apache.org/tuscany. When you want to publish new or updated pages to the live website, use the command 

	mvn site-deploy
which transfers the site files from the site/target directory on your system to the people.apache.org system and the files go live within a few minutes of the transfer. For site-deploy to work, you must have a userid and password that are valid for the people.apache.org system and you must be a member of the apcvs group, since this is the group with write access to the /tuscany directory. To enable the mvn site-deploy command to work correctly, you need an entry like this in your maven settings.xml file: 
<servers>
<!-- server
| Specifies the authentication information to use when connecting to a particular server, identified by
| a unique name within the system referred to by the 'id' attribute below.
| 
| NOTE: You should either specify username/password OR privateKey/passphrase, since these pairings are 
|       used together.
|
-->
	
	<server>
		<id>website</id>
		<username>yourid</username>
		<password>yourpassword</password>
	</server>
	
</servers>
The settings.xml file can be found in your $MAVEN_HOME/conf directory.

The source files for the Tuscany site are held in the site/src/site directory. In that directory there is a special file called site.xml which holds the basic layout for all the pages in the site. In particular, site.xml contains the definitions for the left menu bar and for the overall title on each page. Only edit site.xml if you need to add a new top level page to the site.

Most of the pages for the site are held in the site/src/xdoc directory. The pages are generally in an XML format, although it is possible to define pages as HTML files. XML files are preferred, since Maven applies a standard layout and style sheet to these pages. If you provide a page as an HTML file, it will appear exactly as you create it - Maven does not modify HTML files as it creates the site.

The website landing page is defined by index.xml. The other pages are linked from this page, either via the left sidebar or via explicit links in the body of the page. The following section gives you some details on how to create your own page and link it into the site.

Other files are held in the resources directory. These files include things like images (eg. JPEG files) and documents (eg. PDF files). These files can be referenced from the pages in the xdocs directory, without the need for any path - Maven copies the files in the resources directory to the root directory of the website.

You can get a good feel for the format of the pages in the Tuscany website by looking at some of the existing files in the xdoc directory. bugs.xml is a good example of a simple page with a reference hyperlink. documentation.xml is an example of a more complex page which has a table. The format of the xml files uses a simple set of elements that approximate to the more common HTML tags. To get a feel for the XML elements, let's use an example of creating a new page called foo.xml.

First, create a file called foo.xml in the xdocs directory, similar to the following: 

<document url="foo.xml">
<properties>  
	<author email="your_id@blah.com">Your Name</author>
	<title>Apache Tuscany - Foo</title>
</properties>
<body>
	<section name="Tuscany Foo">	
	<p>
	Welcome to the foo section.  
	Please review the <a href="tuscany_foo.pdf">Tuscany FOO manual</a>.
	You can run foo by typing in the command:
	<pre>
		foo bar
	</pre>
	</p> 

</section>
</body>
</document>
Note the header information with a general title in the properties section - this gets applied to the title line of the browser when the page is displayed. There is a body section, which is the main content of the page. Within the body, each section tag places a heading into the page. Paragraphs are defined using the <p> tags. Hyperlink references can be created using the <a> element. For descriptions of commands and similar text elements, you can use the <pre> element.

References like "tuscany_foo.pdf" should be dropped into the site/resources directory. If you want to structure the information in the resources area, you can create subdirectories and then use relative references in the hyperlinks which reference them, such as href="subdirname/tuscany_foo.pdf".

If the foo page needs to be linked from the left bar, then a link to foo must be created in the site.xml file which is in the main src/site directory, with the following format: 

...
<menu name="Tuscany">
...
<item name="Foo"  href="foo.html" />
</menu>
...
Note that the link here is to foo.html, not to foo.xml - foo.html is the name of the page in the final website format.

When placing materials onto the web site, please use formats that are widely accepted and avoid proprietary formats. So, xdoc format is the preferred style for source web pages since they get the "house style" look and feel of the Tuscany site. HTML files are also acceptable, but they will lack the naviagation features of the xdoc pages (particularly the left bar). If you need to publish longer material, you can use HTML or PDF format. PDF is particularly good for material that users may need to download and keep locally for reference. PDF is also good if you anticipate that the users will need to print the material.

Please avoid the use of proprietary format such as Word documents. Not everyone has Microsoft office installed and may find such formats unreadable.