/
WebSite.shtml
328 lines (296 loc) · 15.4 KB
/
WebSite.shtml
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
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html lang="en">
<head>
<title>
JMRI: JMRI.org Web Site Help
</title>
<meta name="author" content="Bob Jacobsen">
<meta name="keywords" content="JMRI technical code web site">
<!-- The combination of "Define" and {Header, Style, Logo and Footer} comments -->
<!-- are an arbitrary design pattern used by the update.pl script to -->
<!-- easily replace the common header/footer code for all the web pages -->
<!-- delete the following 2 Defines if you want to use the default JMRI logo -->
<!-- or change them to reflect your alternative logo -->
<!-- Style -->
<meta http-equiv=Content-Type content="text/html; charset=iso-8859-1">
<link rel="stylesheet" type="text/css" href="/css/default.css" media="screen">
<link rel="stylesheet" type="text/css" href="/css/print.css" media="print">
<link rel="icon" href="/images/jmri.ico" type="image/png">
<link rel="home" title="Home" href="/">
<!-- /Style -->
</head>
<body>
<!--#include virtual="/Header.shtml" -->
<div id="mBody">
<!--#include virtual="Sidebar.shtml" -->
<div id="mainContent">
<h1>JMRI: Web Site</h1>
<p>This page discusses technical aspects behind the JMRI web site
at <a href="http://jmri.org">jmri.org</a> and also providing
parts of the help system in JMRI.</p>
<p>
If you just want to know how to make a small change to a web or
help page, please see the
<a href="webupdate/UpdatingDocs.shtml">Updating JMRI Documentation instructions</a>.</p>
<h2>Structure of Information</h2>
<p>We distinguish between three types of information on the main web site:</p>
<ol>
<li>User information which is useful at run time.
This is made available both via our <a href="Help.shtml">JavaHelp</a>,
and also directly by placing those files on the web.
<li>User information which is either not useful at run time, such as
instructions for installing the software, or is too large for inclusion
in releases, e.g. video clinics.
<li>Reference information from releases, such as decoder definitions, copies of scripts,
JavaDocs, etc.
</ol>
<p>We provide these separately:</p>
<ol>
<li>Run-time user information is made available by putting the help system
on the web site.
<li>Other user information is stored in our
<a href="https://github.com/JMRI/website"><tt>JMRI/website</tt> GitHub repository</a>
and placed directly on the web site.
<li>Reference information is put on the web site from their own repository locations,
or created by automated Ant scripts during release builds.
</ol>
<h2>Technology</h2>
<p>Page formatting is done using CSS, originally set up by John Plocher.
All pages should reference the CSS files for screen and printing
from the "/css" directory. This also means that you should leave the
formatting to the style sheets, and minimize the explicit formatting
that you do in HTML directly.</p>
<p>
Because we use our web pages in JavaHelp, there are some restrictions
on use of tags. See our <a href="Help.shtml">JavaHelp web page</a> for more on this.</p>
<p>
We are using
<a href="http://httpd.apache.org/docs/2.2/howto/ssi.html">server-side includes</a>
to provide consistent headers, sidebars and footers.
This allows us to share HTML
content between the web and the JavaHelp system
used by the program itself. Each page will contain just content,
plus includes for files named "Header", "Sidebar" and "Footer"
which contain the navigation information.
Eventually, all but a few index pages will have
".shtml" extensions. (The remaining index.html pages keep that name
so that people who request just a directory URL will be served something useful).</p>
<p><a name="redirect"></a>
We are using .htaccess files to do redirects when a web page is removed. This
lets older bookmarks continue to work.
The
<a href="https://github.com/JMRI/website/tree/master/hardware/.htaccess">hardware/.htaccess file</a> provides an example.
For more information on the syntax, see the
<a href="https://httpd.apache.org/docs/current/mod/mod_rewrite.html#rewriterule">Apache mod_rewrite documentation</a>.
<h2>Directory Organization</h2>
<p>The web site contains several separate areas:</p>
<ul>
<li>jython, resources, xml, web - these are taken directly from the
directories of the same name in the
<a href="https://github.com/JMRI/website"><tt>JMRI/JMRI</tt> repository</a>
They are only occasionally referenced directly.
<li>help - also used for the JavaHelp system, this has the internal
structure described below and on our
<a href="Help.shtml">JavaHelp</a>
page.
</ul>
<p>Another group are from the
<a href="https://github.com/JMRI/website"><tt>JMRI/website</tt> repository</a>,
and are checked out at
the root of the web server.</p>
<ul>
<li>releasenotes - Specific information on each test and production release
<li>install - Information on how to install the JMRI software on various kinds of computers
<li>community - Clinics, web pages, and other community-contributed information
<li>images - (Images used by web pages)
<li>contact -
</ul>
<p>Finally, some of the site is generated from the JMRI source itself, as opposed to being contained in
the source. The <a href="http://jmri.org/JavaDoc/doc/">Javadoc</a> is one such section, along with some of the
<a href="http://jmri.org/xml/XSLT">human-readable information</a> about defined decoders.
<h2>Updating the jmri.org site</h2>
<p>Most of the web site contents is updated hourly from jobs running on one of the
project's Jenkins build servers. The directories listed above constitute most of the site,
and this content is updated from the JMRI repository without any additional work.</p>
<ul>
<li><a href=
"http://builds.jmri.org/jenkins/job/Web%20Site/job/Website%20from%20JMRI%20GitHub%20JMRI%20repository/">static
content from JMRI/JMRI repository, e.g. help, xml, etc in JMRI distributions</a></li>
<li><a href=
"http://builds.jmri.org/jenkins/job/Web%20Site/job/Website%20from%20JMRI%20GitHub%20website%20repository/">static
content from JMRI/website repository, e.g. website-only information</a></li>
<li><a href=
"http://builds.jmri.org/jenkins/job/Web%20Site/job/Website%20from%20JMRI%20GitHub%20website-legal%20repository/">static
content from JMRI/website-legal repository, e.g. content around the JMRI-Katzer legal case</a></li>
</ul>
<p>The regeneration of the Javadoc and xml content involves
significantly more work than merely updating a directory, and so these are only done once per day, as needed,
by the
<a href="http://jmri.tagadab.com/jenkins/job/WebSite/job/generate-website/">Generate Website</a>
job on the
<a href="http://jmri.tagadab.com/jenkins/">production Jenkins server</a>.</p>
<a name="local"></a><h2>Local Web Site: Mac OS X</h2>
<p>If you want to host a copy of the JMRI web site on your local
Mac OS X machine, follow these instructions to first configure
the Apache server to do server-side includes, and then make
a copy of the web site files available to the server.</p>
<p>A similar process may work for Linux (or even Windows) systems
with Apache installed.</p>
<ol>
<li>To make sure that your local server has the right options enabled, edit the Apache web server's configuration file.
<ul>
<li>On Mac OS X 10.4 (Tiger), this is the /etc/httpd/httpd.conf file
<li>On Mac OS X 10.5 (Leopard) and later, this is the /etc/apache2/httpd.conf file
</ul>
Once you've located the file, open it with your favorite
editor (You'll need to authenticate with the administrator password to
modify this file).
<ul>
<li>
To turn on server-side includes, find the section that
looks like
<pre>
# This may also be "None", "All", or any combination of "Indexes",
# "Includes", "FollowSymLinks", "ExecCGI", or "MultiViews".
#
# Note that "MultiViews" must be named *explicitly* --- "Options All"
# doesn't give it to you.
#
Options Indexes FollowSymLinks MultiViews
</pre>
Add the word "Includes" to the last line so it looks like
<pre>
Options Includes Indexes FollowSymLinks MultiViews
</pre>
<li>Now, configure the server to handle files with ".shtml"
extensions. Find the section that looks like (the leading comment
may be different):
<pre>
#
# To use server-parsed HTML files
#
#AddType text/html .shtml
#AddHandler server-parsed .shtml
</pre>
and un-comment the last two lines so that it looks like
<pre>
#
# To use server-parsed HTML files
#
AddType text/html .shtml
AddHandler server-parsed .shtml
</pre>
Then find the reference to the include_module and make sure it's loaded by a line like:
<pre>
LoadModule include_module libexec/apache2/mod_include.so
</pre>
By default, that's commented out with a leading # character.
<li>Finally, configure the server to allow <a href="#redirect">.htaccess files to provide redirects</a>.
We use this to allow people with old URLs in bookmarks to reach the right current pages.
<p>
Find a section that looks like:
<pre>
DocumentRoot "/Library/WebServer/Documents"
Directory "/Library/WebServer/Documents"
</pre>
There's an indented section directly below that. Find the part that looks like:
<pre>
#
# AllowOverride controls what directives may be placed in .htaccess files.
# It can be "All", "None", or any combination of the keywords:
# AllowOverride FileInfo AuthConfig Limit
#
AllowOverride None
</pre>
Change the last line to allow overrides (which is what a .htaccess file does):
<pre>
AllowOverride All
</pre>
Then find the reference to the rewrite_module and make sure it's loaded by a line like:
<pre>
LoadModule rewrite_module libexec/apache2/mod_rewrite.so
</pre>
By default, that's commented out with a leading # character.
<p>
JMRI's web site uses index.shtml files as index pages.
To make sure that those will display by default,
e.g. if you use a partial URL like
<a href="http://jmri.org/download">http://jmri.org/download</a>,
find the line containing "DirectoryIndex" and add
"index.shtml" to the existing list of index-like file names.
<p>
We also want PHP turned on, so that the indices for the resources pages will work.
Find the follow line and make sure it's not commented out:
<pre>
LoadModule php5_module libexec/apache2/libphp5.so
</pre>
</li>
</ul>
</li>
<li>Install the JMRI files to be served:
<ul>
<li><a name="link"></a>Check out both the JMRI/JMRI
and JMRI/website repositories to somewhere on your computer. It's OK for these
to be outside the web server's directory tree.
<li>Change to the web server directory
<pre>
cd /Library/WebServer/Documents
</pre>
<a name="locallink"></a>
<li>Set symbolic links to bring in content from the two repositories:
<pre>
~me/git/website/setSymLinks.sh ~me/git/JMRI ~me/git/website
</pre>
where "~me/git/website" is the path to the JMRI/website repository that you just checked out,
and "~me/git/JMRI" is the path to the JMRI/website repository. setSymLinks.sh sets up
symbolic links that let your web server see the top of the JMRI web site as if the files
were directly present.
</ul>
<li>Restart your computer to reinitialize the web server.</li>
<li>Test it by trying to display the URL
<a href="http://localhost/">http://localhost/index.shtml</a>,
which should get you a JMRI top-level page.
</li>
</ol>
<a name="catalog"></a>
<h3>Installing a local XML catalog</h3>
Many JMRI XML files contain XIncludes that reference
other XML files with URLs like "http://jmri.org/xml/schema/types/turnouts-2-9-6.xsd".
When a JMRI program encounters those, it automatically converts those to
a local file reference. Other tools, like NetBeans and xmllint, don't know to do that.
<p>
Installing a local XML catalog, and then telling your tools to use it, can solve this.
<ul>
<li>
If you're not running a local webserver, you can provide a limited solution by
copying the xml/catalog.xml file from your JMRI directory to an /etc/xml/catalog file.
(Note that this is for Linux and Mac OS X and it's not clear what works for Windows;
you might have to sudo to do this; that there's no .xml suffix on the
resulting file; if there's already
a file there you'll have to manually merge the contents; you'll have to update
this periodically as JMRI continues to evolve)</li>
<li>
Alternately, if you're running a local server as
<a href="#local">described above</a>,
you can provide a more generic solution by copying
the following to a /etc/xml/catalog file
(Note that this is for Linux and Mac OS X and it's not clear what works for Windows;
you might have to sudo to do this; that there's no .xml suffix on the
created file; and if there's already
a file there you'll have to manually merge the contents; but at least you won't
have to update this in the future!):
<pre>
<?xml version='1.0'?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<rewriteURI uriStartString="http://jmri.org/xml/"
rewritePrefix="http://localhost/xml/" />
</catalog>
</pre>
This catalog redirects all HTTP references to the "xml" directory at the JMRI website
to the "xml" directory on your local web server.</li>
</ul>
<!--#include virtual="/Footer.shtml" -->
</div><!-- closes #mainContent-->
</div> <!-- closes #mBody-->
</body>
</html>