OASIS Darwin Information Typing Architecture (DITA) TC

DITA 1.0: Separate architectural spec and language reference DITA 1.1: " " DITA 1.2: Aggregated archSpec and LangRef DITA 1.3: " " and three editions What do we want to consider for DITA 2.0? -- Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype)

I wanted to follow up on the discussion from Tuesday, specifically regarding the suggestion that (I'm pretty sure) came from Chris Nitchie. The suggestion there was about changing how we think about and publish the spec. Rather than using a hard-to-define separation of "Architectural spec" versus "Language spec", much of our content could be organized much more logically into Processing and Grammar. As I said on the call, I really like that idea. Kris and I found during 1.3 editing that it could be very difficult to make a distinction between what was "Architecture" versus what was "Language". That difficulty doesn't entirely go away with Processing and Grammar, but I think those groupings go a long way to helping us better organize the content. That said - those two distinctions don't cover everything in the specification. I expect that if we make that sort of reorganization, we'll end up with several better focused sections. I can think of a few good candidates for other major sections of a 2.0 spec, based on sub-sections of the current architectural specification: - Addressing - Specialiazation and modularity - Grammar file construction Are there any suggestions for additional types of content that exist in the spec (and should continue to exist)? Alternatively, do any of the sections I've listed seem like the wrong direction? Regards, Robert D. Anderson DITA-OT lead and Co-editor DITA 1.3 specification , Digital Services Group E-mail: robander@us.ibm.com Digital Services Group 11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA Kristen James Eberlein ---09/06/2016 09:57:56 AM---DITA 1.0: Separate architectural spec and language reference DITA 1.1: " " From: Kristen James Eberlein <kris@eberleinconsulting.com> To: DITA TC <dita@lists.oasis-open.org> Date: 09/06/2016 09:57 AM Subject: [dita] DITA 2.0: How might we reorganize (reformulate?) the spec for DITA 2.0 Sent by: <dita@lists.oasis-open.org> DITA 1.0: Separate architectural spec and language reference DITA 1.1: " " DITA 1.2: Aggregated archSpec and LangRef DITA 1.3: " " and three editions What do we want to consider for DITA 2.0? -- Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) --------------------------------------------------------------------- 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  

What do you mean by "Grammar file construction"? That sounds like it would be something under the specialization section. Or do you mean something about the organization of the shipped grammar files (in which case perhaps "Grammar file organization")? Or something else?   mag     From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On Behalf Of Robert D Anderson Sent: Thursday, September 08, 2016 10:55 AM To: Kristen James Eberlein Cc: DITA TC Subject: Re: [dita] DITA 2.0: How might we reorganize (reformulate?) the spec for DITA 2.0   I wanted to follow up on the discussion from Tuesday, specifically regarding the suggestion that (I'm pretty sure) came from Chris Nitchie. The suggestion there was about changing how we think about and publish the spec. Rather than using a hard-to-define separation of "Architectural spec" versus "Language spec", much of our content could be organized much more logically into Processing and Grammar. As I said on the call, I really like that idea. Kris and I found during 1.3 editing that it could be very difficult to make a distinction between what was "Architecture" versus what was "Language". That difficulty doesn't entirely go away with Processing and Grammar, but I think those groupings go a long way to helping us better organize the content. That said - those two distinctions don't cover everything in the specification. I expect that if we make that sort of reorganization, we'll end up with several better focused sections. I can think of a few good candidates for other major sections of a 2.0 spec, based on sub-sections of the current architectural specification: - Addressing - Specialiazation and modularity - Grammar file construction Are there any suggestions for additional types of content that exist in the spec (and should continue to exist)? Alternatively, do any of the sections I've listed seem like the wrong direction? Regards, Robert D. Anderson DITA-OT lead and Co-editor DITA 1.3 specification , Digital Services Group E-mail: robander@us.ibm.com Digital Services Group 11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA Kristen James Eberlein ---09/06/2016 09:57:56 AM---DITA 1.0: Separate architectural spec and language reference DITA 1.1: " " From: Kristen James Eberlein < kris@eberleinconsulting.com > To: DITA TC < dita@lists.oasis-open.org > Date: 09/06/2016 09:57 AM Subject: [dita] DITA 2.0: How might we reorganize (reformulate?) the spec for DITA 2.0 Sent by: < dita@lists.oasis-open.org > DITA 1.0: Separate architectural spec and language reference DITA 1.1: " " DITA 1.2: Aggregated archSpec and LangRef DITA 1.3: " " and three editions What do we want to consider for DITA 2.0? -- Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) --------------------------------------------------------------------- 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  

I think what I really meant was coding practices (the term used in DITA 1.3). We have a lot of critical rules around specialization - here is how you extend an element, here are the rules for what you can do with it. Those do not (necessarily) have any connection to the grammar files. That is - conceptually, when I specialize <ol> to <steps>, there are a lot of things I can do and and a lot of things I cannot do. Those rules are true regardless of what grammar format I'm using (XSD, DTD, RNG, or any other rule format). The rules are true whether my particular DTD implementation is modular, or optimized in a single file. They're even true in the (abstract and rather impractical) case where you don't even have a grammar file. Those are now in section 2.5.3 (2.5 as a whole covers specialization, constraints, generalization, and configuration). All I meant was to highlight that this is different from constructing the rules themselves (that is, different from the DTD/XSD/RNG coding practices). In DITA 1.2 these things were all jumbled together in different parts of the Architectural Spec. In 1.3, they're distinct, which is an improvement. In a larger reorganization, I'd hope to maintain that distinction, treating the rules on how to extend + constrain DITA as separate from the rules for one specific grammar format. Sorry for the confusion, Robert D. Anderson DITA-OT lead and Co-editor DITA 1.3 specification , Digital Services Group E-mail: robander@us.ibm.com Digital Services Group 11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA "Tom Magliery" ---09/08/2016 01:01:29 PM---What do you mean by "Grammar file construction"? That sounds like it would be something under the sp From: "Tom Magliery" <tom.magliery@justsystems.com> To: Robert D Anderson/Rochester/IBM@IBMUS, "Kristen James Eberlein" <kris@eberleinconsulting.com> Cc: "DITA TC" <dita@lists.oasis-open.org> Date: 09/08/2016 01:01 PM Subject: RE: [dita] DITA 2.0: How might we reorganize (reformulate?) the spec for DITA 2.0 Sent by: <dita@lists.oasis-open.org> What do you mean by "Grammar file construction"? That sounds like it would be something under the specialization section. Or do you mean something about the organization of the shipped grammar files (in which case perhaps "Grammar file organization")? Or something else? mag From: dita@lists.oasis-open.org [ mailto:dita@lists.oasis-open.org ] On Behalf Of Robert D Anderson Sent: Thursday, September 08, 2016 10:55 AM To: Kristen James Eberlein Cc: DITA TC Subject: Re: [dita] DITA 2.0: How might we reorganize (reformulate?) the spec for DITA 2.0 I wanted to follow up on the discussion from Tuesday, specifically regarding the suggestion that (I'm pretty sure) came from Chris Nitchie. The suggestion there was about changing how we think about and publish the spec. Rather than using a hard-to-define separation of "Architectural spec" versus "Language spec", much of our content could be organized much more logically into Processing and Grammar. As I said on the call, I really like that idea. Kris and I found during 1.3 editing that it could be very difficult to make a distinction between what was "Architecture" versus what was "Language". That difficulty doesn't entirely go away with Processing and Grammar, but I think those groupings go a long way to helping us better organize the content. That said - those two distinctions don't cover everything in the specification. I expect that if we make that sort of reorganization, we'll end up with several better focused sections. I can think of a few good candidates for other major sections of a 2.0 spec, based on sub-sections of the current architectural specification: - Addressing - Specialiazation and modularity - Grammar file construction Are there any suggestions for additional types of content that exist in the spec (and should continue to exist)? Alternatively, do any of the sections I've listed seem like the wrong direction? Regards, Robert D. Anderson DITA-OT lead and Co-editor DITA 1.3 specification , Digital Services Group E-mail: robander@us.ibm.com Digital Services Group 11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA Kristen James Eberlein ---09/06/2016 09:57:56 AM---DITA 1.0: Separate architectural spec and language reference DITA 1.1: " " From: Kristen James Eberlein < kris@eberleinconsulting.com > To: DITA TC < dita@lists.oasis-open.org > Date: 09/06/2016 09:57 AM Subject: [dita] DITA 2.0: How might we reorganize (reformulate?) the spec for DITA 2.0 Sent by: < dita@lists.oasis-open.org > DITA 1.0: Separate architectural spec and language reference DITA 1.1: " " DITA 1.2: Aggregated archSpec and LangRef DITA 1.3: " " and three editions What do we want to consider for DITA 2.0? -- Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) --------------------------------------------------------------------- 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

I don't have particularly strong opinions about the spec structure and organization--as a formal specification rather than a tutorial it's always going to be a challenge to read and understand no matter how you organize it--the best we can do is ensure that it's not worse than it has to be, make sure the appropriate links are there, etc. I think the editors did a pretty good job with 1.3 given the challenges they faced.  It's also the case that no single organization is going to be ideal because different people think about things in such different ways. I've always considered the DITA architecture to include the base element types. For example, you can't separate DITA addressing from the concept of topic as a unit of content organization that has specific identification and addressing implications both for itself and for its directly-contained non-topic descendants. The essential nature of the base architecture is already reflected in the current Architecture Spec sections that talk about DITA markup generally. Those historically reflect an attempt to describe DITA conceptually for authors and we've lightly reworked them to be a bit more rigorous and standard-like, but they still read much more like a tutorial than a formal definition of concepts and requirements. With that analysis I could definitely see a tighter integration of what is currently the language reference for the base elements with a more formally-defined architecture specification. The current spec currently describes linking and addressing in a single major section, which makes sense because the linking depends on the addressing. But at the same time, the semantics of linking should be completely divorced from addressing details (meaning a given link should mean the same thing if you replace one form of address with a different-but-equivalent form of address and that is mostly true for DITA 1.3). So it could be possible to have a top-level section that is just about the mechanics of addressing as divorced from the semantics of linking in all the different ways that DITA does it. The linking semantics could be covered as part of a larger unified discussion of DITA structural components and semantics generally. Ideally the specialization facility would be sufficiently abstract so that other XML applications that are not otherwise related to DITA could pick it up and use it. The main barrier to that that I see today are the DITA-specific rules about what you can and can't conref. But we've also made it much clearer that those rules are not mandatory and they're certainly not a prerequisite for productive use of specialization generally [they are much more about ensuring reliable interchange of content than they are about interchange and operation of processing.]  I had a dream at one point that specialization could be a completely separate specification that DITA then uses by reference but I doubt there are many people beyond myself who would care enough to make it worth the effort. At this point it's easier to just use DITA than to try to make a new non-DITA specialization-based XML application and legacy applications like DocBook and JATS would require so much change to their markup design to enable the use of DITA-style specialization that it would never happen, even if the custodians of those standards wanted to do it (which to date they show no inclination to do). Cheers, E. -- Eliot Kimber http://contrext.com   From: < dita@lists.oasis-open.org > on behalf of Robert D Anderson < robander@us.ibm.com > Date: Thursday, September 8, 2016 at 12:55 PM To: Kristen James Eberlein < kris@eberleinconsulting.com > Cc: DITA TC < dita@lists.oasis-open.org > Subject: Re: [dita] DITA 2.0: How might we reorganize (reformulate?) the spec for DITA 2.0 I wanted to follow up on the discussion from Tuesday, specifically regarding the suggestion that (I'm pretty sure) came from Chris Nitchie. The suggestion there was about changing how we think about and publish the spec. Rather than using a hard-to-define separation of Architectural spec versus Language spec , much of our content could be organized much more logically into Processing and Grammar. As I said on the call, I really like that idea. Kris and I found during 1.3 editing that it could be very difficult to make a distinction between what was Architecture versus what was Language . That difficulty doesn't entirely go away with Processing and Grammar, but I think those groupings go a long way to helping us better organize the content. That said - those two distinctions don't cover everything in the specification. I expect that if we make that sort of reorganization, we'll end up with several better focused sections. I can think of a few good candidates for other major sections of a 2.0 spec, based on sub-sections of the current architectural specification: - Addressing - Specialiazation and modularity - Grammar file construction Are there any suggestions for additional types of content that exist in the spec (and should continue to exist)? Alternatively, do any of the sections I've listed seem like the wrong direction? Regards, Robert D. Anderson DITA-OT lead and Co-editor DITA 1.3 specification , Digital Services Group E-mail: robander@us.ibm.com Digital Services Group 11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA Kristen James Eberlein ---09/06/2016 09:57:56 AM---DITA 1.0: Separate architectural spec and language reference DITA 1.1: From: Kristen James Eberlein < kris@eberleinconsulting.com > To: DITA TC < dita@lists.oasis-open.org > Date: 09/06/2016 09:57 AM Subject: [dita] DITA 2.0: How might we reorganize (reformulate?) the spec for DITA 2.0 Sent by: < dita@lists.oasis-open.org > DITA 1.0: Separate architectural spec and language reference DITA 1.1: DITA 1.2: Aggregated archSpec and LangRef DITA 1.3: and three editions What do we want to consider for DITA 2.0? -- Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) --------------------------------------------------------------------- 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