diff options
Diffstat (limited to 'branches/site-20060730-mvnbased/src/site/xdoc/howtobuildsite.xml')
| -rw-r--r-- | branches/site-20060730-mvnbased/src/site/xdoc/howtobuildsite.xml | 178 |
1 files changed, 0 insertions, 178 deletions
diff --git a/branches/site-20060730-mvnbased/src/site/xdoc/howtobuildsite.xml b/branches/site-20060730-mvnbased/src/site/xdoc/howtobuildsite.xml deleted file mode 100644 index 43e9874815..0000000000 --- a/branches/site-20060730-mvnbased/src/site/xdoc/howtobuildsite.xml +++ /dev/null @@ -1,178 +0,0 @@ -<?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> |