ActionItems:
1. Eliot will come up with a draft of a definition for index and generated index.
===============================================
Minutes of the OASIS DITA TC
Tuesday, 2 July 2024
Recorded by Nancy Harrison
link to agenda for this meeting:
https://github.com/oasis-tcs/dita/wiki/Previous-agendas
Attendance:
===========
Robert Anderson, Kris Eberlein, Nancy Harrison, Bob Johnson, Eliot Kimber, Zoe Lawson, Christina Rothwell, Leroy Steinbacher, Dawn Stevens, Frank Wegmann, Leo Belchikov
Business
========
Regrets: Scott Hudson, Stan Doherty
1. Approve minutes from previous business meeting
25 June 2024 (Harrison, 02 July 2024) https://groups.oasis-open.org/discussion/dita-tc-meeting-minutes-25-june-2024
Kris moved, 2nd Christina, approved by TC
2. Announcements *
[none]
3. Transition to new OASIS infrastructure: How is it going?
Any new issues?
- Christina; it would be nice to have a tutorial on how to edit pages on the site.
- Kris; they're probably only editable by me and Nancy...
4. Question about titles in examples
Robert Anderson, 30 June 2024 https://groups.oasis-open.org/discussion/question-about-titles-in-example
- Robert; this was sparked by Jarno. Way back in 1.0, example and section element were functioanlly equivalent, and because sections allowed txt, it allowed for multiple titles. We make a point of recommending that sections have only one title, so Jarno's question is 'why don't we also say, 'if you have titles in examples, intent is only to have only one title'?
- Kris; so Scott response was to say that 'it's because it's a specialization'.
- Robert; no, it's not, it's part of the base, not a specialization.
- Kris; I think we should make the same statement about titles for excample as for section.
- Dawn; I agree, I tell my clients 'just don't do it' about putting more than one title in an example.
5. Review Clifton Chenier: Indexes and indexing elements
Opening of review https://groups.oasis-open.org/discussion/base-spec-review-clifton-chenier-indexes-and-index-elements
Summary of participation and review comments
3 questions to consider, a, b, and c.
a. Do we remove implementation details? (The spec should focus on what DITA markup means.)
- Robert; comments spanned a wide range, from nits to broad questions. My question, about 'what should we have in here?' is good place to start. It's a high level overview, spec currently has lots of details about what index terms mean and where they are, but it also has lots of rendering rules. Some can't be avoided, e.g. see-also. but many rules are normative statements about collating and presentation. They're not written specifically for PDF, but many things make less sense for HTML, e-pub, or Webhelp. So we may be limiting what things an implementation can do, that might be good things for it to do. So, how broad do we want to be about rules about rendering? And, if we take them out, what do we want to do with them?
- Kris; Looking back and focusing on what DITA markup means. this content was focused on Idiom, and written by Idiom developers working on DITA-OT, to help them. I think we should remove info about rendering from spec, and add statements about how indexing would be implementation-specifiic. So we should remove topic about merging index entries.
- Robert; it might be useful guide to how one implementation might work, but it's not good as general gidelines.
- Kris; if we move it out of this part of the spec, then it should be taken out of spec completely; it's good fodder for CN about indexing.
- Eliot; totally agree.
- Kris; any concerns about removing these implementation-specific details?
- Dawn; a question, if we remove these, does that impact the DITA-OT? It's not part of spec, but it does follow that guidance? would it stop doing what it does?
- Robert; it won't change, nobody's working on that kind of thing, only adding new rules would prompt a change.
- Kris; any other concerns?
[none]
b. Do we remove normative statements about errors? (The spec should not mandate what is or is not a valid way to render an index.)
- Robert; we say things are invalid that don't make sense. like multiple see-also elements to diff things. we should talk about errors, we should talk about markup without normative statements
- Eliot; I agree
- Robert; I was in favor of these rules 10-12 years ago, but things have changesd since then.
- Kris; these rules were designed for one author per document, that's no longer the case.
- Robert; And if you have 2 diffeerent indexing guidelines for 2 different root maps, spec will give you trouble.
- Bob; it seems like we have consensus about removing output guidance from spec, but there's still a question of 'do we provide output guidance, and if so, where? That's still an open question.
- Kris; I think we immediately have a finite set of options for removed content, esp for indexing.
1. remove content entirely, make it available if TC members want to write a CN.
2. we could craft a carefully worded topic in the appendix, but we couldn't just move content as it already exists to that appendix.
- Robert; depends on how much guidance we want to give. If we just want to say 'rendering is implementation-specific', that's easy. If we want to give some examples, that requires a new topic. I'd probably prefer just a couple of paras of guidance in the overview topic.
- Eliot; agree.
- Kris; Bob, are you comfortable with removing statements about errors, adding a couple of paras to container topic, and then, if we don't think that will work, creating a CN if we have folks willing to author it?
- Bob; I think we'll want more than just a couple of paras in that initial topic.
- Kris; then we'll create a non-normative topic in appendix.
c. What should the spec state about index ranges?
- Kris; Eliot and Dawn? the content currently in draft spec was in 1.1 - 1.3 specs, albeit reworked for editorial clarity. Eliot, should there be implicit assumptions about index ranges?
- Eliot; using implicit rules for range=start/end may lead to confusion. By removing implicit end rules, and requiring an explicit end, it makes it easier to find errors. No one's complained about it, probably no one's using it. so is it worth it?
- Dawn; I second what Eliot says Is it worth it? No one among my clients bothers with ranges.
- Eliot; also, as an implemntor of indexing, dealing with implicit end is very hard to implement. but that's programmer angst, not design comment. The rule wouldn't work for some of what I've done, but if someone wanted, they could just make it work
- Bob; how much does issue of range cross over into previous discussion?
- Kris; it doesn't, here we're talking about indexterm elements with @start and @end on them, and how they're treated. Eliot; would you just remove idea of having implicit ends at particular locations?
- Eliot; yes, I'd like to get rid of implicit @end rule. if start/end don't match, it's an easy error condition.
- Kris; any other comments
- Nancy; I agree, if you have a start, you need an end, this is also probably from linear print documents.
- Leroy; I also agree, and we don't need the content that says 'processors should do...'
- Kris; I want to talk to Robert before a final decision, but any other comments about index ranges?
- Eliot; I was happy with language as it is otherwise; stated rules for ranges started in topics rather tham maps are more consistent than we thought.
- Kris; we'll need to do a reality check, because we're removing so much, both implementation details and normative statements. We'll have to do a second review, will have to check all the examples, may need to remove some examples because they do rendering. or keep them but be less 'normative' about them.
Also, we don't define formally what an index or a generated index is.
- Eliot; yes, we should define those terms, I didn't see it anywhere. There's an unstated assumption of what we mean by index/generated index.
- Kris; and how would we define it? tradition back--of-the-book index, terms and page numbers
- Eliot; It's a mapping between hierarchical subjects and locations in content, which have different rendered expressions; I can take a stab at a definition.
***ActionItem: Eliot will come up with a draft of a definition for index and generated index.
- Kris; and we might find interesting things doing a google search on index.
- Christina; in Oxygen webhelp; index is listed as a link in their footer; so it doesn't always have to be at the end of a WebHelp. See Oxygen example at: https://www.oxygenxml.com/doc/versions/25.0/ug-author/topics/getting-started-intro.html
- Kris; any other thoughts?
11:40 am ET close
------------------------------
Nancy Harrison
Principal, Infobridge Solutions
Nancy Harrison (Personal)
Portland OR
978-505-9189
------------------------------