[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: minutes from 8/13/19 DITA TC Call
=================================================
Minutes of the OASIS DITA TC
Tuesday, 13 August 2019
Recorded by Hancy Harrison
link to agenda for this meeting:
https://wiki.OASIS-open.org/dita/PreviousAgendas
Attendance:
Robert Anderson, Deb Bissantz, Carsten Brennecke, Bill Burns, Stan Doherty, Kris Eberlein, Hancy Harrison, Scott Hudson, Eliot Kimber, Zoe Lawson, Chris Nitchie, Jacquie Samuels, Jim Tivy
Business
========
1. Roll call
Regrets: Carlos Evia, Keith Schengili-Roberts
2. Approve minutes from previous business meeting:
06 August 2019
https://lists.oasis-open.org/archives/dita/201908/msg00027.html (Recorded by Bissantz, sent by Eberlein, 12 August 2019)
Moved by Kris, 2nd by Bill, approved by TC
3. Announcements:
None
4. Action items
11 September 2018
Kris: Review conversation with Joe Pairman, e-mails about metadata, and TC discussion in late 2017/early 2018; summarize to TC: due 09 April Overdue
13 November 2018
Eliot: Test refactoring of grammar files; due 15 Aug
18 December 2018
Eliot: Investigate issue re earningAggregationsTopicrefConstraintMod.xsd; due 15 Aug
05 March 2019:
Alan: Update DITA 2.0 files for appropriate elements with LwD hint values for @format and create a pull request; due 23 April
09 April 2019
Eliot: Does SVG zip file need to be in techcomm grammar folder? due 15 Aug
Kris and Tom: Finish up any discussion about examples in ArchSpec files
30 April 2019
Kris: Request OASIS Open repository for tools/scripts to aid users in moving to DITA 2.0
28 May 2019
Kris and Robert: Revise content and run it by Eliot (Draft-comment in spec WD03, section 3.3.3, page 37)
Robert: Take an initial look at fixing this (Draft-comment in spec WD03, section 3.4.4, page 52)
Chris: Look at draft-comment in spec WD03, section 8.2.2.19, page 210
18 June 2019
Robert: Set up submodule for DITA for TechComm repository
Robert: Work on remaining stylesheet issues; see https://wiki.oasis-open.org/dita/stylesheetBacklog
02 June 2019:
Kris and Deb: Look at existing content in spec about map processing (especially construction of hierachy, rel tables) and make recommendations (COMPLETED by Kris)
- no updates to any AIs.
- Kris; note that Eliot has a few items due on 15 Aug. Does anyone have any updates? Please check any AIs belonging to you and do something about them.
5. DITA 2.0 stage two proposals
Vote
#277: Change specialization base of imagemap
https://lists.oasis-open.org/archives/dita/201908/msg00026.html (Updated by Eberlein, 12 August 2019)
Kris made motion to move this to stage 3, 2nd by Zoe
Voting results:
yes votes: 11 (Robert Anderson, Deb Bissantz, Carsten Brennecke, Bill Burns, Stan Doherty, Kris Eberlein, Hancy Harrison, Scott Hudson, Eliot Kimber, Zoe Lawson, Chris Nitchie)
no votes: 0
Stage 3 reviewers for this proposal: Eliot, Zoe, Scott
6. DITA 2.0 stage three proposals
Vote
None
Initial discussion
#253 Indexing changes
https://lists.oasis-open.org/archives/dita/201907/msg00073.html (Eberlein, 18 July 2019)
- Kris; this proposal basically about removing index-base and index-sort-as, moving index-see and index-seealso to base DITA, so index-base is unnecessary.
- Robert; I'm happy with this; think it's a good change
- Kris; basically a simplificiation and cleanup move; was reviewed originally by Dawn and Bill.
- Eliot; for folks who don't use indexing, it does mean removing indexing domain from shells, and that would now require a slightly more complicated constraint module, but I don't think that's a real issue.
- Robert; but if you're already taking out indexterm, they'll never see its new children.
- Eliot; I think I don't constrain out indexterm even for folks who don't use it anyway...
- Kris; for those who do create an index, you'll see a simplified version of what can be in indexterm. fewer indexing elements available
- Eliot; another thing; currently DITA doesn't have a way to indicate that a indexterm is the primary intedexterm for an item.
Kris; I think that would be a separate stage 1 proposal; suggest you send a mail to TC list.
- Eliot; I'm not sure I want to champion a proposal if I'm the only person who cares...
- Kris; sending an email just puts it on agenda to get it discussed, doesn't obligate you to champion it
[#253 indexing changes proposal will be voted on next week]
7. DITA 2.0 stage one proposals
Allow <example> in same locations as <div>
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)
New e-mails:
https://lists.oasis-open.org/archives/dita/201907/msg00058.html (Hudson, 16 July 2019)
https://lists.oasis-open.org/archives/dita/201907/msg00060.html (Anderson, 16 July 2019)
- Scott; one of my AIs was to get different content models that might 1) make example more like fig, or 2) add an 'example' type to note, or 3) if example was allowed in same place as div, also illustrate situations where example is allowed today. I did see a lot of difference, but Robert's suggestion (email above), which simplified things, is more in line with making it like fig.
- Robert; I found your note really helpful; wrt where dive can go and where fig can go; I think that putting it where fig can go brings a lot of benefit. and if we put it where fig can go, it's somewhere where you could already put a good-sized figure block. so it won't really impact implementers; e.g., you often want an example to go in a fig, and fig can't go in itself, so that's useful.
Scott; and it addresses my concerns about typical places we've found we needed examples; this approach solves that problem.
- Kris; this will also work well with set content.
- Robert; so let's get this done soon so we can use it; it's a good solution.
- Bill; completely agree with that approach.
- Kris; is there anyone who would oppose this?
[none]
- Kris; Scott, will you champion this?
- Scott; yes.
[moved to stage 2, with Scott assigned as champion.]
8. DITA 2.0 editorial work
Highlights?
See Editorial work completed for a full summary
See Backlog for open items and future plans
Working draft 09:https://lists.oasis-open.org/archives/dita/201908/msg00033.html (Eberlein, 13 August 2019)
Contains revised indexing content, based on reviews by Robert Anderson, Stan Doherty, Eliot Kimber, and Joyce Lam.
- Kris; I posted new version of 2.0 spec, with updated indexing content as reviewed by Robert, Stan, Eliot, and Joyce; included as many comments as I could, but left some as draft-comments; a significant comment from Eliot was we need a topic on how processors merge index elements and create an index; how do we match content, etc. any questions before we go to item #9?
[none]
9. Question about how to define equivalent index entries
https://lists.oasis-open.org/archives/dita/201908/msg00028.html (Anderson, 12 August 2019)
https://lists.oasis-open.org/archives/dita/201908/msg00029.html (Nitchie, 12 August 2019)
https://lists.oasis-open.org/archives/dita/201908/msg00032.html (Kimber, 13 August 2019)
- Robert; coming out of above review (agenda item #8), question was raised of how much should spec define how processors should treat index entires that match; how far do we go in saying what 'matches' processors should be free to render indexing content however they want. can the spec consider matching? what gets left up to processing?
- Chris; main takeaway is I think we need to err on side of permissiveness, wrt leading/trailing white space, case sensitivity??, etc.
- Robert; I'm wary of saying 'processors should give an option for something' wrt indexing. Processors are free to provide options, or not. Also, the content as written previously was written from POV of PDF or printed book, and a lot of content in it is irrelevant to digital content and needs to be written more generally.
- Kris; I have changed all instances of 'page reference' to 'locators' which is a more output-agnostic term. Also, going back to case-sensitivity, we make reference to what we expect in 'start' and 'end' terms for index ranges; should we?
- Eliot; I'm not sure that's really appropriate; matching of index terms is more complicated than just case-sensitivity; gets into locale-specific and language-specific issues.
- Kris; it's definitely more complicated than for @ values like @start and @end, but I'd hate to specify something on an @ value that didn't match a corresponding value in index content.
- Eliot; but start and end are @ values, there has to be exact match
Robert; and tha @ value doesn't have to correspond to actual index term, with terms themselves different, there are lots of ways you might want to combine them.
- Kris; well, I'd be an advocate for case-sensitivity in index terms.
- Robert; the issue is how do we address these issues? how strict does the spec want to be? I'd prefer to err on side of permissiveness, but how do we address it? Do we list what has to be considered? Or give a list of what we recommend be considered?
- Eliot; we have 2 audiences
1. naive developer, who knows nothing about indexing.
2. a developer who has made a deep dive into locale-specific matching and sorting; if we say to much, they may find that the spec says something that prevents them from doing what they want to do.
- Robert; we want to support both the 90% and the 10%.
- Eliot; the spec has to explicitly say 'we're not constraining how you do your index processing, but this is the way they're ususally done'.
- Robert; so use 'indexes typically do ...' , or 'recommended way is...'?
- Kris; Eliot, can you lay out what you said in your email?
- Eliot; reasonable to specify to (sse his mail)
- Kris; in 1.1-1.3, specs said 'given a matching indexterm element, correct behavior is to merge.' I think that didn't show up as clearly, because I framed it as a normative statement, and asked if it should be normative; i.e. 'all indexterms with the same content are merged, and all contributed page numbers are included in the entry.'
- Eliot; but that may or may not actually answer the questiosn; it doesn't distinguish single index term from a primary term with secondary entries; so spec is underspecifying in that case. IF there are no secondary entries, that statement is somewhat ok, but it doesn't cover subordinate entries.
- Kris; would it help if Eliot gave more examples of how processors might merge single terms with identical terms with subordinate entries?
- Chris; thinking about it in terms of persons who structured the index, I'd think that they would want those to be in the same entry.
- Eliot; but you don't know if someone wants that, and since it's very probable that the diff entries were authored by diff people, it's also possible that wouldn't work at all.
- Kris; also, you not only have topics by multiple authors, but also multiple maps, also with indexing markup to be merged.
- Eliot; so spec needs to be more clear about what you should do in that case, and processors need to do what needs to be done.
- Scott; so do you want to clarify between 'apple' and 'Apple computer"
- Eliot; would think you do.
- Kris; indexing content of spec 1.1-1.3 was hard to use, Robert and I have stayed away until 2.0. We have to be careful what we do; need a lot of latitude for processors, and we can't assume print processing. We don't know what they need now, or 5 years from now. I want to go back to the question: How may DITA users do indexing?
- Zoe: when I was at IBM, a lot of groups were moving away from indexing towards search; I haven't used an index term in content I created in 10 years.
- Eliot; at IBM in early days, w/Bookmsater, index entries were given priority in search results, so the index was valuable.
- Chris; same in other systems.
- Scott; we do some indexing at Jeppesen; challenge is to develop a good index.
- Stan; at Oracle it's rare. there are generally resources for either indexing or SEO, and SEO generally wins.
- Kris; I don't remember if we had any indexes in 1.0 spec. for 1.2 and 1.3 we turned off indexing; we didn't have agreement in TC about it, and no way to do a good one. I turned it back on for the most recent 2.0 draft, just to see it. The element ref topics are better indexed than arch spec index.
- Eliot; indexing conceptual topics is really hard work.
- Kris; for docs like the spec, an index is invaluable; for some things you'll never be able to do an adequate search; e.g., if you wanted to find something about a single element, or a single @, you might end up with 400 hits.
- Eliot; I'd love to have the time to index the spec, but it's a month's worth of work.
- Kris; another point Eliot's email brought up; should primary entries with secondary entries have page numbers? do you merge, and if you do, what gets a page number?
- Eliot; you can manage that from authoring standpoint, but not easily from a processing standpoint.
- Kris; if you want that, you need to have overrides of processing to get what you want, but people are just not making them, because people aren't taking that trouble.
- Eliot; in publishing, indexes are done by professional indexers, and fewer and fewer are indexed.
- Chris; it's a diff approach from legal group; they used xref to indexterm, just to get a good index for their purposes.
- Kris; we need to be ready for a DITAWeb review of content once we put in disclaimers and put in a topic on constructing a useful index. We won't move to that till we've agreed on the issue on indexing. We also need to discuss how index ranges work, and how to define and default on those. Eliot, Robert and I have discussed this; does anyone else have experience they'd like to share?
[none]
[no index discussion next week, move on toother items]
12 noon ET close
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]