Techniques for debugging EDDs?, etc.

[Lynne A. Price]

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
      <TEXT>, (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:
      (<TEXT> | 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 <TEXT>, 
>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 <TEXT> in the 
>more complex contexts in which the ordered list element is used. However, 
>for the simple contexts, not permitting <TEXT> would mandate a Para 
>element for every ordered list element, which would be tiresome (i.e. you 
>would not be able to create a new list element just be pressing Return, 
>which is what you want in simple lists).
>
>I think what I'm asking is what rules of thumb you would use for the use 
>of <TEXT> versus a Para element in this sort of situation.


Lynne A. Price
Text Structure Consulting, Inc.
Specializing in structured FrameMaker consulting, application development, 
and training
lprice at txstruct.com            http://www.txstruct.com
voice/fax: (510) 583-1505      cell phone: (510) 421-2284