/
Help.shtml
311 lines (261 loc) · 13.3 KB
/
Help.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
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html lang="en">
<head>
<meta name="generator" content=
"HTML Tidy for Mac OS X (vers 31 October 2006 - Apple Inc. build 15.17), see www.w3.org">
<title>JMRI: Use of JavaHelp</title>
<meta name="author" content="Bob Jacobsen">
<meta name="keywords" content=
"JMRI technical code Java Help JavaHelp"><!-- Style -->
<meta http-equiv="Content-Type" content=
"text/html; charset=us-ascii">
<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" -->
<div id="mBody">
<!--#include virtual="Sidebar" -->
<div id="mainContent">
<h1>JMRI Code: Use of JavaHelp</h1>
This page talks about technical
aspects of how JMRI provides help information using <a href=
"https://javahelp.java.net">JavaHelp</a> and <a href=
"http://jhelpdev.sourceforge.net/">JHelpDev</a>.
<h2>Organization of the help files</h2>The help files are
located in the "help" directory within the JMRI distribution
directory.
<p>The master copy of this is stored in our repository as the
"help" directory in the JMRI code repository. This means to
get your own local copy, just follow the steps on the
"<a href="getgitcode.shtml">getting the code</a>" page.</p>
<p>Within that, all the English-language files are located
within the "en" subdirectory. Eventually, this will let us
internationalize the help pages.</p>
<p>Within that, there are several file trees:</p>
<ul>
<li>package - organized like the source package tree, this
contains code-specific help files for e.g. a particular
window or component. For example, a window that's created
by the <code>jmri.jmrit.speedometer.SpeedometerFrame</code>
class (from the
<code>src/jmri/jmrit/speedometer/SpeedometerFrame.java</code>
file) should have its window-specific help in a file at
<code>package/jmri/jmrit/speedometer/SpeedometerFrame.shtml</code>.</li>
<li>html - general descriptions, tutorials, etc. This in
turn in organized into directories that represent general
areas.</li>
<li>manual - the most recent version of the DecoderPro et
al manuals reformatted for use in the help system. (Older
ones are stored in the <a href="WebSite.shtml">main web
site</a>)</li>
</ul>
In the long run, we want only two branches to this
structure: the "package" part of the tree for help
information that is specific to a particular piece of code,
and another part of the tree for more general information.
(It's a religious issue whether that 2nd part should be
called "html" or "manual"; the key thing is we end up with
just one). The web is meant to be a <em>web</em>, with many
paths through it to reach content. The second part of the
tree should also be organized as "one page, one topic", with
links to connect them as needed. <a name="limitations" id=
"limitations"></a>
<p>All the page formatting on JMRI help and other web
pages is done through included CSS files, originally created by
John Plocher. These are included from "/css" via
Server-Side Includes (SSI). The main file is at
<a href="http://jmri.org/css/default.css">/css/default.css</a>
and works with a few other files in that same directory.
Because JavaHelp ignores SSI, the CSS formatting
is ignored when JavaHelp is displaying the pages within the JMRI itself.
In that case, JavaHelp provides the formatting.
<h3>Limitations of JavaHelp HTML</h3>
JavaHelp displays "plain
old HTML 4.0", without providing some of the syntactic sugar
provided by many browsers to allow poor HTML to render.
Do not include any particular formatting options, specifically
including embedded CSS commands.
There are a couple of specific things to watch for:
<ul>
<li>Anchor tags need a specific format. Specifically, they
should be written
<pre style="font-family: monospace;">
<a name="pull">...</a>
</pre>around text content only. It's OK to be empty between the
open and close tags. It's not OK to combine them into a single
<code><a name="pull"/></code> tag; don't do that, as it
confuses JavaHelp.
<p>For example, to put an anchor on a heading, do</p>
<pre style="font-family: monospace;">
<h2><a name="foo">Foo!</a></h2>
</pre>
<p>Note: Incorrectly structured anchor tags (not like the
above) often cause just a < character appearing by
itself on the rendered help page.</p>
</li>
<li>Anchors need to use the "name" attribute rather than
the "id" attribute. See the item above for an example.</li>
<li>Do not use spaces or <code>%20</code> in anchor names.
If you must use a phrase for a name, use the underscore character:
"This_Anchor", not "This Anchor.</li>
<li>You can use the <code><code></code> element, or
the <code><pre></code> element, but you can't use
both together. <code><code></code> is good for
highlighting in-line text as being code (like we've used it
here); <code><pre></code> is good for making a block
of inline HTML or Java look right. To give a code-like
appearance to a block, wrap it in <code><pre
style="font-family: monospace;"></code></li>
<li>You can't count on any particular location for your
files on the local machine, so all links to other help
pages need to be relative.</li>
<li>Links to web pages outside the help system work. In
most cases they'll be automatically opened in an outside
web browser.</li>
</ul><a name="web" id="web"></a>
<a id="check"></a>
<h3>Checking Your Changes</h3>
The
<a href="ContinuousIntegration.shtml">Continuous Integration</a>
process checks all changes to JMRI Help files to make
sure they're OK. If you'd like to run that same check
while you're working, do:
<pre style="font-family: monospace;">
ant scanhelp
</pre>
<h2>Web access to help</h2>
It's inconvenient to have to
maintain two separate web pages for the main web site and the
help system. To reduce the need for that, we use a particular
form for the web pages in the help system.
<ul>
<li>Use ".shtml" file extensions so that the main web
servers will search the files for <a href=
"http://httpd.apache.org/docs/1.3/howto/ssi.html">server-side
includes</a>.</li>
<li>When you create a new page, start with a copy of either
the help/en/TemplateBar.shtml or
help/en/TemplatePlain.shtml template file, depending on
whether or not you want to include a "Sidebar" via a file
of the same name. This will put the proper top and bottom
matter in place to get the page properly displayed.</li>
</ul><a name="code" id="code"></a>
<h2>Access in the code</h2>
Within the JMRI code, access the
help system comes via the jmri.util.HelpUtil class. (For
historical reasons, there's a little bit of code in
apps.Apps, but you should ignore that).
<p>The easiest way to add a help menu to a frame is to have
it be a JmriJFrame (which you should do anyway), and call
addHelpMenu(...) after you've built any other menus.</p>
<p>By convention, we use a similar file tree for the source
code and help files. For example, the
<code>jmri.jmrit.simpleclock.SimpleClockFrame</code> class
inherits from JmriJFrame, and adds a help menu with the
line</p>
<pre style="font-family: monospace;">
addHelpMenu("package.jmri.jmrit.simpleclock.SimpleClockFrame", true);
</pre>The help file is then located at
<code>help/en/package/jmri/jmrit/simpleclock/SimpleClockFrame.shtml</code>.
<p>You should add the new page to the JHelpDev index to have JMRI
accept it as a Help target (see next the heading).</p>
<p>A number of help files have been put in place without any
contents; hopefully some users will edit them and contribute
them back. <a name="jhelpdev" id="jhelpdev"></a></p>
<h2>Creating the control files with JHelpDev</h2>
JavaHelp
uses various XML files to control how the table of contents
and index are displayed. We create those with <a href=
"http://jhelpdev.sourceforge.net/">JHelpDev</a>. Please don't
edit them manually.
<p>JHelpDev is now included in the JMRI dist. To use the
tool:</p>
<ol>
<li>Make sure you've updated to the most recent version in
the code repository before getting started.</li>
<li>You can run in batch mode by running <code>ant</code>
from the command line in the <code>help/en/</code>
directory. It'll still pop windows, but should run
to completion by itself. It might take a minute or so.</li>
<li>If you'd like to operate it manually, please
follow the rest of these bullets.
(Or if using Eclipse, right-click on the
help/en/build.xml file and select Run As Ant Build.)</li>
<li>Start the tool by clicking on the jhelpdev.jar file.
(If that doesn't work, try running either JHelpDev.csh or
JHelpDev.bat, depending on what kind of computer you
have)</li>
<li>Once the window appears, select "Open Project" under
the "File" menu.</li>
<li>Navigate to the "help" directory in your checked out
copy of the code, then the "en" directory within that, then
select the "JHelpDev.xml" file and click "Open".</li>
<li style="list-style: none">
<p>You may get a message about "[Fatal Error]
index.html:1:3: The markup declarations contained or
pointed to by the document type declaration must be
well-formed." Although it says it's fatal, it's really
not a problem. Just ignore it. On startup the Map (a file
containing the JHelpDev index of all anchors in the JMRI
help system) is regenerated.</p>
</li>
<li>By clicking the "Index Editor" tab or the "TOC Editor"
tab, review and update the Help entries. A red line marks a
hyperlink that JHelpDev can't locate on disk. Right-click
on such a line to open the Edit context menu.</li>
<li>Click the "Create All" button to recreate the TOC,
Index, etc.</li>
<li>Then, back on the command line and in the help/en
directory, invoke "ant index TOC" to create the web index and table
of contents pages. </li>
</ol>
<p>The various control files that JavaHelp uses are stored in
our code repository, so once you've done this they will show
as modified. Please check them in when you check in new Help
files so other people don't have to recreate those control
files for themselves. <a name="tocAndIndex" id=
"tocAndIndex"></a></p>
<h3>Table of Contents and Index</h3>
Java Help includes a
<a href="http://jmri.org/help/en/webtoc.shtml">table of
contents</a> and an <a href=
"http://jmri.org/help/en/webindex.shtml">index</a>. These are
both available as hyperlinks on the web, and provided via a
nicer user interface when using JavaHelp in the program.
<p>The underlying information must be manually maintained in
the help/en/JmriHelp_enTOC.xml and
help/en/JmriHelp_enIndex.xml files, respectively. JHelpDev
then makes the files that Java Help needs, and an "ant" step
in the directory makes the webtoc.shtml and webindex.shtml
files that are displayed on the web.</p>
<p>Note: This means you should not manually change the
webToc.shtml and webindex.shtml files, because those changes
will be overwritten by later steps.</p>
<p>The JmriHelp_enTOC.xml and JmriHelp_enIndex.xml files are
straight-forward XML, and you can manually edit them. Make
sure to run the JHelpDev "create all" step and "ant" after
doing so.</p>
<p>You can also use the JHelpDev tool to add items to the
table of contents and index if you'd like. There's more info
on how to do that on the <a href=
"http://jhelpdev.sourceforge.net/">JHelpDev web site</a>.
Remember to run "ant" after that to include your updates on
the web versions. <a name="site" id="site"></a></p>
<h2>Updating the JMRI.org site</h2>
<p>Changes to Help pages
which are checked-in should show up automatically on the
JMRI.org site after a short while. There's a <a href=
"http://jmri.tagadab.com/jenkins/job/WebSite/job/generate-website/">
Jenkins job</a> that handles periodic updates for the static
(from repository, unlike e.g. Javadoc) pages.</p>
<!--#include virtual="/Footer" -->
</div><!-- closes #mainContent-->
</div><!-- closes #mBody-->
</body>
</html>