| 1 |
<html> |
| 2 |
<head> |
| 3 |
<title>Syntax error handling</title> |
| 4 |
</head> |
| 5 |
<body> |
| 6 |
|
| 7 |
<h1 align="center">Syntax error handling<br />>=======================<</h1> |
| 8 |
|
| 9 |
<p> |
| 10 |
[This file explains how netrik handles syntax errors in HTML pages, why it does |
| 11 |
so, and what to do about that. See index.txt or |
| 12 |
<a href="index.html">index.html</a> for an overview of available |
| 13 |
netrik documentation.] |
| 14 |
</p> |
| 15 |
|
| 16 |
<p> |
| 17 |
or: |
| 18 |
</p> |
| 19 |
|
| 20 |
<h2>Why does netrik always complain about HTML syntax errors??</h2> |
| 21 |
|
| 22 |
<p> |
| 23 |
or: |
| 24 |
</p> |
| 25 |
|
| 26 |
<h3>No matter what site I load, (almost) always I get error messages. That can't be OK?!</h3> |
| 27 |
|
| 28 |
<p> |
| 29 |
Well, it *is* OK... The problem is: Actually almost all sites *are* more or |
| 30 |
less broken. |
| 31 |
</p> |
| 32 |
|
| 33 |
<p> |
| 34 |
Other browsers simply ignore the errors, hoping that the effect will resemble |
| 35 |
more or less what the author intended -- and nobody ever knows, but for some |
| 36 |
little blemish maybe, where no one cares about. (If Netscape wasn't so tolerant |
| 37 |
about syntax errors in the first place, we wouldn't have that problem today :-( |
| 38 |
) However, the browser can only "guess" what the author intended, and that |
| 39 |
doesn't always work out; such errors can cause the page to be layouted |
| 40 |
completely wrong, including missing text parts etc. That's why netrik warns |
| 41 |
about them, so the user at least knows what the matter is, and also gets the |
| 42 |
chance to tell the page author about the problem. (s.b.) |
| 43 |
</p> |
| 44 |
|
| 45 |
<p> |
| 46 |
Note that XHTML even *requires* a browser to abort on syntax errors -- sadly, |
| 47 |
XHTML is not very popular. (Yet?...) |
| 48 |
</p> |
| 49 |
|
| 50 |
<p> |
| 51 |
Of course, it might also happen that netrik sees an error where there is none |
| 52 |
-- but this is rather rare, and would indicate a bug in netrik. Of course, if |
| 53 |
you encounter such a situation, don't hesitate to send a bug report. ($ |
| 54 |
<a href="mailto:[email protected]">[email protected]</a>$ |
| 55 |
) |
| 56 |
</p> |
| 57 |
|
| 58 |
<h2>Can't I turn that off?</h2> |
| 59 |
|
| 60 |
<p> |
| 61 |
Well, actually, you can: There are the two options "--broken-html" and |
| 62 |
"--ignore-broken". "--ignore-broken" will prevent netrik complaining about |
| 63 |
*any* syntax errors, while "--broken-html" only turns off warnings about common |
| 64 |
errors which in most cases can be guessed correctly and nicely worked around. |
| 65 |
(But not always!) |
| 66 |
</p> |
| 67 |
|
| 68 |
<p> |
| 69 |
Presently, "--broken-html" is the default, so less critical erros won't cause |
| 70 |
netrik to stop and wait for keypress. (The error messages are still displayed, |
| 71 |
but they just scroll through in this mode.) This is because the current |
| 72 |
interface makes the warnings quite obtrusive; we will change the default again |
| 73 |
when a better UI will allow displaying the messages in a less disturbing |
| 74 |
manner. |
| 75 |
</p> |
| 76 |
|
| 77 |
<p> |
| 78 |
However, please avoid usage of these options if possible. While "--broken-html" |
| 79 |
probably can't be helped for now, it seems generally a bad idea to use |
| 80 |
"--ignore-broken". |
| 81 |
</p> |
| 82 |
|
| 83 |
<p> |
| 84 |
Still, please take the (little) trouble to tell the page author about the |
| 85 |
problem. |
| 86 |
</p> |
| 87 |
|
| 88 |
<h2>Reporting a problem</h2> |
| 89 |
|
| 90 |
<p> |
| 91 |
Normally you will find an e-mail address of the right contact at the bottom of |
| 92 |
the page, or on some "contact" page. Most authors will be greatful for the |
| 93 |
information, and will gladly fix the problem -- once and for all. |
| 94 |
</p> |
| 95 |
|
| 96 |
<p> |
| 97 |
You can improve your chances by telling exactly what the problem is. To find |
| 98 |
out, you can load the page again, but using the "--debug" option. While parsing |
| 99 |
the page, netrik will dump the source in this mode. When an error is |
| 100 |
encountered, the last charactacter printed before the error message is the |
| 101 |
offending one. Note however that in some cases the real reason for the problem |
| 102 |
may be somewhere before. |
| 103 |
</p> |
| 104 |
|
| 105 |
<p> |
| 106 |
If the output is too big, you may either use the --dump option and pipe the |
| 107 |
output through some pager (but note that the debug output is written to stderr, |
| 108 |
so you'll need to redirect it: "netrik --debug --dump <url> 2>&1 |less -R" or |
| 109 |
something the like), or you can use the "--fussy-html" option, causing netrik |
| 110 |
to abort after the first error is detected. |
| 111 |
</p> |
| 112 |
|
| 113 |
<p> |
| 114 |
Alternatively, you can use the W3Cs (WWW Consortium) HTML validating service. |
| 115 |
(<a href="http://validator.w3.org">http://validator.w3.org</a>) |
| 116 |
This will create a report with all problems nicely listed -- very helpful for |
| 117 |
the page author. |
| 118 |
</p> |
| 119 |
|
| 120 |
<h2>A note on comments</h2> |
| 121 |
|
| 122 |
<p> |
| 123 |
Netrik implements full SGML comment parsing. The problem is that the comment |
| 124 |
syntax in SGML is fairly complicated; most authors do not know it, and thus do |
| 125 |
not know that putting a "--" string inside a comment normally generates errors. |
| 126 |
In most cases these are quite obvious; netrik will print an error message, and |
| 127 |
use a workaround which will work in most cases, but not always -- just like for |
| 128 |
other typical errors. |
| 129 |
</p> |
| 130 |
|
| 131 |
<p> |
| 132 |
However, there are some constructs which *are* valid SGML -- but do not make |
| 133 |
what the author probably intended. "<!------>" is a typical example: It is |
| 134 |
valid, but the comment doesn't terminate; everything behind it will also be |
| 135 |
treated as part of the comment! As it is not an error, netrik can't print an |
| 136 |
error message or apply a workaround; instead, just a warning is printed. |
| 137 |
</p> |
| 138 |
|
| 139 |
<p> |
| 140 |
Often such an unterminated comment will generate other errors later, because it |
| 141 |
interferes with other comments or because it stretches to the end of the file; |
| 142 |
in such a case, the warning may help finding the problem. In other cases |
| 143 |
however, no error is generated at all -- the warning is the only cue that |
| 144 |
something went wrong. |
| 145 |
</p> |
| 146 |
|
| 147 |
<h2>Warnings in general</h2> |
| 148 |
|
| 149 |
<p> |
| 150 |
Other similar situations are thinkable. That's why netrik also prints warnings |
| 151 |
on things that are strictly speaking valid hatml, but explicitely discouraged |
| 152 |
in the HTML standard -- while some browsers will handle them correctly, others |
| 153 |
might do otherwise; or sometimes a really correct behaviour even produces |
| 154 |
results different from what the author intended and sees in popular browsers. |
| 155 |
</p> |
| 156 |
|
| 157 |
<p> |
| 158 |
Warnings will normally (in --valid-html or --broken-html mode) only scroll |
| 159 |
through, but without pausing with an additional message after parsing is |
| 160 |
finished. To see all warnings, use --clean-html . |
| 161 |
</p> |
| 162 |
|
| 163 |
</body> |
| 164 |
</html> |