diff options
Diffstat (limited to 'site/branches/site-20060730-mvnbased/src/site/xdoc/howtobuildsite.xml')
| -rw-r--r-- | site/branches/site-20060730-mvnbased/src/site/xdoc/howtobuildsite.xml | 178 |
1 files changed, 178 insertions, 0 deletions
diff --git a/site/branches/site-20060730-mvnbased/src/site/xdoc/howtobuildsite.xml b/site/branches/site-20060730-mvnbased/src/site/xdoc/howtobuildsite.xml new file mode 100644 index 0000000000..43e9874815 --- /dev/null +++ b/site/branches/site-20060730-mvnbased/src/site/xdoc/howtobuildsite.xml @@ -0,0 +1,178 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (c) 2005 The Apache Software Foundation or its licensors, as applicable. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + --> +<document url="howtobuildsite.xml"><properties> + <author email="mike_edwards@uk.ibm.com">Mike Edwards</author> + <title>Apache Tuscany - How To Build Site</title></properties><body> + + <section name="Tuscany Site Generation Overview"> + <p>The Tuscany website is built using the site plugin of Maven 2.0. A general guide to + the Maven site plugin can be found <a href="http://maven.apache.org/guides/mini/guide-site.html">here</a>. + </p> + <p> + 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. + <pre> + mvn site + </pre> + 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. + </p> + <p> + The actual live website for Tuscany is at the URL + <a href="http://incubator.apache.org/tuscany/">http://incubator.apache.org/tuscany/</a>. 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 + <pre> + mvn site-deploy + </pre> + 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: + <pre> +<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> + </pre> + The settings.xml file can be found in your $MAVEN_HOME/conf directory. + </p> + + </section> + <section name="Location and Format of the Source Files"> + + <p>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. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + + </section> + <section name="Creating your own Pages"> + <p> + 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. + </p> + <p> + First, create a file called foo.xml in the xdocs directory, similar to the following: + + <pre> +<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> + </pre> + + 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. + </p> + <p> + 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". + </p> + <p>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: + + <pre> +... +<menu name="Tuscany"> +... +<item name="Foo" href="foo.html" /> +</menu> +... + </pre> + 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. + </p> + <section name="Preferred Data Formats"> + <p> + 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. + </p> + <p>Please avoid the use of proprietary format such as Word documents. Not everyone has Microsoft office + installed and may find such formats unreadable. + </p> + </section> + </section> + +</body> +</document> |