Re: [dita] Groups - Proposal 13102, Stage 2 Release Management (PDF) uploaded

[Eliot Kimber <ekimber@rsicms.com>]

I think it would be a misuse of <foreign> to use it merely to get around the
lack of block elements within <data>.

If we think block elements should be allowed in <data> we should expand the
scope of my proposal 13044, basic-ph in <data> to include at least <p>,
<ul>, <ol>, <sl>, <div>, and <note>, if not also <fig> and <table>, and
<image>. There is an argument to be made that we should not restrict, at the
base level, the content model of <data> because who are we to say what it is
reasonable for metadata and what is not? In this case, as Nancy points out
correctly, I think, a change comment could be quite involved, but it is also
clearly semantically metadata about the thing changed, not content (in the
rhetorical sense) of the thing changed.

On the other hand, if the primary use case is to generate either typical
change lists (e.g., "list of effective pages" and whatnot) or things like
change tracking spreadsheets, allowing block content would complicate both
of those, where otherwise they would be relatively straightforward to
implement.

Because the change descriptions are metadata applied to the topic or map,
they must go in <prolog> or <topicmeta>, which pretty much limits your
specialization options to <metadata> and <data>. I suggested using
<metadata> as the base for <change-historylist> so that it could only go in
<prolog> or <topicmeta>.

The alternative would be to define new base element types so that there
would be no pre-existing content model constraints.

Cheers,

Eliot

On 8/23/13 11:10 PM, "Nancy Harrison" <nharrison@infobridge-solutions.com>
wrote:

> Hi Tom,
> 
> Thanks for the new submission.  I do have one comment.   I notice that the
> <change-summary> element is specialized from <data>   As someone who's written
> lots of release notes in my time, I can say that some release notes are
> significantly more complex than the ones in your examples, and more complex
> than is allowed within any of data's child elements, with the exception of
> <foreign>/<desc> (which allows 'p' and 'note').  Is that what you had in mind
> for anyone needing a long, complex release note? 
> 
> If so, I'd suggest creating an element - maybe 'change-long-summary'? - 
> specializing off foreign (and perhaps only allowing <desc>), so there's an
> element within change-summary that will guide an author in creating a long
> release note description.
> 
> This would mean altering the
> <!ENTITY % change-summary.content "(%data.cnt;)*">
> to 
> <!ENTITY % change-summary.content "(%data.cnt;)* | %change-long-summary.cnt;">
> 
> And adding a change-long-summary element such as:
> 
> <!-- Long Name: Change Long Summary
>      container for a long or complex release note description that requires
> the inclusion of one or more block elements
>   -->
> <!ENTITY % change-long-summary.content
>  "(%desc.cnt;)*"
>> 
> <!ENTITY % change-long-summary.attributes
>       '%changehistory.data.atts;
>  name 
>           CDATA 
>                     "change-long-summary"
> '
>> 
> <!ELEMENT change-long-summary %change-long-summary.content; >
> <!ATTLIST change-long-summary %change-long-summary.attributes; >
> 
> with the following class attribute:
> 
> <!ATTLIST change-long summary           %global-atts;
>     class CDATA "- topic/foreign rm-d/change-long-summary ">
> 
> 
> If you don't create a specific long-summary specialization, then the
> documentation for change-summary will need to note that if someone has to
> create a complex summary, they can use foreign/desc to do it.  Most authors
> don't use foreign as a general rule, and might not be familiar with its
> content model, and its name doesn't sound like something you'd put a summary
> in. 
> 
> Nice job on the general structure.
> 
> Regards,
> Nancy
> 
> 
> 
> On Fri, Aug 23, 2013 at 1:33 PM, Tom Cihak <r65612@freescale.com> wrote:
>>         Submitter's message
>>  PDF version of release management stage 2 proposal
>> -- Tom Cihak  
>>   Document Name: Proposal 13102, Stage 2 Release Management (PDF)
>> 
<https://www.oasis-open.org/apps/org/workgroup/dita/document.php?document_id=>>
5
>> 0423> 
>>  
>> 
>>  Description
>>  Proposal 13102, Stage 2 Release Management PDF
>>  Download Latest Revision
>> 
<https://www.oasis-open.org/apps/org/workgroup/dita/download.php/50423/latest>>
/
>> proposal_13102_release_management_Stage2.pdf>
>>  Public Download Link
>> 
<https://www.oasis-open.org/committees/document.php?document_id=50423&wg_abbr>>
e
>> v=dita> 
>>         
>> 
>>  Submitter: Tom Cihak
>>  Group: OASIS Darwin Information Typing Architecture (DITA) TC
>>  Folder: Drafts
>>  Date submitted: 2013-08-23 13:33:50
>>  
>>   
> 
> 

-- 
Eliot Kimber
Senior Solutions Architect, RSI Content Solutions
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368
www.rsicms.com
www.rsuitecms.com
Book: DITA For Practitioners, from XML Press,
http://xmlpress.net/publications/dita/practitioners-1/