The raw declarations in your schemas are very useful for parsers processing your document, but are rarely sufficient for other humans who need to read and make sense of your schema. Adding notes helps those who use and maintain your schema to understand the hows and whys of your schema designs, and can be a critical tool for keeping groups of developers working on the same or related schemas in sync. Comments provide a working description of your schema while it is in development that can later be used as a foundation for more formal documentation efforts.
XML Authority's Notes provide a more sophisticated set of commenting tools than those available in XML 1.0, though it builds on existing facilities. XML Authority provides multiple levels of comments, supporting comments for the schema as a whole in addition to comments for specific declarations. XML Authority's Notes pane can interact with the other panes, changing its content to reflect the declaration currently being edited. It differentiates Schema Notes (which provide information for fellow schema designers) from Usage Notes (intended for authors creating documents with the schema), and provides automated change tracking if desired.
The Notes pane displays notes for the currently selected declaration by default. You can open the Notes pane from the View menu or by pressing Ctrl-7. Figure A shows how the Notes pane might appear with a schema describing a paragraph structure:
Figure A - The Notes Pane showing information about a particular declaration
NOTE: The Notes Pane in a SOX schema is marked by slightly different tags. See Creating and Editing Sox Schemas for more information.
The All Notes tab of the Notes pane lets you see all of the notes for a particular declaration at once. You can't edit them, however - you must make changes in the Schema Notes or Usage Notes tabs. To modify or view the schema notes for this declaration, click on the Schema Notes tab to bring up the view shown below in Figure B.
Figure B - The Notes Pane's Schema Notes tab lets you edit information meant for other schema developers.
Similarly, to view or modify the Usage Notes (meant for authors or developers creating documents based on this schema), click the Usage Notes tab to bring up the view shown in Figure C.
Figure C - The Notes Pane's Usage Notes tab lets you edit information meant for people creating documents based on your schema.
Comments in the Change Notes tab can't be changed. XML Authority will generate them automatically.
The Source Preview tab isn't really a note at all, but lets you see the actual schema source for the current declaration.
You can move between notes for your declaration and notes for your schema as a whole by clicking on the 'Show Document' option at the top right of the Notes pane, as shown below in Figure D.
Figure D - The Notes pane 'Show Document' option lets you switch between viewing the comments for your declaration and the comments for your entire schema.
When you open the notes for your schema, the tabs will change and the 'All Notes' tab for the schema will be highlighted, as shown below in Figure E. Like the All Notes tab in the declarations pane, you can't edit the notes displayed here. You must go to the Schema Notes or Usage Notes tabs to make changes.
Figure E - Displaying all of the notes describing the schema
Like the Schema Notes tab for declarations, the Schema Notes tab for the entire document is meant to contain information for fellow schema designers, not users. This information can be edited. Typically, you'll want to describe the schema as a whole and its relation to any other schemas or processing software it must work with. Figure F shows a typical Schema Notes entry for a small schema.
Figure F - Displaying the schema notes for the entire schema
Similarly, the Usage Notes tab provides a space for comments directed at those who will be using the schema to create documents that conform to its declarations, and is a good place to put an introduction, as shown in Figure G. This information is editable.
Figure G - Displaying the usage notes for the entire schema
The Version History tab is explained in Tracking Versions for Your Schema.
XML Authority keeps track of the many different kinds of information it stores in notes using a few conventions for comments. By opening the Source pane, you can see the fairly simple format that XML Authority uses to separate different kinds of notes, as shown in Figure H.
Figure H - XML Authority uses some simple conventions to identify different types of notes and the declarations (or schema) they describe.
Comments always immediately precede their target. For example, the notes for the schema appear before the body of the schema, and the notes for individual declarations appear immediately before the declaration. Schema Notes are prefixed with "#AUTHOR", while Usage Notes are prefixed with "#USAGE". Version information is always prefixed with "#CHANGES". As long as you maintain these prefixes, you can modify the notes in your schema directly and have them appear properly in the Notes pane.
Copyright 2000 Extensibility, Inc.
Suite 250, 200 Franklin Street, Chapel Hill, North Carolina 27516