1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
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>
|
