====== What are they for? ======

XMLEye can integrate with third-party converters to open non-XML formats, but it first needs to know how to identify these formats, what they're called, and what commands should be used to invoke our favorite editor and the converter.

**Document format descriptors** do just that.

====== How do I make one? ======

It's a simple XML file. Take for example the descriptor for YAML/JSON files, ''yaml.format'':

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<format xmlns="http://xmleye.uca.es/xmleye/accepted-doc">
  <name>YAML/JSON file</name>
  <name language="es">Fichero YAML/JSON</name>
  <edit_cmd>emacs %s</edit_cmd>
  <import_cmd>yaml2xml %s</import_cmd>
  <extensions>
    <extension>yaml</extension>
    <extension>yml</extension>
    <extension>json</extension>
  </extensions>
</format>
</code>

It follows the general philosophy of the FreeDesktop desktop files. First you have the usual XML declaration. After it, a root ''format'' element under the XMLEye document format descriptor namespace will include the following children:

  * one or more ''name'' elements, listing the string to be used in the file selector in the Open dialog. You can add a ''language'' attribute indicating the ISO 3166 country code and optionally also the ISO 639 language code, separated with a hyphen, like "en" or "en-US".
  * an ''edit_cmd'' with the command to be used for launching the editor. ''%s'' will be substituted here for the full path to the current document's source file.
  * optionally, an ''import_cmd'' detailing the command to be used to launch the converter. As before, ''%s'' will be replaced with the full path to the opened non-XML file. Its standard output will be used as the final input document to be browsed.
  * several ''extension'' elements inside an ''extensions'' element. This is how XMLEye can determine what format a specific file is opened as, even if you use the "All files" option in the file selector. Right now, XMLEye cannot use magic cookies or look in any way at the contents of the file itself to detect the format.

====== Customizing DFDs from the user interface ======

Check the "Accepted formats..." entry in the Preferences menu. You can change the name for the current locale, the editor and converter commands, and the extensions associated to it. Oh, and don't worry: you can always restore to the default settings using the Restore button. You can't add new formats this way yet, though.

This method has the advantage that it can be used in system-wide installations, like those used by Debian packages, without requiring root access.

====== Installation ======

Just copy the file to your format repository, and reopen XMLEye. The exact location will vary depending on what installation method you used: look in its wiki page for more details.