And I'm 200% in favor of simplifying the rules for resolving
variable text.
Yes, I've seen a lot of variety in the markup people use in key
definitions. I think people tended to use whatever markup patterns
were in place at their company. And often templates that authors
use to create new topics are not updated with new releases of
DITA, thus carrying on practices such as nesting <keywords>
within <metadata> ...
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)
On 12/5/2019 10:10 PM, Robert D
Anderson wrote:
For me -- 100% all in favor of simplifying the
key text resolution rules, even if I expect that it may end up
a little bit more complex than hoped.
The one thing most likely to complicate things is
that quite a lot of people today seem to use a lot of nesting
to create <keyword> for their variable text. I'm not
sure if this should still be allowed, or if this should be
migrated to keytext:
<keydef keys="example">
<topicmeta>
<keywords>
<keyword>Reusable text</keyword>
</keywords>
</topicmeta>
</keydef>
I've also seen that where <keywords> is
further nested inside of <metadata>, a legacy of early
DITA versions that required the extra container.
There's no doubt that using <keytext> would
be simpler, but the migration might be complicated by cases
that really do want to retain the keyword. I suppose that
could be another case like you raised on the call, where the
safest migration could just create two copies and leave any
cleanup for later:
<keydef keys="example">
<topicmeta>
<keytext>Reusable
text</keytext>
<keywords>
<keyword>Reusable text</keyword>
</keywords>
</topicmeta>
</keydef>
Robert D. Anderson
DITA-OT lead and Co-editor DITA 1.3
specification
Marketing Services Center |
Chris Nitchie ---12/05/2019 04:58:24
PM---Thanks, Robert. Another question. Currently, the rules
for determining where to pull effective text
From: Chris
Nitchie <chris.nitchie@oberontech.com>
To: Robert
D Anderson <robander@us.ibm.com>
Cc: "DITA
TC (dita@lists.oasis-open.org)"
<dita@lists.oasis-open.org>
Date: 12/05/2019
04:58 PM
Subject: [EXTERNAL]
Re: [dita] Question about include element and existing
specializations
Sent by: <dita@lists.oasis-open.org>
Thanks, Robert.
Another question. Currently, the rules for
determining where to pull effective text for key references is
incredibly complex. The <linktext> element is essentially
a fallback. See http://docs.oasis-open.org/dita/dita/v1.3/errata02/os/complete/part3-all-inclusive/archSpec/base/processing-keyref-for-text.html#processing_key_references.
With the addition of a new base element
explicitly for specifying key reference text, how does the TC
feel about scrapping the current rules in favor using
<keytext> if present, <linktext> if not, and normal
title determination rules (title of referenced topic, etc.)? It
complicates migration but simplifies keyref resolution
considerably.
Chris
From: Robert
D Anderson <robander@us.ibm.com>
Date: Wednesday, December 4,
2019 at 9:37 AM
To: Chris Nitchie
<chris.nitchie@oberontech.com>
Cc: "DITA TC
(dita@lists.oasis-open.org)" <dita@lists.oasis-open.org>
Subject: RE: [dita] Question
about include element and existing specializations
I assumed it was oversight for coderef, because
it's more or less required there for some cases.
For svgref / mathmlref I think I'd prefer to add it and stay
in sync with the base. It's not going to hurt anything and
there's no requirement to use it, but it could be useful in
cases where you're doing something odd, just as with any
reference to an XML file from the base <include>
element.
For <fallback> -- I think it probably makes sense to add
it, unless someone has an objection.
Robert D. Anderson
DITA-OT lead and Co-editor DITA 1.3
specification
Marketing Services Center |
Chris Nitchie ---12/04/2019 07:46:15
AM---The lack of <fallback> in the specializations was
an oversight on my part; I was focused on backward
From: Chris Nitchie
<chris.nitchie@oberontech.com>
To: Robert D Anderson
<robander@us.ibm.com>, "DITA TC
(dita@lists.oasis-open.org)" <dita@lists.oasis-open.org>
Date: 12/04/2019 07:46 AM
Subject: [EXTERNAL] Re: [dita] Question
about include element and existing specializations
Sent by: <dita@lists.oasis-open.org>
The lack of <fallback> in the specializations was an
oversight on my part; I was focused on backwards compatibility
and hadn't thought this part through. I don't have a problem
adding it to those. I also failed to add @encoding to
<coderef>. I'm not sure whether it should be added to
<svgref> or <mathmlref> as, being XML-reference
elements, encoding handling follows normal XML parsing rules
(i.e. it should come from the <?xml?> PI in the referenced
file).
Chris
From: <dita@lists.oasis-open.org>
on behalf of Robert D Anderson <robander@us.ibm.com>
Date: Tuesday, December 3,
2019 at 9:10 PM
To: "DITA TC
(dita@lists.oasis-open.org)" <dita@lists.oasis-open.org>
Subject: [dita] Question
about include element and existing specializations
Proposal #8 to add the <include> element
also covered an update to coderef, svgref, and mathmlref so
that they are based on <include>.
I've been working on integrating that change into the
technical content specification this evening and ran into a
question.
The proposal mentioned adding @parse to those three (with
default values), but overlooked adding the other new attribute
@encoding from the new base element. This pretty clearly seems
to be an oversight (no reason to exclude it), so I've put that
onto the three existing elements.
One question I'm wondering about -- with these three
currently-empty elements now based on <include>, they
could also allow the nested <fallback> element for cases
where backup behavior is needed.
Should that element be added as a child to those three, or
should they be left as they are today? I'm not sure if this
was an oversight in the proposal, or was explicitly left out.
Thanks,
Robert D. Anderson
DITA-OT lead and Co-editor DITA 1.3
specification
Marketing Services Center |
The content of this email and any attached
files are intended for the recipient specified in this message
only. It may contain information that is confidential,
proprietary, privileged, and/or exempt from disclosure under
applicable law. It is strictly forbidden to share any
part of this message with any third party or rely on any of its
contents, without the written consent of the sender. If you
received this message by mistake, please reply to this message
and follow with deletion of the original message, any copies and
all attachments, so that Oberon Technologies can ensure such a
mistake does not occur in the future.
|