General XMetaL Discussion

XMetaL Community Forum General XMetaL Discussion Documenting a DTD / W3C Schema for Users of XMetaL Author

  • Derek Read

    Documenting a DTD / W3C Schema for Users of XMetaL Author

    Participants 0
    Replies 1
    Last Activity 13 years, 1 month ago

    Background:
    Creating XML documents to comply to a specific XML document type (schema) is aided in large part by simply using an XML authoring tool such as XMetaL Author. The use of features like the Element List and Attribute Inspector in XMetaL Author help authors know when a particular element or attribute value is allowed in any given context.

    What an XML authoring tool cannot do automatically is describe the proper usage of a particular element or help the user know when to use one element over another in any particular context. These can be industry standard guidelines, corporate business rules, or perhaps something else.

    When a schema is written the creator of that schema has a specific purpose in mind for each element and attribute value. These are sometimes documented in the schema itself (as comments or descriptions). In some cases more detailed documentation is already available, or a company may write their own.

    You could package up this documentation in various ways: make it available on an intranet site, via printed PDF, via a wiki, or point users to a particular website (for standards), etc. In some cases it might be nice to provide each user with their own specific copy of this documentation, particularly when it is for internal use, and make this accessible directly from within XMetaL Author. Even better, perhaps it would be nice to provide a function that lets the author ask for help on a specific element while they are editing.

    One Solution:
    The example included here is a simple customization for a DTD called “simple.dtd” (a very simple demo DTD that defines 5 elements and to keep things simple, no attributes). The main purpose of this demo is to show how to provide context sensitive help for a particular schema, so the most relevant parts of the customization are the MCR file and CHM file. There really is no magic to this. This solution consists of a couple of simple macros and a (slightly special) CHM file.

    Limitations
    In order for this particular feature to work an element must already exist within the document. This is because the name of the element is used as the context for providing that help. However, because the CHM file is available and users are free to browse it this is not much of a limitation, provided the CHM file is nicely formatted (meaning that it has a proper index, search, relevant linking between topics, etc).

    Audience:
    This demo is meant for XMetaL Author customizers and partners to use as a sample to work from (or to inspire them) when building their own solution for providing context sensitive help for a particular schema.

    Macro File:
    This file defines two macros:

    • A script that runs when the user presses Alt+F1. It checks the name of the current element (the element the author's cursor is currently within) and then displays help for that element inside a CHM file. See attached screen capture “elementHelpCHMFile.gif”. The main trick here is that the name of the element is used to build a path to locate the topic inside the CHM. The easiest way to do that is to save the HTML file for each relevant topic using .html as the filename.
    • A script that adds the same functionality to the right click (or Shift+10) context menu. See attached screen capture “elementHelpContextMenu.gif”.

    CHM File:
    The CHM file was generated using XMetaL Author Enterprise via the integrated copy of the DITA Open Toolkit. The DITA source documents are included in dita_source_for_chm.zip. A copy of the compiled CHM is included with the actual demo in elementContextHelpDemo.zip so you don't need these DITA source files unless you want to use them as a basis for building your own CHM. The CHM file included in the demo was created to demonstrate primarily how to get a particular topic open. You might have a completely different preference for what such a file might actually contain and you may wish to use an completely different tool to generate such a CHM.

    Note also that three hand-coded HTML files are also included inside the CHM file that begin with “redirector_”. These demonstrate a method for pointing the Windows hh.exe application (what Windows uses to display CHM files) to a specific network or WWW resource. In this demo these pages take you to the W3C website.

    Warning:
    This is a demo. Use at your own risk. These files are not known to contain any malicious code but you may wish to examine them prior to loading the customization (which you will want to do anyway because that is the whole purpose of this demo).

    Installation:
    Download and unzip the attached elementContextHelpDemo.zip file into any empty folder on your machine.

    There aren't any installation steps beyond this because this customization has been written so that opening the XML document in XMetaL Author will locate and load it (DTD, CSS, CTM and MCR files) from the same folder (normally you would not do this but this is a demo). The CHM file should also be placed in the same folder as the DTD for this demo because an API is used to find it there (ActiveDocument.ResourceSet.Root). There are various other APIs that would allow you to place your CHM file in other locations if you prefer and still locate it (such as Application.Path, etc). If you package your customization into an XAC file and include the CHM in there as well then ActiveDocument.ResourceSet.Root can be used to find it as well.

    The Demo:
    1. Launch XMetaL Author or XMetaL Author Enterprise.
    2. Open test_document.xml then place the insertion point (cursor) within any element and either press Shift+10 (or the “Context Menu” button on a Windows keyboard) or right click. You will see something similar to the attached screen capture “elementHelpContextMenu.gif”.
    3. Select the last item in the context menu. This will open simple.chm and take you to the topic for the current element. You will see something similar to the attached screen capture “elementHelpCHMFile.gif”.

    Reply

    dcramer

    Reply to: Documenting a DTD / W3C Schema for Users of XMetaL Author

    If your DTD's documentation is online and the page names match the element names you can also write a macro to open a browser to the page:

    [code]var nd = Selection.ContainerNode;
    // For DITA Use: http://docs.oasis-open.org/dita/v1.1/OS/langspec/langref/
    openUrl(“http://docbook.org/tdg/en/html/” + nd.nodeName + “.html”);
    ]]>
    [/code]

    Then in On_Context_Menu add:

    [code]  Application.AppendMacro(“Entry for current element in &DocBook, The Definitive Guide…”,”DBTDG”);[/code]

    David

    Reply

  • You must be logged in to reply to this topic.

Lost Your Password?

Products
Downloads
Support