/
UpdatingDocs.shtml
182 lines (159 loc) · 7.68 KB
/
UpdatingDocs.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
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<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">
<meta name="author" content=
"Joseph A. Ellis - TesserAct Studios">
<meta name="Revised_By" content=
"Bob Blackwell - afticarr@sympatico.ca">
<meta name="Revised_By" content="Egbert Broerse">
<meta name="Revision" content=
"Updated instructions for GitHub instead of single file edit and ZIP">
<title>How to Update the JMRI Documentation</title>
<!-- 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.shtml" -->
<div id="mBody">
<!--#include virtual="Sidebar.shtml" -->
<div id="mainContent">
<h1>How to update the JMRI Documentation</h1>
<div class="toc">
<ul>
<li><a href="#screenshots">Creating Images from Screen
Shots</a></li>
<li><a href="#sizing">Sizing and Saving the
Images</a></li>
<li><a href="#submitpage">Submitting to GitHub</a></li>
</ul>
</div>
<p>JMRI's web pages and help screens are written in a
simple subset of HTML, the language that powers the web. The
most important part of the content is the plain text that
people will read, and the additional formatting information
is kept very minimal. To update a JMRI web page, you edit
these directly on GitHub web or on your computer with a plain
text editor.</p>
<p>Using a word processing app like MS Word or Front Page
to edit these .shtml documents
is not a good idea because they will probably add in their
own proprietary formatting codes that will mess things up,
possibly even to the point of being unusable by JMRI. Also,
don't rename existing files, or make changes to the
formatting information at the top or bottom.<br>
So you may concentrate on making editorial changes to the
text in the main body of a file, which is really what the
readers are paying attention to anyway.</p>
<p>To get started, you can drill down inside your computer's
JMRI program files to the folder for the DecoderPro manual.
On a Windows system, the location for this folder looks
something like this --
<code>C:\ProgramFiles\JMRI\help\en\manual</code>. In this
folder is a file called <code>index.shtml</code>. Open that
file with a text editor and look around. If you change
something, you can then open the page in the JMRI help system
and see how it looks (either keep a backup in case you want
the original page back, or you can reinstall JMRI to restore
it).</p>
<p>The most simple changes are just ones to the text itself:
To add a sentence or fix a wording, you just do that with the
editor. To add a break between paragraphs, e.g. to add a new
paragraph, you insert a "tag" that tells JMRI or a browser to
insert a paragraph break.</p>
<h2><a name="screenshots" id="screenshots">Creating Images
from Screen Shots</a></h2>
<h3>For Windows</h3>
To snag a screen shot in Windows, start by setting up the window
that holds what you want to capture. Make it take up as
little space on your screen as you can while it still shows
what you want. You can take a shot of the active window
(instead of your whole desktop), by pressing the
<code><Alt></code> key and the <code><Print
Screen></code> key at the same time. (Note: Depending on
your keyboard, you might need to press the
<code><Fn></code> or <code><Function-Lock></code>
key as well.) This puts the image on your "clipboard" and you
can paste it into an image-editing program such as Window's
Paint or Photoshop.
<h3>For Linux</h3>
If your
distro doesn't already have a default application that
supports the use of the <<code>Print Screen></code>> and
<<code>Alt + Print Screen</code>> keys you can install
<a href="http://www.kde.org/">KSnapshot</a> or your favorite
application to do your screen grabbing.
<h3>For macOS</h3>
After setting up your shot, hold down
<code><Apple + Shift + 4></code> key.
When you release them at the same time, the
cursor becomes a plus sign, and you can drag it around the
area you want. When you let go, you will have an image file
on your desktop.
<h3>Using a Third-Party Application</h3>
<p>On macOS we nowadays often use Evernote
<a href="https://evernote.com/intl/nl/products/skitch">Skitch</a>
to grab and touch up screen shots. Here's an example of that style:<br>
<img src="../images/GitHubPencil.png" width="285" height="101">
</p>
<p>We also love <a href=
"http://www.irfanview.com">IrFanView</a>
for screenshots, and it is free. With it, you can also
include your mouse cursor in your snapshot. You can also take
a series of shots easily, and even make a slideshow of them.
You can tell it what file format you want the image files to
be AND where you want them to be saved before you take the
shot, and that makes it easier to work with them in a program
like Paint or Photoshop.</p>
<h2><a name="sizing" id="sizing">Sizing and Saving the
Images</a></h2>
Any changes you
make to your image should be done before you use Amaya to
insert it into your document. Remember that if you change it,
it needs to be re-inserted. Make sure you save the image as
one of the following filetypes: PNG, JPG, or JPEG (not BMP or
TIF), and do not use any spaces or capital letters in the
image file name. Generally, a good size for the width of an
image is 500 pixels or less, at a web resolution of 72 pixels
per inch. If you know how to resize your images, it would be
very helpful.
<h2><a name="submitpage" id="submitpage">Submitting
to GitHub</a></h2>
<p>If you understand this, you
are ready to help us update the many JMRI documents that we
use for both the JMRI website and for the Help files in a
next software build.</p>
<p>When you submit your changes to be included in future JMRI
releases, they are given a quick check and then merged into
the previous content. The check is done by using GitHub tools
to find the parts of the file that have been changed.</p>
<h3>Prepare the Files</h3>The proper filetype to use for JMRI
has the .shtml extension. If you have made a (new) .html or
.htm file, you should change the extension to .shtml. Don't
use spaces or capital letters in your filenames. If you are
not changing or adding images, just save the file with its
original name, i.e. <span style=
"font-family: monospace">"index.shtml"</span>, in a location
where you can find it easily when you're ready to copy them
to GitHub.
<h3>Send to GitHub</h3>
<p>You can view the current <a href=
"https://github.com/JMRI/JMRI">JMRI repository on GitHub</a>.
To learn how to make changes to connect to GitHub and
contribute your changes, please read <a href=
"../getgitcode.shtml">Using Git</a>.
</p>
<!--#include virtual="/Footer" -->
</div>
</div>
</body>
</html>