source: trunk/j/doc/xmlmode.html @ 2

Last change on this file since 2 was 2, checked in by piso, 18 years ago

Initial checkin.

File size: 4.3 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2
3<html>
4
5<head>
6<title>J User's Guide - XML Mode</title>
7<LINK REL="stylesheet" HREF="j.css" TYPE="text/css">
8</head>
9
10<body>
11
12<a href="contents.html">Top</a>
13
14<hr>
15
16<h1>XML Mode</h1>
17
18<hr>
19
20<p>
21In XML mode, the bottom pane of the sidebar normally displays a tree
22representing the document you're editing. The tree is enabled by default. To
23disable it, add the following line to your 
24<a href="preferences.html">preferences</a> file:
25<pre>
26    enableTree=false
27</pre>
28<p>
29If the tree is enabled but no tree appears in the sidebar, the most likely
30reason is that j's XML parser was unable to parse the contents of the buffer.
31Parsing is done in a background thread, so it may take a little while for the
32tree to appear (or possibly a long while, if the document references a DTD on
33the Internet, for example).
34<p>
35The j distribution includes a version of the &AElig;lfred XML parser from
36<a href="http://www.microstar.com">Microstar</a>, taken from David Brownell's
37<a href="http://home.pacbell.net/david-b/xml">SAX2 XML Utilities</a>.
38
39<p>
40If you would rather use a different XML parser, you need to do two things:
41
42<ol>
43<li>
44Add the relevant jar file(s) to j's runtime <code>CLASSPATH</code>. If you
45build j from source, you can use the configure script's 
46<code>--with-extensions</code> option to do this:
47<pre>
48    ./configure --with-extensions=/usr/share/java/xerces.jar:/usr/share/java/xp.jar
49</pre>
50The j shell script that is automatically generated and installed will then use
51the correct <code>CLASSPATH</code>.
52<br><br>
53</li>
54
55<li> 
56
57Add a line to your <a href="preferences.html">preferences</a> file to specify
58the <a href="preferences.html#org.xml.sax.parser">org.xml.sax.parser</a>
59property, which tells j the fully qualified class name of the parser to use.
60For example:
61<pre>
62    org.xml.sax.parser=org.apache.xerces.parsers.SAXParser
63</pre>
64</li>
65</ol>
66
67<p>
68When you have a tree in the sidebar, the selection in the tree will follow
69along as you navigate in the edit buffer, but the tree is not automatically
70expanded to show nested nodes. You can use
71<a href="commands.html#xmlFindCurrentNode">xmlFindCurrentNode</a>, mapped by
72default to Ctrl =, to force the tree to expand all the way down to the node
73corresponding to the location of the caret in the edit buffer.
74
75<p>
76Clicking on a node in the tree moves the caret to the corresponding
77location in the edit buffer.
78<p>
79By default, the tree is not refreshed automatically if you make changes to the
80buffer. If you'd like the tree to be refreshed automatically, add a line like
81this to your <a href="preferences.html">preferences</a> file:
82<pre>
83    refreshTree=500
84</pre>
85The numeric parameter is the number of milliseconds the user must be idle
86before j refreshes the tree. A value of zero (which is the default) disables
87the automatic refresh functionality. In the current implementation, the minimum
88effective value is 500 milliseconds.
89<p>
90If the tree is enabled, you can use 
91<a href="commands.html#xmlParseBuffer">xmlParseBuffer</a>, mapped by default to
92Ctrl P, to force the tree to be refreshed. The parser uses the image of the
93buffer in memory, rather than the file on disk, so there's no need to save any
94changes you've made to the buffer before refreshing the tree.
95<p>
96If <a href="commands.html#xmlParseBuffer">xmlParseBuffer</a> encounters an
97error, the tree is not updated.  Instead, a message box displays the parser's
98error message, and the caret is moved to the location of the error in the edit
99buffer (as reported by the parser). You can use 
100<a href="commands.html#showMessage">showMessage</a>, mapped by default to Alt
101M, to have another look at the error message later.
102
103<p>
104Parser errors that occur when j is automatically refreshing the tree are not reported.
105<p>
106<a href="commands.html#xmlParseBuffer">xmlParseBuffer</a> invokes
107<a href="commands.html#xmlFindCurrentNode">xmlFindCurrentNode</a> automatically
108when it succeeds in updating the tree.
109
110<p>
111The following commands are also specifically relevant in XML mode:
112
113<ul>
114<li><a href="commands.html#xmlElectricEquals">xmlElectricEquals</a></li>
115<li><a href="commands.html#xmlFindMatch">xmlFindMatch</a></li>
116<li><a href="commands.html#xmlInsertEmptyElementTag">xmlInsertEmptyElementTag</a></li>
117<li><a href="commands.html#xmlInsertTag">xmlInsertTag</a></li>
118</ul>
119
120</body>
121
122</html>
Note: See TracBrowser for help on using the repository browser.