OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


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


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)

Description
Proposal 13102, Stage 2 Release Management PDF
Download Latest Revision
Public Download Link

Submitter: Tom Cihak
Group: OASIS Darwin Information Typing Architecture (DITA) TC
Folder: Drafts
Date submitted: 2013-08-23 13:33:50




--
_____________
Nancy Harrison
Infobridge Solutions 
nharrison@infobridge-solutions.com


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]