https://lists.oasis-open.org/archives/dita/201906/msg00026.html (Hudson, 10 June 2019)
https://lists.oasis-open.org/archives/dita/201906/msg00027.html (Kimber, 10 June 2019)
https://lists.oasis-open.org/archives/dita/201906/msg00028.html (Eberlein, 10 June 2019)
Scott: One of the things I run into with my authors is the need to insert examples in different locations than the end of the document. They need something a little bit more block-oriented that can be used in more places. Examples are also useful in lists, sometimes tables, maybe as part of info in step, and maybe more. The current model is very limiting. I suggested div because it's allowed in many places, but more important is the ability to identify something as semantically an example in many more contexts. If it's too hard to maintain content-model wise maybe we could just add example to div.
Kris: I wish Eliot was here but since he isn't please open his email link.
Scott: Eliot suggested a new element examplediv. I'm not so much in favor of that if we could allow something that is already present as a block but remove some restrictions.
Kris: I think Eliot is saying example is currently logically a specialization of section, although not technically.
Robert: It's not a specialization, but in how it's defined in the spec it was always written that way. Definitely up through DITA 1.2 the grammar files said "For content model of example, use what's in section". I don't know whether it's that history that makes me blind here but it makes me cringe to think of example inside of div because I think of example as a large titled block. But does it need to be.
Tom: Eliot's suggestion would get around that
Robert: But then we have two elements for the same thing, something that we do a little grudgingly.
Tom: Do we have to hold our noses and change what example is?
Kris: That makes me feel wrong too. Scott I can understand wanting more semantic markup. Would we want to consider an example token (for @type) on note?
Stan: I support that, there are people doing that already on note with othertype.
Scott: For translation purposes I don't want it tied into an attribute
Zoe: One question I have is I've always wanted example in more places. In my brain section and example are the same thing. Having to put an example at the end of a topic is just weird. And what happens with stepxmp?
Kris: Scott you mentioned wanting to put example in info in tasks. That's what stepxmp is for.
Scott: Yeah I forgot that and we do use it.
Chris: If I were inventing example from scratch I'd model it more on figure than section.
Robert: Figure has a weird content model. Example is more free-flowing section content. Doing it with note feels "off". Doing it with examplediv seems "off".
Scott: We also need inline examples, so maybe we need a block one and an inline one.
Chris: Am I right that div is not titled
Robert: yes, and I definitely don't want to add a new titled element
Chris: given that we have an existing example element that is modeled after section what's the harm in adding it to more content models
Kris: The big problem is that if we make a titled element within section we'll give people the ability to do nesting that we didn't want
Chris: but an example within a section is a very common use case
Kris: I like the idea of a new untitled block element. Inline element makes me kind of queasy, though.
Chris: I'm not saying infinitely nested example. It's allowed within section. It's a one layer deep titled block. I suppose people could use it for 2nd level nesting, but the chances are low.
Robert: I think putting it in section is not going to give Scott what he wants. Then again you can also do that in figures. Nobody would think that's wise and your results might be garbage but you can do it. So that on its own isn't the reason to say we can't do that with example. We have titled things that you can make nested.
Tom: Aren't there both titled and untitled things.
Robert: There's no "best practice" in the spec. I don't think there's even a consistent best practice in usage.
Scott: What if we allowed example wherever figure and table are allowed. All that's doing is removing the restriction that when you use section or example, you're ONLY allowed to follow up with more of those.
Kris: You mean example as currently defined?
Scott: Yes. Even in a ref or refbody you have the same constraint.
Kris: I think we need to keep the focus not on concept/reference but on example as it works in topic. A lot of the things in regard to concept/reference really have to do with the content model of those.
Robert: It's just concept. In reference it's just like in topic: unless you have a constraint of your own you can use example more places. The restriction is that they can only be a child of body. Concept is the only one that has that restriction. It has confused poeple but that's tangent to this dicsucssion.
Zoe: I understand that constraints exist that it's supposed to be at the same level as section but I'm trying to think of where I'd use example and I'm getting lost. Do I want to tag "For example, blah" all the time? Sometimes I do but why does it have to be at the same level as a section? That hurts a lot of people's brains.
Scott: It makes it harder for reuse, too, because you wanted that example to stay with the section. You need two conrefs instead of one.
Robert: I think your core question is at what level is it wise/useful for people to mark up examples. If you have a sentence in the middle of a paragraph, you don't want to set that sentence as its own block, so maybe that's where Scott was thinking about an inline element. In my VERY limited experience that tends to be where you've got a codeblock and I wouldn't want people to change that to an example element.
Kris: In the spec we use otherprops=example on both some blocks and some inline phrases. We do that because have had requests to be able to filter out examples in the spec.
Robert: A lot of those we have that outputclass attribute on elements that have their own semantics.
Tom: Would blessing some kind of global attribute solve this whole problem?
Scott: the challenge would be what if we wanted a formal example mixed into the paragraph model.
Kris: Maybe we should step back and look at the requirements. I'm hearing the ability to clearly identify content that is an example, anywhere. Another one might be to generate some kind of styling or label. Am I missing any other use caes/requirements?
Scott: I think those are the main concerns. Semantic idenification and styling. And ease of re-use.
Scott: I really do like the idea of the importance attribute. That could help with semantic identification. I'd also like to be able to use example higher up in the conbody or refbody.
Kris: Where do we want to go with this? Clearly there is interest in addressing these use cases. But perhaps not consensus on how to do that. Shall we continue discussion next week, and in the meantime mull over our options.
Scott: the only limit on the discusson is I'm on vacation next week until July.
Kris: Ok, maybe we'll continue the discussion but reach no conclusions until you're back, since you'll likely be the champion of the proposal.
Scott: I'm interested in continuing discussion on the list as well.
6. DITA 2.0 editorial work
[skipped for time]
7. Draft comments in latest working draft from TC attention
[skipped for time]
8. DITA for 'To be named' version 2.0
[skipped for time]
9. Multimedia domain
Kris: Alan, are you able to set up a DITAweb rview for these topics?
Alan: Is the content ready to go in github?
Kris: I might need to publish something e.g. a PDF but I should be able to do that this week. Are you available later this week?
Alan: Yes, that should be fine.
Kris: Heads up to everyone, we'll open up this review soon, just for the multimedia topics, we do have some draft-comments in place. The idea is to do a review to get them locked down and able to be published in the committee note. We don't want the CN editors (Carlos, Bill) to have any questions about those topics.
ACTION: Alan to set up DITAweb accounts for Zoe and Joyce
11:57 ET close
-- Mr. Tom Magliery
| [Thread Prev]
| [Thread Next]
| [Date Next]
| [Thread Index]
| [List Home]