dita message

Subject: Re: [dita] DITA 2.0 proposal: allow example in more contexts

From: "Robert D Anderson" <robander@us.ibm.com>
To: Scott Hudson <scott.hudson@jeppesen.com>
Date: Tue, 14 Aug 2018 12:02:37 -0500

Topics do not require examples at the end of the body (unless you've got a constraint in place). Here's the latest errata version of the DTD, but the only change here from DITA 1.0 is that <bodydiv> was added a couple releases ago:
https://github.com/oasis-tcs/dita/blob/master/doctypes/dtd/base/dtd/topic.mod#L375
<!ENTITY % body.content
"(%body.cnt; |
%bodydiv; |
%example; |
%section;)*">

So today - example can be the first thing in your body, followed by everything else.

The restriction only comes up in concept topics, where there was an explicit decision back in DITA 1.0 to put examples and sections at the end:
https://github.com/oasis-tcs/dita/blob/master/doctypes/dtd/technicalContent/dtd/concept.mod#L90
<!ENTITY % conbody.content
"((%body.cnt;)*,
(%section; |
%example; |
%conbodydiv;)*)">

I don't have a strong feeling about that restriction one way or the other, but I think it means the change here would be to update the <conbody> content model in concepts rather than <body> in topics.

Robert D. Anderson
DITA-OT lead and Co-editor DITA 1.3 specification
Marketing Services Center

E-mail: robander@us.ibm.com

11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA
IBM

Scott Hudson ---08/14/2018 10:55:21 AM---This may be a controversial proposal, but I've seen so many incidents of this need, that I'd like to

From: Scott Hudson <scott.hudson@jeppesen.com>
To: "dita@lists.oasis-open.org" <dita@lists.oasis-open.org>
Date: 08/14/2018 10:55 AM
Subject: [dita] DITA 2.0 proposal: allow example in more contexts
Sent by: <dita@lists.oasis-open.org>

This may be a controversial proposal, but I've seen so many incidents of this need, that I'd like to revisit this for DITA 2.0.

Use case:

The current structure of example requires the placement of examples at the end of a topic. In longer topics, this might place the example too far from the context to be useful. The existing structure is useful for formal examples that might be numbered or have a title.

Proposal:

By following the style of note, or perhaps even as a type of note, examples can be placed in many more contexts. In many use cases, a writer needs to provide a short example in the context of a paragraph or within a table entry.

We want to capture the semantics of any content that could be an example and minimize hard-coding of the "Example:" labeling.

Alternatively:
We could loosen the requirement that <section> and <example> must occur only at the end of the topic:

<!ENTITY % body.content

"((%body.cnt;)*,

(%section; |

%example; |

%bodydiv;)*)">
To:

<!ENTITY % body.cnt

"%basic.block; |

%data.elements.incl; |

%draft-comment; |

%foreign.unknown.incl; |

%required-cleanup; |
%section; |
%example; |
%bodydiv;">

Thanks and best regards,

--Scott

Voting member:
Boeing Data Standards Technical Advisory Board
OASIS DocBook TC (Secretary), Publishers SC (Chair)
OASIS DITA TC, Tech Comm SC, LwDITA SC, Learning Content SC (Secretary)
OASIS DITA Adoption TC
OASIS Augmented Reality in Information Products (ARIP) TC

Scott Hudson
Content Strategist, Digital Aviation Learning and Development
Jeppesen, A Boeing Company
55 Inverness Drive East
Englewood, CO 80112
303-328-6228 | Cell: 303-350-7934

This document contains only administrative, uncontrolled data under U.S. International Traffic in Arms Regulations.

References:
- DITA 2.0 proposal: allow example in more contexts
  - From: Scott Hudson <scott.hudson@jeppesen.com>


E-mail: robander@us.ibm.com 11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA

	<!ENTITY % body.content
	"((%body.cnt;)*,
	(%section; \|
	%example; \|
	%bodydiv;)*)">

<!ENTITY % body.cnt
	"%basic.block; \|
	%data.elements.incl; \|
	%draft-comment; \|
	%foreign.unknown.incl; \|
	%required-cleanup; \| %section; \| %example; \| %bodydiv;">