Groups - DITA TC Meeting Minutes 26 July 2016 uploaded

[Tom Magliery<tom.magliery@justsystems.com>]

        Submitter's message
        Action items:
1. Kris: Talk to Chet about incorporating an information topic about revisions and/or full revision information into the 1.3 Errata document.
2. Keith: Ping Chet again about Google Analytics, mindful of our imminent schedule deadlines for 1.3 Errata progress.
3. Kris to look more closely at the content of both langref and arch spec regarding subject schemes. (Bonus if Eliot and Chris can manage it as well.)

=================================================
Minutes of the OASIS DITA TC
Tuesday, 26 July 2016
Recorded by Tom Magliery
link to agenda for this meeting:	
https://wiki.oasis-open.org/dita/PreviousAgendas

Regrets: 
Regrets: Robert Anderson, Stan Doherty, Nancy Harrison, Joe Storbeck

Standing Business
=================

Approve minutes from previous business meeting:
https://lists.oasis-open.org/archives/dita/201607/msg00086.html (Nancy Harrison, for 19 July 2016)
Previous minutes: Motion to approve by Kris, seconded by Dick; no objections given

Business
========
1. Action items:

From 1 June 2016:
Kris, Nancy, Bob: Meet about errata builds (COMPLETED)
Dick: Review materials about how other TCs use Jira (COMPLETED)
From 19 July 2016:
Kris: Update errata change listing to include info about grammar files (IN PROGRESS)
Keith: Discuss Google Analytics with OASIS staff (IN PROGRESS)
Kris: Open TC Admin request for template for DITA and DITA-OT committee note (COMPLETED)
Chris: Add keys and subjectScheme to DITA 2.0 list 
Chris: Add include proposal to DITA 2.0 list 
Don: Write up transclusion use case 
Kris, Bob, Chris: Discuss thread on dita-comment 

2. Announcements:
NONE

3. Continuing item: DITA 1.3 errata
Build process ---
Bob: Completed work on the build process; it will build everything except the master change document and dump everything into a compliant directory structure. File naming and links are also compliant with OASIS guidelines.
Kris: Looks like you've implemented some attribute value tokens to handle things.
Bob: Given the dynamic nature of links we don't want to handle that manually. A series of keys is populated with basic components for file names. Those are extracted from the root map and made available as Ant properties fed back into the transformation. Part of that involves token substitutions to replace links on the cover page.
Kris: Sounds super, this was very fiddly and manual and error-prone for the 1.3 spec.

Change list ---
Kris: An update on the change list, took a look at directions from Chet and Paul. Looks like they want a separate list, I have started building source files. Built new topics for changes to the content model and changes to the grammar files, but have not yet committed to SVN or integrated these new topics into Bob's build. 
On one hand want one change list with all changes in one place, but I also think it would be handy to have a change listing in the revised spec; otherwise we don't have any explanation for readers about the change bars or color coding or whatever we decide. 
Tom: If I were reading a spec and encountered change bars I would want to be able to find an explanation.
Kris: Maybe we need at least a new topic explaining the errata, and possibly incorporation of the entire change list into the errata.
Bob: Keeping them separate would be more useful for someone wanting to keep track of the changes.
Kris: Definitely need a separate change document, the question is whether we want to incorporate some of that info also into the spec.
Bob: If I wanted to compare old and new versions, I'd want two separate documents.
Kris: In the full doc, whether it's base or all-inclusive, would you still appreciate a topic explaining revision info?
Bob: Yes, that would be appropriate for an introduction or other early topic.
Kris: Does anyone disagree with having such a topic included? [no objections raised]

ACTION: Kris to talk to Chet about incorporating revision topic and/or full info in the errata document. (We will definitely have a separate doc with full change info regardless.)

SEO ---
Keith: Asked Chet whether we could add Google anlytics to our portion of web site and asked if we could get server logs
either way we should get interesting results. Have not heard back yet.
Kris: Perhaps follow up with Chet and say that we had a schedule goal to complete work on this by the 29th; remind him where we are and see if he can bump this up his priority list.
Keith: At least this can be fairly esay retrofitted to existing web site
Tom: Not sure if we can retro-fit, though. We could not do that with the spec itself because the HTML is fixed as a standard.

ACTION: Keith to go back and respond to Chet about that.

Keith: Another thing is if we get server log data that would at least give us some idea of who is visiting the spec and when. E.g. it would be interesting (if surprising) to learn that most people are reading the spec from mobile phones.

4. No updates on committee notes

5. Continued item: [dita-comment] email list
Gathering restricted values using a subject scheme map
Kris: New email from Radu raises some new points for consideration; questions whether my initial response to him was valid.
Summary: Radu's original email included a scenario with multiple subjectdef in one map, one used via keyref to reference a key in that map. My response was that I thought the values should be {none, left} excluding the value of floatLeft. Now I am not sure whether that is true or not given his latest email to the list. I wonder if the subject scheme details have been under-specified.
Chris: What Radu's saying is what I was kinda saying last week. When you reference another subject by keyref, in some cases you're saying copy this into the new location; in other cases it's a push. Which is which depends on how deep you are in the hierarchy. Maybe it is a bit underspecified, can't really tell from the examples we have.
Kris: It's a little tricky; Radu's email brings up private email we had about how they implemented subject scheme support going back a few years. In that example I said you could have the same subject referenced twice in a map, once by keys and once by keyrefs, and it could be part of two different larger enumerations. It's diff from his original example here because you're not referencing by keyrf the outer subjectdef container. 
Chris: Right, I think it doesn't matter whether it's outer or inner, you're just referencing the subjectdef. One way it's a pull and the other it's a push.
Kris: If you go back to Radu's orig subject scheme in his first email, would you think the set of permissible values for outputclass would include float left?
Chris: It depends on whether at authoring time you include intermediate values. 
An example in the specification talks about extending a subject scheme. According to the specification both in normative language and examples, when you have that, the subjectdefs that appear beneath the root are effectively pushed into the subject you're referencing.
Example uses schemeref element but nothing that I can see says it's neceessary. It would surprise me if that were necessary.
The other case (more apropros to this discussion) is what happens if you have a keyref from deep down inside ?
Example suggests that the resolution (using schemeref) takes the entire scheme hierarchy and copies it into the scheme that's referencing it. It's not just taking child values, it's taking the whole structure.
Kris: I agree. Normative text we added in 1.3 is in the topic (2.2.3.1). We spent a lot of time deciding what that language said. I feel like I want to do another pass through all the examples now. Seems we have a little disconnect between that language and what's in the langref topics showing that the outermost subjectdef element is ignored for purpose of constructing enumerations.
Eliot: 2.2.3.2 says each value is defined using subjectdef element. Looking at Radu's example it's clearly defining a category floatLeft. My expectation would be that the children of floatLeft become children of outputclass.
Chris: That's my position based on reading of 2.2.3.8.3, extending subject schemes upward.
Eliot: 2.2.3.3. says values can be a hierarchy, uses filtering and flagging but does not disallow their use here. I guess I'm agreeing that the spec is underspecified.
Chris: But if you have one with values of left that would effectively be a no-op.
Eliot: Conclusion is the specification is underspecified.
Kris: With quick reads we've found two different interpretations. Maybe closer reads will yield better interpretation.
Eliot: The question comes down to: is our expectation that the subjectdef with keyref will be a replacement
Kris: That's not an unreasonable interpreation but we have examples that seemingly contradict that. Some stuff about top level being category and leaves being controlled values (added in 1.3 for clarificaiton) has complexified it.
Eliot: It would be nice if we could ask Erik Hennum his intentions.
Kris: I'm not sure that matters, given what we have as normative for 1.2 and 1.3, what does it all add up to for 1.3 errata?
A separate question is where do we want to go with 2.0. From viewpoint of a processor I'd like there to be one correct answer to Radu's question about how a processor should interpret the values for outputclass in this example.
Chris: From a strict reading of the spec there is currently no one answer.
Kris: I feel like I need to do one more complete reading of the architectural and langref topics to be sure I've seen everything I need to see. Eliot and Chris have you done that?
Chris: Probably not, have been mostly focused on the architectural spec, haven't taken a close enough look at the langref topics.
Kris: I know for 1.2 there was very little in the architectural spec and a lot in the langref, particularly embedded in examples. For 1.3 we tried to improve by merging content and bringing more into the arch spec, but not sure if we did that well enough. Need to look again at the langref.

ACTION: Kris to look more closely at the content of both langref and arch spec regarding this matter. (Bonus if Eliot and Chris can manage it as well.)

Eliot: In 2.2.3.2 it says parent subject is category and children are values
2.2.3.4 clearly shows a top level that has two values, both are allowed values. That seems like an error. Should be root subjectdef defining category and descendants defining controlled values.
Based on the example in 2.2.3.4 it's clear that the keyref in the subjectdef was copied in its entirety
If we apply the same behaviour to Radu's example the result would be that outputclassFig subject would have the values none floatleft and left.
Jim: I think that result makes sense.
Kris: Looking at that example, with binding of audience values to controlled values I think values would be [all of them] but not including "users". 
From that point of view wouldn't floatLeft be excluded from Radu's list?
Eliott: I would say not; reasoning is if subjectdef acts as use by reference of the entire subjectdef as though it had occured in the content, then in radu's example, being referenced as a child would be accessed as descendant
Because floatLeft in the top level subjectdef can only act as a top level subjectdef and therefore only used in values
Jim: One other thing - in some cases you might define that only terminal values in a tree are actual controlled values.
Eliot: but 2.2.3.4 makes clear that all descendents are allowed values.
Jim: Distinction has to be made. Probably it's interior levels with controled values. Why would you layer something if it were not categories?
Eliot: In case of hierarchy non-leaf children of subjectdefs act as both category and values. "Therapist" is a category but it's also a value. Then you also have other values because leaf values are also values.
Jim: I'm just wondering if it makes general sense, maybe this is the source of ambiguity.
Eliot: I think the issue comes down to what is the subject composition implication for subjectdef with keyref. Is the semantic of the referenced subject unchanged?
Jim: I kind of agree that it's like a conref, a reference to a source as if the source appeared there.
Kris: We have these semi-competing examples that talk about the outermost subjectdef not contributing a value to the list of controlled attribute values.
Jim: Maybe that comes from the temrinal argument. In order to get that in you have to use the word "descendants" instead of children. Maybe need to say leaf nodes if that's what you want. Not sure which way to go but there is an issue around whether we should be rolling something about that allows people to use category objects as internal nodes or should be just temrinal nodes. Right now ther'es no language about terminal nodes.
Kris: Yes, we do not say terminal or leaf nodes anywhere in the spec.
Jim: That is an interesting point to study.
Kris: It's tricky because we've overloaded keys. They have meanings in subject scheme that they don't have anywhere else. Also we have tended to not always think about these special instances when we were talking about new/other things in the spec e.g. keyscope.
Chris: No, I definitely wasn't thinking about subject scheme at all when I designed keyscopes.

Kris: The only tools that handle subject schemes for now are the DITA OT, oXygen and SuiteShare. 
Chris: Support in Titania is coming ... hence my recent study of subject schemes.
Kris: User feedback a few years ago on this for SyncroSoft was not consistent.
Eliot: Does XMetaL have any support?
Tom: No, they are just treated like a map.
Kris: Maybe it's worth considering the existing implementations to see what they do and decide how that influences our decisions. I will look at this, and would like anyone else who has the time to look at it both in architectural spec and langref.

Let's try to close out this issue next week.
This is a good jumping point to another issue in agenda item #6, originally from Leigh White, raising other unresolved questions about subject schemes.
Also I would like people to be aware that Robert will return next week and we will pick up our discussion of DITA 2.0 and chunking.

Meeting adjourned 9am PT/12noon ET.
        
-- Mr. Tom Magliery

Document Name: DITA TC Meeting Minutes 26 July 2016

---

No description provided.
Download Latest Revision
Public Download Link

---

Submitter: Mr. Tom Magliery
Group: OASIS Darwin Information Typing Architecture (DITA) TC
Folder: Meeting Notes
Date submitted: 2016-07-26 15:17:40