Consider jEdit as an open source/free tool to use for the lessons

[libcce]

Per some initial research by @catsmith she recommends jEdit after discussing other tools such as oXygen, XML Spy, Netbeans and an extension in Atom. @catsmith can you add your thoughts/research here. Thanks!

[catsmith]

I looked at Atom as was suggested at the last meeting however a lot of the XML plugins are no longer supported and I was not able to get any of them to work. I did a bit of googling and came across jEdit as a cross platform open source solution and I am finding it pretty good. It is easy to install as are the two required plugins and it does everything I look for:

• Syntax highlighting
• Closing tag completion
• Correct indenting of a file
• Well-formed checks
• Validation against a schema
• XPath searches
• XSLT conversions.

There is no automatic check for well-formedness which is a bit of a shame but it is not difficult to initiate.

[catsmith]

I am uploading my working documentation on jEdit for XML. I will complete if in the next week or two. I thought I would upload the start of it so that if anyone wants to experiment you can see what I am suggesting to use.

[catsmith]

Using jEdit to work with XML

jEdit is free, open source software with specific plugins that support working with XML. Many other options, both free and paid, are available but jEdit works on all operating systems and has good support for editing, validating, transforming and searching XML.

Installation

jEdit requires Java to run. If you are on windows or mac then Java should already be available. If you use linux then you may need to install a Java runtime environment. Details of how to do this are available on the jEdit compatibility page http://www.jedit.org/index.php?page=compatibility

jEdit

jEdit can be downloaded from www.jedit.org. The link to the download page is in the top right corner. Download the appropriate installer for your operating system from the top section of the download page title ‘Option 1 – manual download’. You will be redirected to a sourceforge page but the download should start also automatically after a few seconds.

Install the downloaded file in the normal way for your operating system.

XML related plugins

Once you have installed jEdit there are a few additional plugins that need installing to add the functionality for working with XML.

• Open jEdit.
• Click on 'plugins' in the menu bar and then select 'plugin manager' from the drop down menu.
• Click on the 'install' tab.
• Type 'XML' into the search box to reduce the number of plugins in the list and then scroll to the bottom of the list.
• Check the boxes next to the two packages 'XML' and 'XSLT'. Any dependencies required will also be selected so don't worry if lots more boxes are ticked when you select these.
• Click install.

If the plugins have installed when you click the 'Plugins' dropdown menu will include the new plugins.

Some useful but not essential configurations

By default the plugins that you have just installed will appear in floating windows which can sometimes be difficult to work with. To make things easier you can dock them in the main jEdit window.

• Click on 'Utilities' in the menu bar
• Select 'Global Options' from the drop down menu
• Under jEdit in the left hand bar of the Global Options window select 'Docking'
• For the windows 'Sidekick', 'XPath Tool' and 'XSLT Processor' which are the three windows we will use in this tutorial select a position for them to dock from the menu to their right.
• The image below shows the three windows docked on the left along with the File Browser window which is there by default
• You can have a look at all of the different options and find out what works best for you

Using Jedit for XML

These notes are not intended to be exaustive but rather be just enough to get you started. Full instructions are provided for the XML plugin by the authors themselves here: http://plugins.jedit.org/plugindoc/XML/. General jEdit documentation is available on the jEdit website here: http://www.jedit.org/users-guide/index.html

Creating and Editing files

These are just a few notes on creating and editing XML files in jEdit.

When you open an XML file or start creating one jEdit should automatically colour the tags and attributes. For larger files you will get a message to give you different display options because of the memory required for highlighting. You will just need to experiment and find the best options for your larger files.

When you are typing in XML if you start to type a closing tag with '</' then jEdit will complete it with the tag name of the currently opened tag.

The encoding of files can be detected automatically if they are correctly encoded in your XML but defaults are set using your operating system standards. If you use unicode files or any other encoding which is not the native encoding of your operating system and would like to change the default encoding used by jEdit you can do so.

• Click on 'Utilities' in the menu bar
• Select 'Global Options' from the drop down menu
• Under jEdit in the left hand bar of the Global Options window select 'Encodings'
• Select the default character encoding you want to use from the drop down menu
• Click 'Apply' at the bottom of the window

Testing for Well-formed XML

Well-formed XML follows all of the rules of XML. These include:

• having a single root element
• using the correct rules for naming elements and attributes (such as not starting an element name with a number and not using spaces)
• closing all open tags
• appropriately nesting tags

Most processors will only be able to handle XML that is well-formed so it is important to check this.

You can check the well-formedness of the open file in a few ways:

From the menu

• Click the 'Plugins' option from the menu bar
• In the drop down menu select 'XML'
• From the second dropdown menu select 'Parse as XML'

From the sidekick window

• Click on the button in the top left corner which looks like this

In both cases any errors will appear in the 'Error List' window. You can either dock this following the instructions above or leave it as a floating window. It should pop up in front of any other windows if there are errors regardless of whether you dock it or not.

Clicking on any error will take you to the line in the file which triggered the error. If the error is a missing closing tag then you will be taken to the point of the document which is the last point the element could have been closed without causing problems with nesting so the opening tag might be much earlier in the document.

One of the slightly annoying things about jEdit as compared to some other (paid for) XML editors is that XML files are not checked well-formedness automatically: you always have to explicitly ask it to check the file. You should get into the habit of doing this regularly because the earlier you find out there is a problem the more likely you are to remember what you changed.

Validating against a schema

XSLT transformations

Xpath searching

[catsmith]

I should also add I didn't look at either netbeans or eclipse as I felt they might be a bit too complex for just XML unless we didn't have a simpler option.

Also I will probably continue to use Oxygen since I am happy to buy a license but we should not require that for a carpentry course.

The functions I use regularly in Oxygen are matched in my jEdit setup but not in quite the same integrated way. For example, files must be explicity reparsed to check for well-formedness and for schema validation and the results of xpath searches are not linked back to the source document.

[PhilReedData]

jEdit looks good here, I agree @catsmith that it is much lighter than NetBeans so much better for beginners.

I'm not an expert in Oxygen at all, I wonder how similar its processes and functions are. Could we write lessons using jEdit in such a way that a future team could substitute/fork to use Oxygen? (I mean, outside of an official Carpentries capacity.)

[catsmith]

Here is an updated version of the instructions for installing jEdit and XML. I found a saxon plugin which adds extra features to the xpath editor and makes it a much more viable way of searching documents. Spacing on PDF is strange because I haven't found a good markdown converter yet.

Jedit_for_XML.pdf