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 DevelopmentJeppesen, A Boeing Company
303-328-6228 | Cell: 303-350-7934
Â
Â
This document contains only administrative, uncontrolled data under U.S. International Traffic in Arms Regulations.
Â
