RE: [docbook-tc] proposed result element

["Rowland, Larry" <larry.rowland@hp.com>]

Comments inline, with LRR>> prefix.

-----Original Message-----
From: Bob Stayton [mailto:bobs@sagehill.net] 
Sent: Wednesday, February 23, 2011 11:36 AM
To: DocBook Technical Committee
Subject: [docbook-tc] proposed result element

I reviewed Larry's proposal for a result element, and would like to initiate an email 
discussion.  I think the proposal is fine, and I have some comments.

1.  I think formal elements should be included in the content model of result.  I 
could easily see cases where a result would contain a table or figure that is 
significant enough to be cross referenced to from elsewhere in the document.

LRR>> I have been thinking it over and think you are correct.  I was trying to avoid
      chopping things up too much but have decided the formal elements should be
      allowed since results can be quite complex.

      I am also beginning to wonder if structure might be necessary, but I can't figure
      out a content model that makes sense and includes it.

2.  Do we need to specify that placement of result is at the end of procedure or step? 
That seems to be a presentational feature.  I could see authoring the result at the 
beginning and then writing the steps to get to that result. Some presentation styles 
may use that order as well.

LRR>> I think of the result as providing confirmation of successful completion of a
      step, series of steps, or procedure, which would make it follow what causes it.
      However, I can also see it as presenting a desired state followed by the actions
      to reach that state.  I frequently have a para preceding a procedure that tells
      why you want to do it, but I don't consider that the result, and it usually is
      not nearly as detailed as the result.

3.  I think we should allow multiple sibling result elements. In addition to Larry's 
use case to handle different procedure outcomes using a class attribute, authors may 
need to use profiling to select different results for different document conditions. 
Allowing multiple result elements makes such profiling easier.

LRR>> Agreed.  Good catch.

4.  If we include a class attribute for result, do we handle it like other class 
attributes, with an enumerated list and an "otherclass" attribute?

LRR>> It is not clear to me whether this would be an enumerated type or more like
      the role attribute.  If it is enumerated, I think it would definitely need 
      an otherclass attribute.


Thanks for kicking off the discussion.

Regards,
Larry Rowland


=======================================================================
[ Larry Rowland             | If you want to build a ship, don't drum ]  
[ ESS/ATG                   | up the men to gather the wood, divide   ]
[ Hewlett-Packard           | the work, and give orders. Instead,     ]
[ 3404 East Harmony Road    | teach them to yearn for the vast and    ]
[ Fort Collins, CO  80528   | endless sea. - Antoine de Saint Exupery ]
[ Phone: 970/898-2280       +-----------------------------------------]
[ E-Mail:larry.rowland@.hp.com                                        ]
=======================================================================