| 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 | XmlMode.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 | <p> |
|---|
| 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 | The tree is refreshed automatically by the idle thread when you make changes to |
|---|
| 80 | the buffer. |
|---|
| 81 | <p> |
|---|
| 82 | You can also use <a href="commands.html#xmlParseBuffer">xmlParseBuffer</a>, |
|---|
| 83 | mapped by default to Ctrl P, to force the tree to be refreshed. The parser uses |
|---|
| 84 | the image of the buffer in memory, rather than the file on disk, so there's no |
|---|
| 85 | need to save any changes you've made to the buffer before refreshing the tree. |
|---|
| 86 | <p> |
|---|
| 87 | If <a href="commands.html#xmlParseBuffer">xmlParseBuffer</a> encounters an |
|---|
| 88 | error, the tree is not updated. Instead, a message box displays the parser's |
|---|
| 89 | error message, and the caret is moved to the location of the error in the edit |
|---|
| 90 | buffer (as reported by the parser). You can use |
|---|
| 91 | <a href="commands.html#showMessage">showMessage</a>, mapped by default to Alt |
|---|
| 92 | M, to have another look at the error message later. |
|---|
| 93 | <p> |
|---|
| 94 | Parser errors that occur when j is automatically refreshing the tree are not reported. |
|---|
| 95 | <p> |
|---|
| 96 | <a href="commands.html#xmlParseBuffer">xmlParseBuffer</a> invokes |
|---|
| 97 | <a href="commands.html#xmlFindCurrentNode">xmlFindCurrentNode</a> automatically |
|---|
| 98 | when it succeeds in updating the tree. |
|---|
| 99 | <p> |
|---|
| 100 | The following commands are also specifically relevant in XML mode: |
|---|
| 101 | <ul> |
|---|
| 102 | <li><a href="commands.html#xmlElectricEquals">xmlElectricEquals</a></li> |
|---|
| 103 | <li><a href="commands.html#xmlFindMatch">xmlFindMatch</a></li> |
|---|
| 104 | <li><a href="commands.html#xmlInsertEmptyElementTag">xmlInsertEmptyElementTag</a></li> |
|---|
| 105 | <li><a href="commands.html#xmlInsertTag">xmlInsertTag</a></li> |
|---|
| 106 | </ul> |
|---|
| 107 | </body> |
|---|
| 108 | </html> |
|---|
