Debian Codegraph @

doc/syntax_error.html

raw ◀ ▶
Source reconstructed at patch state 0 of 1 — not the installed (fully patched) source.
1 Debian patch touch this file
1 <html>
2 <head>
3 <title>Syntax error handling</title>
4 </head>
5 <body>
6
7 <h1 align="center">Syntax error handling<br />>=======================&lt;</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 &lt;url> 2>&amp;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. "&lt;!------>" 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>