| 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> |
|---|
| 21 | In XML mode, the bottom pane of the sidebar normally displays a tree |
|---|
| 22 | representing the document you're editing. The tree is enabled by default. To |
|---|
| 23 | disable it, add the following line to your |
|---|
| 24 | <a href="preferences.html">preferences</a> file: |
|---|
| 25 | <pre> |
|---|
| 26 | enableTree=false |
|---|
| 27 | </pre> |
|---|
| 28 | <p> |
|---|
| 29 | If the tree is enabled but no tree appears in the sidebar, the most likely |
|---|
| 30 | reason is that j's XML parser was unable to parse the contents of the buffer. |
|---|
| 31 | Parsing is done in a background thread, so it may take a little while for the |
|---|
| 32 | tree to appear (or possibly a long while, if the document references a DTD on |
|---|
| 33 | the Internet, for example). |
|---|
| 34 | <p> |
|---|
| 35 | The j distribution includes a version of the Æ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> |
|---|
| 40 | If you would rather use a different XML parser, you need to do two things: |
|---|
| 41 | |
|---|
| 42 | <ol> |
|---|
| 43 | <li> |
|---|
| 44 | Add the relevant jar file(s) to j's runtime <code>CLASSPATH</code>. If you |
|---|
| 45 | build 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> |
|---|
| 50 | The j shell script that is automatically generated and installed will then use |
|---|
| 51 | the correct <code>CLASSPATH</code>. |
|---|
| 52 | <br><br> |
|---|
| 53 | </li> |
|---|
| 54 | |
|---|
| 55 | <li> |
|---|
| 56 | |
|---|
| 57 | Add a line to your <a href="preferences.html">preferences</a> file to specify |
|---|
| 58 | the <a href="preferences.html#org.xml.sax.parser">org.xml.sax.parser</a> |
|---|
| 59 | property, which tells j the fully qualified class name of the parser to use. |
|---|
| 60 | For example: |
|---|
| 61 | <pre> |
|---|
| 62 | org.xml.sax.parser=org.apache.xerces.parsers.SAXParser |
|---|
| 63 | </pre> |
|---|
| 64 | </li> |
|---|
| 65 | </ol> |
|---|
| 66 | |
|---|
| 67 | <p> |
|---|
| 68 | When you have a tree in the sidebar, the selection in the tree will follow |
|---|
| 69 | along as you navigate in the edit buffer, but the tree is not automatically |
|---|
| 70 | expanded to show nested nodes. You can use |
|---|
| 71 | <a href="commands.html#xmlFindCurrentNode">xmlFindCurrentNode</a>, mapped by |
|---|
| 72 | default to Ctrl =, to force the tree to expand all the way down to the node |
|---|
| 73 | corresponding to the location of the caret in the edit buffer. |
|---|
| 74 | |
|---|
| 75 | <p> |
|---|
| 76 | Clicking on a node in the tree moves the caret to the corresponding |
|---|
| 77 | location in the edit buffer. |
|---|
| 78 | <p> |
|---|
| 79 | By default, the tree is not refreshed automatically if you make changes to the |
|---|
| 80 | buffer. If you'd like the tree to be refreshed automatically, add a line like |
|---|
| 81 | this to your <a href="preferences.html">preferences</a> file: |
|---|
| 82 | <pre> |
|---|
| 83 | refreshTree=500 |
|---|
| 84 | </pre> |
|---|
| 85 | The numeric parameter is the number of milliseconds the user must be idle |
|---|
| 86 | before j refreshes the tree. A value of zero (which is the default) disables |
|---|
| 87 | the automatic refresh functionality. In the current implementation, the minimum |
|---|
| 88 | effective value is 500 milliseconds. |
|---|
| 89 | <p> |
|---|
| 90 | If the tree is enabled, you can use |
|---|
| 91 | <a href="commands.html#xmlParseBuffer">xmlParseBuffer</a>, mapped by default to |
|---|
| 92 | Ctrl P, to force the tree to be refreshed. The parser uses the image of the |
|---|
| 93 | buffer in memory, rather than the file on disk, so there's no need to save any |
|---|
| 94 | changes you've made to the buffer before refreshing the tree. |
|---|
| 95 | <p> |
|---|
| 96 | If <a href="commands.html#xmlParseBuffer">xmlParseBuffer</a> encounters an |
|---|
| 97 | error, the tree is not updated. Instead, a message box displays the parser's |
|---|
| 98 | error message, and the caret is moved to the location of the error in the edit |
|---|
| 99 | buffer (as reported by the parser). You can use |
|---|
| 100 | <a href="commands.html#showMessage">showMessage</a>, mapped by default to Alt |
|---|
| 101 | M, to have another look at the error message later. |
|---|
| 102 | |
|---|
| 103 | <p> |
|---|
| 104 | Parser 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 |
|---|
| 108 | when it succeeds in updating the tree. |
|---|
| 109 | |
|---|
| 110 | <p> |
|---|
| 111 | The 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> |
|---|
