[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [dita] Stage one proposal: Allow <example> in same locations as <div>
|
More thoughts on example before I get distracted by life and forget to respond.
Why I might want to tag something for example:
Some big long block that I want to title "Example: Do the thing" or provide special formatting (different background color, box, maybe even off into a sidebar).
Sometimes, these blocks are big and could almost be topics unto themselves.
Sometimes, these blocks are smaller, and I want them closely associated with surrounding content. This is a case where I'd like to be able to have the ability to use <example> in more places. Often with concept-like content describing how something works, I
may have a small example as part of the flow of the content. I will have related text before it and related text after it. I don't like having to work around an artificial construction of <section with title><example><section> just to make my content work
in my DITA. (And if I want to reuse it, it's harder.)
I can see uses for small example content/snippets in lists and tables. These probably don't need titles, but I might want to highlight them in some way.
Potentially, if it were an option, to be able to tag inline with <userinput> or <codeph/block>, where the example content is. A lot of users cut and paste code samples/command-line stuff out of the doc. Being able to easily show the difference between "these
are the commands you should run" vs. "this is my example file name or property value" could be useful. (Potentially for accessibility as well). Sometimes I do that with <varname>, but that's not always semantically correct. I don't always want to flag the
whole command as <example>.
I don't feel that I need to mark everything that has "for example" in it.
ZoÃ
From: dita@lists.oasis-open.org <dita@lists.oasis-open.org> on behalf of Eliot Kimber <ekimber@contrext.com>
Sent: Monday, June 10, 2019 7:49 PM To: dita@lists.oasis-open.org Subject: Re: [dita] Stage one proposal: Allow <example> in same locations as <div> Example is currently defined a being logically a specialization of <section> ("The <example> element is a section...") and thus can really only be allowed where <section> is allowed. Also, in the base topic definition, <example>, like
<section>, is allowed anywhere within <body> (meaning you can mix <section> with other things in generic topics). Also in <refbody>. However, <conbody> is more restrictive (see below).
For 2.0 it would make sense to have <example> be specialized from <section> (and maybe moved into the software domain or maybe into a new "example" domain.) That would allow <example> to take <sectiondiv> (it can already take <div> by way of basic.block) and would also explicitly express what the prose of the spec already says ("example is-a section"). I think the issue Scott is referring to is that in concept <example> can only occur as a peer to <section> and must follow any non-section content of <body>, which means it can't be mixed with other elements, as it can in topic/body. The only solution I can see to that that doesn't involve relaxing the content model of <conbody> is to define a new element, i.e., <examplediv>, that carries the "this is an example" semantic but is allowed wherever <div> is allowed, including within itself. Cheers, E. -- Eliot Kimber http://contrext.com ïOn 6/10/19, 7:05 PM, "Scott Hudson" <dita@lists.oasis-open.org on behalf of scott.hudson@jeppesen.com> wrote: The content model for example is much too restrictive, limiting how and where content can be semantically marked as exemplary content. As a result, writers often hardcode paragraphs with "For example:â" or other non-semantic constructions. By allowing <example> in more places, content can be properly tagged with the <example> semantic. If there are too many models to change, we could also allow <example> within <div>. 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 Technology Strategist Information and Knowledge Services _____________________________________ Jeppesen A Boeing Company ph: 303.328.6228 | Mobile : 303.350.7934 | scott.hudson@jeppesen.com 55 Inverness Drive East | Englewood, CO 80112 | www.jeppesen.com <http://www.jeppesen.com/> This document contains only administrative, uncontrolled data under U.S. International Traffic in Arms Regulations. --------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]