Pages: 1
Author Topic: 5.1: Why Can Some Nested Required Elements be Deleted?  (Read 3436 times)

Posts: 2

« on: February 01, 2010, 06:44:21 PM »

We're using XMetaL 5.1 and we've specified in our DTDs that some nested element structures are required that were previously optional (DITA 1.1). 


For instance, in Topics, we've specified that:
1. Exactly one <prolog> element is required.
2. Within <prolog>, one or more <metadata> elements are required.
3. Within <metadata>, one or more <keywords> elements are required.
4. Within <keywords>, one or more <indexterm> elements are required.

So, basically, each topic requires, at a minimum, this structure after the <title> element:

The DTD logic I applied was the "+" symbol for each of the "one or more" instances.


When I create a topic in XMetaL using the updated RLX files and DTDs (yes, I've made sure they are regenerated and match), The topic is only valid when saving if I have the above structure in it.  However, unlike other areas where XMetaL prevents me, the user, from deleting an element that would invalidate the topic, in the nested case I've presented above, it allows me to delete the indexterm element entirely.  However, when I attempt to save the document, I receive the validation error message that is expected.

Why doesn't XMetaL prevent the user from deleting a nested required element if it would result in an invalid file?  It appears this behavior is inconsistent and I'm not sure how to successfully modify it.
Derek Read
Program Manager (XMetaL)

Posts: 2621

« Reply #1 on: February 01, 2010, 08:40:23 PM »

I'm assuming you have created a specialized DITA DTD, but that seems to be beside the point. I will concentrate on your main complaint which is that the product is letting you remove required elements.

This is expected behavior. See the topic in XMetaL Author's help called 'Validation and rules checking'. There are subtle differences between the two functions, with the main points being:

Validation checks to see if the markup is correct and complete with reference to your DTD or Schema. Rules checking ensures that you do not break the required structure as you edit your document by allowing you to insert only valid elements.

Validation occurs automatically when you save your document or when you switch from Plain Text view to Normal or Tags On view.

Rules checking is less stringent than validation in that it checks that no errors have been made, but does not check that the markup is complete.

XMetaL Author will allow you to delete markup that is required, starting from the bottom up (end of document back toward the beginning) because in many cases it is possible to have what amounts to a "branch" in a DTD or Schema.

The functionality that controls element insertion is the "Rules checking" feature. Unless additional business logic making parts of a document non-removable has been coded (which is not something we can do for DITA, because different clients have different needs) it will always be possible to keep deleting parts of a document until there is nothing left. This allows an author to back up if necessary.

One simple example with a DTD containing this definition <!ELEMENT a (b,c)>. If you have the XML <a><b/><c/></a> XMetaL will not allow you to remove <b/> until you remove <c/>. However, you can also remove all of <a>...</a> at any time in this case, and you can remove <b/> after you remove <c/>.

Another example, for a DTD where a child element must be followed by one of two of its siblings, like so: <!ELEMENT a (b, (c | d))>.
In this case <b> MUST be followed by one of either <c> or <d>. If you insert <c> and then later you decide you actually wanted <d> instead, XMetaL allows you to remove <c> so you can insert <d>.

A more extreme example (which applies for all DTDs) is that if you decided you do not wish to use <a> as your root element (same DTD as above) but instead restart this document using <b>, <c> or <d>. XMetaL allows you to back up to the point where your document is empty and do that. So, the simplest case: press Ctrl+A then delete (in any document). In this case the Element List shows all elements defined in the document because any of them are allowed to be the root (see XML Recommendation). I would call the resulting document (one that starts with an element not typically considered the "root" element) a "partial document". Such a document is typically included inside another larger "main" document at some point (often during post processing or a transformation of some kind). Of course, once you pick a root element and insert it, Rules Checking kicks in and the Element List contracts to show a smaller list of allowed elements.

Hope this makes sense and that I have not confused things further with too many examples.

Unfortunately, this means you may need to train some users if they are working with complex content (and in your case you have modified the DTD so you possibly cannot just refer them to the DITA Language Spec but might need some additional docs of your own creation). However, we provide two tools that may help in addition to the Validation Log:
1. The Element List. This window shows only those elements valid at a particular location (current position) in the current document. When one of the elements is required, and that required element is the only possible required element, it is listed in bold.
2. The Alt+F1 help feature (specifically for our standard DITA customization only) that opens the 'DITA Language Specification' to the definition for the current element. This includes a description of the intended usage, a listing of parent elements the element may appear in, child elements allowed and attributes.
« Last Edit: February 02, 2010, 01:23:55 AM by Derek Read » Logged

Posts: 2

« Reply #2 on: February 02, 2010, 11:22:09 AM »

This is perfect - thank you. Ideally, we would have been able to enforce the desired behavior, but explaining the reasoning behind the current behavior is just as good.

Yes, we are using a slightly modified DTD for our DITA.  We've essentially restricted the behaviors down to match our editorial guidelines without adding additional specialization (where possible). That all topics require one or more indexterms is one such example.
Pages: 1
Jump to:  

email us