Re: Techniques for debugging EDDs?, etc.
Steve, I hope you don't mind my copying this to Framers--I suspect other people will be interested in this thread. I agree with you about reusing element tags in different contexts; doing so provides writers with a natural environment. People think about particular text as a title or a paragraph and not as a title-of-a-third-level-section or a paragraph-in-a-nested-list. I typically use a general rule such as , (Para | List)* for list items. Thus, in the frequent case in which the item consists only of text, there's no need to create a Para element (which is a nuisance even if auto-inserted because it affects FM's Return behavior and clutters up the Structure View). This rule prohibits text except at the beginning of an item. Note that this rule does allow an item to begin with a Para if the user prefers that approach. Of course, the XML counterpart of this rule is not valid. I use a technique that was suggested by someone on Framers (and I owe this person an apology for not recalling who it was). I put a second general rule in the EDD: ( | Para | List)* I use conditional text to show the first but hide the second when importing element definitions and the reverse when creating a DTD from the EDD. (In fact, I rarely manage the show/hide settings myself. I use the Reusable EDD Manager which keeps track of condition tags and importing element definitions into the appropriate files for me. If you'd like more information about this tool, we can make it the subject of a later message.) This dichotomy causes no problems if all editing is done within FM. The XML model, which allows text nodes between Para and List elements, is more permissive than the FM model. Thus, all content created within FM is valid within XML. If other XML editors are used and the writers are not conscientious about avoiding "loose" text after a Para or List, it's straightforward with XSLT to wrap such text in a Para before import back into FM. As far as formatting rules, nested lists are often much easier to support with hierarchical styles than with named paragraph formats. There are environments where you need named paragraph formats (for example, to support WebWorks or other follow-on processes that require named formats to distinguish context, or if you want to be able to import a different set of formats to change the appearance of a document). If a list is like a "regular" paragraph except that it is indented and the first paragraph in each item begins with a bullet, number, or other mark, then I use a text format rule in the list element to set the first and left indentation to the values used for continuation paragraphs within an item (the left indentation is usually correct for the first paragraph in the item as well). Note that if the extra indentation for each level of list is the same, then this text format rule can be an all-contexts rule. Then, in the rule for list items, I use a first-paragraph rule to outdent the first line in the item back to where the list mark should appear and to set an appropriate autonumber. Some people prefer to avoid hierarchical styles simply to avoid format overrides. I certainly agree that user-specified overrides should be avoided as much as possible. In the unstructured world, overrides to paragraph formats fall into this category. In structured documents, you can certainly strongly encourage writers to keep away from the paragraph and character designers (and their shortcut and menu equivalents), but there's no harm in letting the EDD tweak the formatting. In fact, hierarchical styles can result in a shorted EDD that is easier and hence quicker to maintain and debug. Regardless on whether you are using hierarchical styles or named formats, investigate how much of the necessary formatting you can specify in the rules for the list and item elements instead of those for paragraphs. Remember that formatting you specify for lists and items will apply to loose text in a list and be inherited by Para elements. By the way, since you've asked for my opinion, I'll share one of my pet peeves. I see no reason to abbreviate "Paragraph" in an environment in which the user does not need to type the entire element name. Hope this helps. --Lynne At 07:33 AM 7/13/2006, Steve Rickaby wrote: When designing the EDD, I tried to keep the number of elements as low as possible. For this reason, the ordered list element gets re-used in every context in which ordered lists occur, and it's one of these that appears to be causing the trouble. All my list elements have a child element ListItem, which permits , Para, and nested list elements. The Para element has a lot of context rules. The problem seems to be stemming from the ability to enter in the more complex contexts in which the ordered list element is used. However, for the simple contexts, not permitting would mandate a Para element for every ordered
Techniques for debugging EDDs?, etc.
Steve, I hope you don't mind my copying this to Framers--I suspect other people will be interested in this thread. I agree with you about reusing element tags in different contexts; doing so provides writers with a natural environment. People think about particular text as a title or a paragraph and not as a title-of-a-third-level-section or a paragraph-in-a-nested-list. I typically use a general rule such as , (Para | List)* for list items. Thus, in the frequent case in which the item consists only of text, there's no need to create a Para element (which is a nuisance even if auto-inserted because it affects FM's Return behavior and clutters up the Structure View). This rule prohibits text except at the beginning of an item. Note that this rule does allow an item to begin with a Para if the user prefers that approach. Of course, the XML counterpart of this rule is not valid. I use a technique that was suggested by someone on Framers (and I owe this person an apology for not recalling who it was). I put a second general rule in the EDD: ( | Para | List)* I use conditional text to show the first but hide the second when importing element definitions and the reverse when creating a DTD from the EDD. (In fact, I rarely manage the show/hide settings myself. I use the Reusable EDD Manager which keeps track of condition tags and importing element definitions into the appropriate files for me. If you'd like more information about this tool, we can make it the subject of a later message.) This dichotomy causes no problems if all editing is done within FM. The XML model, which allows text nodes between Para and List elements, is more permissive than the FM model. Thus, all content created within FM is valid within XML. If other XML editors are used and the writers are not conscientious about avoiding "loose" text after a Para or List, it's straightforward with XSLT to wrap such text in a Para before import back into FM. As far as formatting rules, nested lists are often much easier to support with hierarchical styles than with named paragraph formats. There are environments where you need named paragraph formats (for example, to support WebWorks or other follow-on processes that require named formats to distinguish context, or if you want to be able to import a different set of formats to change the appearance of a document). If a list is like a "regular" paragraph except that it is indented and the first paragraph in each item begins with a bullet, number, or other mark, then I use a text format rule in the list element to set the first and left indentation to the values used for continuation paragraphs within an item (the left indentation is usually correct for the first paragraph in the item as well). Note that if the extra indentation for each level of list is the same, then this text format rule can be an all-contexts rule. Then, in the rule for list items, I use a first-paragraph rule to outdent the first line in the item back to where the list mark should appear and to set an appropriate autonumber. Some people prefer to avoid hierarchical styles simply to avoid format overrides. I certainly agree that user-specified overrides should be avoided as much as possible. In the unstructured world, overrides to paragraph formats fall into this category. In structured documents, you can certainly strongly encourage writers to keep away from the paragraph and character designers (and their shortcut and menu equivalents), but there's no harm in letting the EDD tweak the formatting. In fact, hierarchical styles can result in a shorted EDD that is easier and hence quicker to maintain and debug. Regardless on whether you are using hierarchical styles or named formats, investigate how much of the necessary formatting you can specify in the rules for the list and item elements instead of those for paragraphs. Remember that formatting you specify for lists and items will apply to loose text in a list and be inherited by Para elements. By the way, since you've asked for my opinion, I'll share one of my pet peeves. I see no reason to abbreviate "Paragraph" in an environment in which the user does not need to type the entire element name. Hope this helps. --Lynne At 07:33 AM 7/13/2006, Steve Rickaby wrote: >When designing the EDD, I tried to keep the number of elements as low as >possible. For this reason, the ordered list element gets re-used in every >context in which ordered lists occur, and it's one of these that appears >to be causing the trouble. > >All my list elements have a child element ListItem, which permits , >Para, and nested list elements. The Para element has a lot of context rules. > >The problem seems to be stemming from the ability to enter in the >more complex contexts in which the ordered list element is used. However, >for the simple contexts, not permitting would mandate a Para >elem