dita — archive

DITA 2.0 proposal: allow example in more contexts

From: Scott Hudson <[email protected]>
To: [email protected]
Date: Tue, 14 Aug 2018 16:19:00 -0000

Indeed, which is why my first suggestion was to use something akin to <note>. It may still be useful to have a formal <title>, so perhaps something akin to <fig> is more appropriate? Thanks, --Scott From: Bob Thomas <[email protected]> Date: Tuesday, August 14, 2018 at 10:16 AM To: Scott Hudson <[email protected]> Cc: "[email protected]" <[email protected]> Subject: Re: [dita] DITA 2.0 proposal: allow example in more contexts Hi Scott, One immediate problem I can see is an increase in processor complexity. One way to look at the current model is that body.cnt can be regarded as an implicit section without a container that only optionally occurs at the beginning of body. Under your proposal, processors would have to make this inference throughout the body content model with blocks now being interspersed between sections. Perhaps what you really want is a block-level example element. Best regards, Bob On Tue, Aug 14, 2018 at 9:54 AM, Scott Hudson < [email protected] > wrote: 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. -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( [email protected] ) or Skype Time zone: Mountain (GMT-7)