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

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 <bob.thomas@tagsmiths.com>
Date: Tuesday, August 14, 2018 at 10:16 AM
To: Scott Hudson <scott.hudson@jeppesen.com>
Cc: "dita@lists.oasis-open.org" <dita@lists.oasis-open.org>
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 <scott.hudson@jeppesen.com> 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 (bob.thomas@tagsmiths.com) or Skype

Time zone: Mountain (GMT-7)

dita message