OASIS Darwin Information Typing Architecture (DITA) TC

This is an attribute that we might want to consider for changes in DITA 2.0. Here what the DITA 1.3 spec says: @lockmeta By default, metadata in the map supplements or overrides metadata that is specified at the topic level, unless the @lockmeta attribute of the <topicmeta> element is set to no . Allowable values are yes , no , and Using the -dita-use-conref-target value . A couple of things: I'm not sure that we specify anywhere what our expectations for processors are about the differences between supplementing and overriding metadata. The DITA 1.3 element reference topic for <topicmeta> is ambiguous, since it implies that navigation titles are metadata, but whether navigation titles specified in maps are used depends on whether @locktitle is set to yes . (Does @lockmeta also have an effect on navigation titles?) -- Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 622-1501; kriseberlein (skype)

If I look at the DITA 1.3 specification, it looks like the <chapter> element, a specialization of <topicref> specifically intended to refer to topics (as well as maps) doesn't allow @lockmeta. That seems like one can of worms; should specializations of topicref allow @lockmeta? Another can of worms might be that the operation of the attribute seems precisely backwards; do the default thing and override the topic metadata unless the value for the lock attribute on the topic reference is "no".  I'm sure I'm just not looking at it from the correct perspective, but this seems actively confusing.  (Or the original name of the attribute was @permit-overrides or similar.) Yet another can of worms would be granularity; right now, @lockmeta is everything-or-nothing, but everything isn't defined.  It's not difficult to imagine use cases for more granularity than that. And the last obvious can of worms is the one noted as 2 originally; how does @lockmeta interact with other processing control attributes? I think it might be simpler to view things as content (we expect to present this to the audience in the main flow of text), alternative text (this can be substituted for content), and metadata (we store this distinctly from the content and don't expect that it will be rendered as part of the main flow of text).  So <navtitle> , <searchtitle>, and <booktitlealt> (for example) are alternative text.   Making a distinction about alternative text changes the question from "is <navtitle> metadata?" to "do we want a switch to treat alternative text elements as metadata during processing?" which I think is easier to answer.  (I'd answer yes.) Graydon Saunders  Publishing Solutions Developer     Precision Content   Direct:  +1   (647)265-8500 x106   Email:   graydon@precisioncontent.com     www.precisioncontent.com     Unlock the Knowledge in Your Enterprise™ This email and any files transmitted with it are confidential and intended solely for the use of the individual or entity to whom they are addressed. If you are not the intended recipient you are notified that disclosing, copying, distributing or taking any action in reliance on the contents of this information is strictly prohibited.   Please notify us by return email if you have received this email in error.  ©2019, Precision Content Authoring Solutions Inc, Mississauga, Ontario, Canada From: dita@lists.oasis-open.org <dita@lists.oasis-open.org> on behalf of Kristen James Eberlein <kris@eberleinconsulting.com> Sent: 11 July 2019 14:18 To: DITA TC Subject: [dita] @lockmeta on <topicmeta>   This is an attribute that we might want to consider for changes in DITA 2.0. Here what the DITA 1.3 spec says: @lockmeta By default, metadata in the map supplements or overrides metadata that is specified at the topic level, unless the   @lockmeta   attribute of the   <topicmeta> element is set to "no". Allowable values are "yes", "no", and   Using the -dita-use-conref-target value . A couple of things: I'm not sure that we specify anywhere what our expectations for processors are about the differences between supplementing and overriding metadata. The DITA 1.3 element reference topic for <topicmeta> is ambiguous, since it implies that navigation titles are metadata, but whether navigation titles specified in maps are used depends on whether @locktitle is set to "yes". (Does @lockmeta also have an effect on navigation titles?) -- Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 622-1501; 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've always found @lockmeta to be a bit unclear and have largely implemented it only on a "pretty sure I know what was intended" basis. It's probably something we should consider either removing in 2.0, or pretty heavily redefining. If you look back through the history of the attribute ... In DITA 1.0 the attribute was declared in the grammar, but listed as undefined in the spec: http://docs.oasis-open.org/dita/v1.0/langspec/topicmeta.html In DITA 1.1 it was defined but pretty loosely : http://docs.oasis-open.org/dita/v1.1/OS/langspec/langref/topicmeta.html The general goal, as I remember / understood it, was based on a mental model that closely mapped how DITA Open Toolkit processing worked. When you publish something, you had to reconcile which metadata wins (that in the topic, or that in the map). Generally something in the map supplements / overrides what's in the topic, and this was a way to say "Even if something is hard coded in the topic, apply the metadata I've got here". The whole language around "replacing" only makes sense in that toolkit context where you actually have a file where things are added / removed / combined. DITA 1.2 and 1.3 were slightly clearly in describing what "yes" means -- "If you set this to yes, it means your metadata is locked, and you can't ignore it". I do think this whole idea of locked metadata is less relevant today than it was when originally imagined. As you can see in that original language, the premise was really based around a DITA-OT model (where metadata is "replaced" during a build). More recently, in DITA 1.2 and especially in DITA 1.3, we have treated metadata in the map as something associated with that specific context. You can do something with it (or not) based on that context, but we don't mandate whether or not a publication process would "replace" that context-based metadata with something else. So yeah - it went from declared-but-undefined in 1.0, to loosely defined, to ... still loosely defined even in 1.3. I'm not sure I've seen it used in real docs, and given how hard it is to talk about in the abstract, I'm not sure it's necessary. For the second part of your question -- the conflict that navigation titles comes out of how those turned from an attribute (in DITA 1.0 / 1.1) into an element in DITA 1.2. These were clearly not meant to be related in DITA 1.0 -- titles were controlled by @locktitle on the topic reference, while metadata was meant to be controlled by @lockmeta. It just happened that <navtitle> was added later into <topicmeta>, which added a bit of confusion. However, the 1.3 specification still clearly describes how titles are controlled by @locktitle (rather than @lockmeta). Robert D. Anderson DITA-OT lead and Co-editor DITA 1.3 specification Marketing Services Center E-mail: robander@us.ibm.com 11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA Kristen James Eberlein ---07/11/2019 01:18:56 PM---This is an attribute that we might want to consider for changes in DITA 2.0. Here what the DITA 1.3 From: Kristen James Eberlein <kris@eberleinconsulting.com> To: DITA TC <dita@lists.oasis-open.org> Date: 07/11/2019 01:18 PM Subject: [EXTERNAL] [dita] @lockmeta on <topicmeta> Sent by: <dita@lists.oasis-open.org> This is an attribute that we might want to consider for changes in DITA 2.0. Here what the DITA 1.3 spec says: @lockmeta By default, metadata in the map supplements or overrides metadata that is specified at the topic level, unless the @lockmeta attribute of the <topicmeta>element is set to "no". Allowable values are "yes", "no", and  Using the -dita-use-conref-target value . A couple of things: I'm not sure that we specify anywhere what our expectations for processors are about the differences between supplementing and overriding metadata. The DITA 1.3 element reference topic for <topicmeta> is ambiguous, since it implies that navigation titles are metadata, but whether navigation titles specified in maps are used depends on whether @locktitle is set to "yes". (Does @lockmeta also have an effect on navigation titles?) -- Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 622-1501; 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

Thanks for the background history. I think @lockmeta is a great candidate for removal in DITA 2.0. What do other voting members of the DITA TC think? Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 622-1501; kriseberlein (skype) On 7/15/2019 4:22 PM, Robert D Anderson wrote: I've always found @lockmeta to be a bit unclear and have largely implemented it only on a pretty sure I know what was intended basis. It's probably something we should consider either removing in 2.0, or pretty heavily redefining. If you look back through the history of the attribute ... In DITA 1.0 the attribute was declared in the grammar, but listed as undefined in the spec: http://docs.oasis-open.org/dita/v1.0/langspec/topicmeta.html In DITA 1.1 it was defined but pretty loosely : http://docs.oasis-open.org/dita/v1.1/OS/langspec/langref/topicmeta.html The general goal, as I remember / understood it, was based on a mental model that closely mapped how DITA Open Toolkit processing worked. When you publish something, you had to reconcile which metadata wins (that in the topic, or that in the map). Generally something in the map supplements / overrides what's in the topic, and this was a way to say Even if something is hard coded in the topic, apply the metadata I've got here . The whole language around replacing only makes sense in that toolkit context where you actually have a file where things are added / removed / combined. DITA 1.2 and 1.3 were slightly clearly in describing what yes means -- If you set this to yes, it means your metadata is locked, and you can't ignore it . I do think this whole idea of locked metadata is less relevant today than it was when originally imagined. As you can see in that original language, the premise was really based around a DITA-OT model (where metadata is replaced during a build). More recently, in DITA 1.2 and especially in DITA 1.3, we have treated metadata in the map as something associated with that specific context. You can do something with it (or not) based on that context, but we don't mandate whether or not a publication process would replace that context-based metadata with something else. So yeah - it went from declared-but-undefined in 1.0, to loosely defined, to ... still loosely defined even in 1.3. I'm not sure I've seen it used in real docs, and given how hard it is to talk about in the abstract, I'm not sure it's necessary. For the second part of your question -- the conflict that navigation titles comes out of how those turned from an attribute (in DITA 1.0 / 1.1) into an element in DITA 1.2. These were clearly not meant to be related in DITA 1.0 -- titles were controlled by @locktitle on the topic reference, while metadata was meant to be controlled by @lockmeta. It just happened that <navtitle> was added later into <topicmeta>, which added a bit of confusion. However, the 1.3 specification still clearly describes how titles are controlled by @locktitle (rather than @lockmeta). Robert D. Anderson DITA-OT lead and Co-editor DITA 1.3 specification Marketing Services Center E-mail: robander@us.ibm.com 11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA Kristen James Eberlein ---07/11/2019 01:18:56 PM---This is an attribute that we might want to consider for changes in DITA 2.0. Here what the DITA 1.3 From: Kristen James Eberlein <kris@eberleinconsulting.com> To: DITA TC <dita@lists.oasis-open.org> Date: 07/11/2019 01:18 PM Subject: [EXTERNAL] [dita] @lockmeta on <topicmeta> Sent by: <dita@lists.oasis-open.org> This is an attribute that we might want to consider for changes in DITA 2.0. Here what the DITA 1.3 spec says: @lockmeta By default, metadata in the map supplements or overrides metadata that is specified at the topic level, unless the @lockmeta attribute of the <topicmeta>element is set to no . Allowable values are yes , no , and  Using the -dita-use-conref-target value . A couple of things: I'm not sure that we specify anywhere what our expectations for processors are about the differences between supplementing and overriding metadata. The DITA 1.3 element reference topic for <topicmeta> is ambiguous, since it implies that navigation titles are metadata, but whether navigation titles specified in maps are used depends on whether @locktitle is set to yes . (Does @lockmeta also have an effect on navigation titles?) -- Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 622-1501; 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'm pretty sure I have never used @lockmeta. The only reason I could imagine caring if it went away would be if someone came along with an existing and compelling usage for it. mag On Mon, Jul 15, 2019 at 1:36 PM Kristen James Eberlein < kris@eberleinconsulting.com > wrote: Thanks for the background history. I think @lockmeta is a great candidate for removal in DITA 2.0. What do other voting members of the DITA TC think? Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 622-1501; kriseberlein (skype) On 7/15/2019 4:22 PM, Robert D Anderson wrote: I've always found @lockmeta to be a bit unclear and have largely implemented it only on a "pretty sure I know what was intended" basis. It's probably something we should consider either removing in 2.0, or pretty heavily redefining. If you look back through the history of the attribute ... In DITA 1.0 the attribute was declared in the grammar, but listed as undefined in the spec: http://docs.oasis-open.org/dita/v1.0/langspec/topicmeta.html In DITA 1.1 it was defined but pretty loosely : http://docs.oasis-open.org/dita/v1.1/OS/langspec/langref/topicmeta.html The general goal, as I remember / understood it, was based on a mental model that closely mapped how DITA Open Toolkit processing worked. When you publish something, you had to reconcile which metadata wins (that in the topic, or that in the map). Generally something in the map supplements / overrides what's in the topic, and this was a way to say "Even if something is hard coded in the topic, apply the metadata I've got here". The whole language around "replacing" only makes sense in that toolkit context where you actually have a file where things are added / removed / combined. DITA 1.2 and 1.3 were slightly clearly in describing what "yes" means -- "If you set this to yes, it means your metadata is locked, and you can't ignore it". I do think this whole idea of locked metadata is less relevant today than it was when originally imagined. As you can see in that original language, the premise was really based around a DITA-OT model (where metadata is "replaced" during a build). More recently, in DITA 1.2 and especially in DITA 1.3, we have treated metadata in the map as something associated with that specific context. You can do something with it (or not) based on that context, but we don't mandate whether or not a publication process would "replace" that context-based metadata with something else. So yeah - it went from declared-but-undefined in 1.0, to loosely defined, to ... still loosely defined even in 1.3. I'm not sure I've seen it used in real docs, and given how hard it is to talk about in the abstract, I'm not sure it's necessary. For the second part of your question -- the conflict that navigation titles comes out of how those turned from an attribute (in DITA 1.0 / 1.1) into an element in DITA 1.2. These were clearly not meant to be related in DITA 1.0 -- titles were controlled by @locktitle on the topic reference, while metadata was meant to be controlled by @lockmeta. It just happened that <navtitle> was added later into <topicmeta>, which added a bit of confusion. However, the 1.3 specification still clearly describes how titles are controlled by @locktitle (rather than @lockmeta). Robert D. Anderson DITA-OT lead and Co-editor DITA 1.3 specification Marketing Services Center E-mail: robander@us.ibm.com 11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA Kristen James Eberlein ---07/11/2019 01:18:56 PM---This is an attribute that we might want to consider for changes in DITA 2.0. Here what the DITA 1.3 From: Kristen James Eberlein <kris@eberleinconsulting.com> To: DITA TC <dita@lists.oasis-open.org> Date: 07/11/2019 01:18 PM Subject: [EXTERNAL] [dita] @lockmeta on <topicmeta> Sent by: <dita@lists.oasis-open.org> This is an attribute that we might want to consider for changes in DITA 2.0. Here what the DITA 1.3 spec says: @lockmeta By default, metadata in the map supplements or overrides metadata that is specified at the topic level, unless the @lockmeta attribute of the <topicmeta>element is set to "no". Allowable values are "yes", "no", and Using the -dita-use-conref-target value . A couple of things: I'm not sure that we specify anywhere what our expectations for processors are about the differences between supplementing and overriding metadata. The DITA 1.3 element reference topic for <topicmeta> is ambiguous, since it implies that navigation titles are metadata, but whether navigation titles specified in maps are used depends on whether @locktitle is set to "yes". (Does @lockmeta also have an effect on navigation titles?) -- Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 622-1501; 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