forked from nlplab/brat
-
Notifications
You must be signed in to change notification settings - Fork 1
/
troubleshooting.html
195 lines (171 loc) · 8.02 KB
/
troubleshooting.html
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
<html lang="en-US" xml:lang="en-US" xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>brat troubleshooting</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
<link rel="stylesheet" type="text/css" href="jquery-theme/jquery-ui-redmond.css"/>
<link rel="shortcut icon" href="../favicon.ico"/>
</head>
<style type="text/css">
</style>
<body>
<div id="manual-main" class="center">
<div id="header" class="ui-widget-header rounded">
<span><a href="index.html">home</a></span>
<span style="color:lightblue" class="unselectable">|</span>
<span><a href="introduction.html">introduction</a></span>
<span style="color:lightblue" class="unselectable">|</span>
<span><a href="case-studies.html">examples</a></span>
<span style="color:lightblue" class="unselectable">|</span>
<span><a href="features.html">features</a></span>
<span style="color:lightblue" class="unselectable">|</span>
<span><a href="installation.html">installation</a></span>
<span style="color:lightblue" class="unselectable">|</span>
<span><a href="manual.html">manual</a></span>
<div id="menulogo" class="logo unselectable">brat</div>
</div>
<h1>brat troubleshooting</h1>
<p>This document provides information on how to address specific
problems with brat. For general instructions on use, see the
<a href="manual.html">brat manual</a>.
</p>
<h2 id="client-trouble">Trouble using brat</h2>
<p>This section relates to issues using an existing brat
installation that has been working for other users (client and
UI issues). If you have trouble creating a new installation of
brat on a server, skip to the
<a href="#server-trouble">section on installation</a>.
</p>
<h3>1) brat fails to start, or some features do not work</h3>
<div style="color:#666666; width:30%; float:right; margin:auto; padding-left:5em">
<b>Sidebar: why is browser X not supported?</b>
<p>Most likely because the browser does not fully implement
support for
<a href="http://en.wikipedia.org/wiki/Scalable_Vector_Graphics">Scalable
Vector Graphics</a> (SVG).
</p>
<p>The core of brat visualization is based on SVG. Although SVG
has been a recommended web standard for over a decade, not all
browsers have implemented it; in particular, Internet Explorer
has only started supporting SVG from version 9. Because SVG is
central to the brat visualization, supporting browsers that do
not implement it would require rewriting much of the brat
client. There are currently no plans to do this, and we ask
users of browsers that do not implement SVG support to
consider using one of the many supported browsers when using
brat.
</p>
</div>
<p>It may be that your browser is not fully supported. Please
check your browser on the
<a href="supported-browsers.html">brat browser support</a>
page.
</p>
<p><strong>If your browser is listed as supported</strong>
but brat fails to work, please check the following:
<ul>
<li>JavaScript should be permitted. The layout and editing
functions of brat are implemented in JavaScript, and
having JavaScript switched off either entirely or limited
using blockers such as <a href="http://noscript.net/">NoScript</a>
will prevent brat from working.
</li>
<li>Cookies should be permitted for editing. brat identifies
users by a session cookie, so users who refuse cookies
cannot be verified as having editing permissions. (Cookies
can be switched off for visualization.)
</li>
<li>The browser should be a relatively recent version. Older
versions of supported browsers may work partially or not
at all. Please consider upgrading if you are running an
older version.
</li>
</ul>
</p>
<p><strong>If your browser is listed as <i>not</i>
supported</strong>, please consider installing a supported
browser. Most of the supported browsers are freely
available, and installation only takes a couple of
minutes. (You can also try pushing the brat developers to
improve support for your browser!)
</p>
<h3>2) brat works, but is slow</h3>
<p>This issue may relate to the browser, the system used to run
it, server load, or document size.
</p>
<p><b>Browser</b> implementations of the core technologies used
to implement brat (vector graphics and JavaScript) have
greatly improved recently, and installing the latest version
of your favorite browser may resolve the issue. There are also
known differences in the efficiency of various browsers'
implementations of these technologies, and trying a different
browser may help. brat is known to work well on recent
versions of the <a href="http://www.google.com/chrome">Google
Chrome</a> and <a href="http://www.apple.com/safari/">Apple
Safari</a> browsers.
</p>
<p><b>System</b> requirements for running the brat client are
not high, and most modern machines (including laptops) should
be able to run brat without noticeable slowdown. However,
low-powered or memory-limited platforms such as smartphones
and older tablets as well as old machines may be unable to run
efficiently. Processing and memory requirements can be reduced
by limiting the size of collections and documents accessed on
such devices.
</p>
<p><b>Server</b> requirements for running brat are also quite
modest, but heavy server load will be noticed also as slowdown
on brat clients accessing the server. If you are running both
the brat client and server on the same machine, try
closing down other programs to release server resources.
</p>
<p><b>Document</b> size increases processing power requirements
on brat. The system does not yet implement progressive or
partial rendering; that is, the whole document is always
rendered even though most of it may not be shown on-screen.
We hope to address this limitation in a future release, but
for the current version we suggest to partition large
documents into smaller sections for annotation.
</p>
<h3>3) brat was working, but crashed or misbehaved</h3>
<p>(<b>in short</b>: try reloading the page.</b>)</p>
<p>You may have encountered a bug in brat. Please contact the
developers and report the issue! We should be able to fix
this, in particular if the issue repeats when you perform a
particular sequence of actions.
</p>
<p>(It is also possible that you are encountering a browser
bug. Though relatively rare, they do occur. In this case
updating your browser might help.)
<p>In general, you should be able to recover from a brat
"crash" or "hang" simply by reloading the
page in your browser (or, in case of browser bug, reloading
the browser). <span style="color:green"><b>It is always safe
to reload brat</b></span>: you will not lose any of your
work; all annotations are immediately stored on the server
as soon as you make them.
</p>
<h2 id="server-trouble">Trouble installing brat on a server</h2>
<h3>Only a defunct menu bar on a blank screen is shown</h3>
<p>It is possible that the brat server script <tt>ajax.cgi</tt>
is not being executed by your web server.
</p>
<p>To check if this is the case, point a browser directly at the
<tt>ajax.cgi</tt> script: if your brat installation is located
at, for example, <tt>http://127.0.0.1/~brat/</tt>, try
entering the URL <tt>http://127.0.0.1/~brat/ajax.cgi</tt>. If
this gives an "internal server error" or similar
message, the script is not being executed. (If you receive a
"no action" message from brat, the issue is
elsewhere.)
</p>
<p>To fix this, verify that your web server is configured to
allow the execution of CGI scripts in the directory into which
brat is installed (see <a href="installation.html">installation
instructions</a>) and that the script <tt>ajax.cgi</tt> is
executable by the web server.
</p>
<div id="footer">
© 2010-2012 brat contributors
</div>
</body>
</html>