[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [dita] Terminology issues: use of @attribute
I consciously use the most formal notation when writing about both
elements and attributes:
* The <step> element
* The @conref attribute
This is in part because of my years working at IBM -- IBM style
mandates always using angle brackets--but also because of feedback that
I have gotten in the past couple of years teaching workshops about DITA
-- most participants found the formal notation to be the easiest to read
and understand.
Kris
Tony Self wrote:
> I agree with you, Robert, that the shortcut of using @ makes it difficult for a non-technical reader to understand.
>
> In my own documentation, I have been using the synph element when describing elements and attributes, as I thought it was the closest semantic fit. My rationale is that elements and attribute names are part of the syntax of XML.
>
> If I am writing about an element (or tag) literally, I use codeph; my thinking being that I am actually quoting a code snippet. I include the tag delimiters ("<" and ">") within the codeph.
>
> Tony Self
>
>
> -----Original Message-----
> From: Robert D Anderson [mailto:robander@us.ibm.com]
> Sent: Friday, 4 December 2009 8:35 AM
> To: Bruce Nevin (bnevin)
> Cc: DITA TC; Kristen James Eberlein
> Subject: RE: [dita] Terminology issues: use of @attribute
>
> I'll leave the definitions to others, but I wanted to address this item:
>
>
>> BTW, I see little consistency in this use of @; some topics say "the
>> value of @foo" and others say "the value of the <keyword>foo</
>> keyword> attribute". I followed the latter model before noticing this.
>>
>
> In editing the language spec for 1.2, I noticed that this was not
> consistent, and many reviewers asked to remove the @ value. First, it was
> often already indicated that the value was an attribute (Attributes such as
> @this and @that...). Second, the notation is meaningless to many less
> technical readers. So, I tried to always refer to "Attribute this" rather
> than "@this".
>
> As for putting attribute names in a keyword - I think there is less
> consistency there, at least in the language spec - I did not do a pass over
> it trying to unify the values. Some used <keyword> around the name, some
> did not. The formatters used to create drafts so far do not add any styling
> to keyword, so it is difficult to notice the inconsistency unless scanning
> the source.
>
> Robert D Anderson
> IBM Authoring Tools Development
> Chief Architect, DITA Open Toolkit
>
> "Bruce Nevin (bnevin)" <bnevin@cisco.com> wrote on 12/03/2009 03:39:47 PM:
>
>
>> "Bruce Nevin (bnevin)" <bnevin@cisco.com>
>> 12/03/2009 03:39 PM
>>
>> To
>>
>> "Kristen James Eberlein" <kris@eberleinconsulting.com>
>>
>> cc
>>
>> "DITA TC" <dita@lists.oasis-open.org>
>>
>> Subject
>>
>> RE: [dita] Terminology issues: Linking and addressing terms?
>> Referencing and referenced element?
>>
>> Just one slip:
>> An element that references another DITA element by specifying an
>> addressing [element ==> attribute].
>> I do agree that examples are very helpful, but personally, I think
>> they belong in the more detailed topics where they are in fact
>> given. But that's just me, and if others feel the need, then ipso
>> facto the need is there. Examples are not unheard of in definitions.
>> Or as an alternative, could we link to a topic which provides
>> examples and further links? Or is that not kosher? Something like
>> the following:
>>
>> referenced element
>> An element that is referenced by another DITA element. For examples, see
>> Title of topic. See also referencing element.
>>
>> The phrase "an address" seems too inspecific here:
>>
>> addressing attribute
>> An attribute, such as @conref, @conkeyref, @keyref, and @href, that
>> can be used to specify the address of a DITA element.
>> [or, maybe a little more plainly and with less repetition of words:
>> to specify the location of a DITA element]
>>
>> BTW, I see little consistency in this use of @; some topics say "the
>> value of @foo" and others say "the value of the <keyword>foo</
>> keyword> attribute". I followed the latter model before noticing this.
>>
>> /B
>>
>> From: Kristen James Eberlein [mailto:kris@eberleinconsulting.com]
>> Sent: Thursday, December 03, 2009 2:48 PM
>> Cc: DITA TC
>> Subject: Re: [dita] Terminology issues: Linking and addressing
>> terms? Referencing and referenced element?
>>
>
>
>> If we are defining terms, we need to follow conventions for
>> glossaries. That means that a definition-list entry should be a
>> definition. How about the following? And is including examples
>> something that we want to do?
>>
>> Bruce, I do agree that these two entities -- referencing element and
>> referenced element -- always exist as a pair; neither can exist as
>> an autonomous entity ...
>> referenced element
>> An element that is referenced by another DITA element. See also
>> referencing element.
>> Example
>> The following code sample is from the installation-reuse.dita topic.
>> The <step> element that it contains is a referenced element; other
>> DITA topics can reference the <step> element by using the @conref
>>
> attribute.
>
>> <step id="run-startcmd-script">
>> <cmd>Run the startcmd script that is applicable to your
>> operating-system environment.</cmd>
>> </step>
>> referencing element
>> An element that references another DITA element by
>> specifying an addressing element. See also referenced element and
>> addressing attribute.
>> Example
>> The following <step> element is a referencing element. It uses the
>> @conref attribute to reference a <step> element in the installation-
>> reuse.dita topic.
>> <step conref="installation-reuse.dita#reuse/run-startcmd-script>
>> <cmd/>
>> </step>
>> addressing attribute
>> An attribute, such as @conref, @conkeyref, @keyref, and @href, that
>> can be used to specify an address.
>> Kris
>>
>> Bruce Nevin (bnevin) wrote:
>> Kris wrote:
>> My analysis of the problem is:
>> The two definitions are circular.
>> We are trying to cram way too much information into a definition
>> These two definitions are reciprocal because together they define a
>> relationship. I don't find that dizzying, but that may be because
>> (in linguistics) I'm used to thinking of relationships which are not
>> easy to TalkAboutAllAtOnceInOneExpression so we talk about one
>> aspect at a time. When I see a reciprocal definition I pop up a
>> level to think about the relationship. But that doesn't make it good
>> clear writing practice for every reader!
>>
>> I agree with simplifying by putting the list of attributes
>> elsewhere. I said that the addressing attributes "include" those
>> listed as a hedge against incomplete recollection. Another tack
>> would be to say "the most important of the addressing attributes
>>
> are ...".
>
>> Jeff, I dropped @codebase from the list because it (optionally)
>> supports the addressing attributes on <object>, but does not itself
>> address a referenced element. But under the last proposal above we
>> could drop the entire <object> set from the list.
>>
>> I agree that we should not use "target" in any form. Nominal and
>> verbal uses are also equivocal over the two points of view -- the
>> target of the link vs. the target of the content. We know we're
>> talking about a link addressing a "target" element but in some
>> contexts readers think of content being reused at a "target"
>> element's location. (I don't think it's an audience problem so much
>> as a context problem. We have seen both senses in the spec. and the ref.)
>>
>> Going back to the first point, suppose we start each definition by
>> asserting the relationship explicitly. Maybe something like this:
>>
>> Referencing element
>> Content reuse requires a relationship between a referencing element
>> and a referenced element. An attribute on the referencing element is
>> set to the address of the referenced element.
>> Example:
>> ...
>> See referenced element; addressing attribute.
>>
>> Referenced element
>> Content reuse requires a relationship between a referencing element
>> and a referenced element. The address of the referenced element is
>> specified in the value of an attribute on the referencing element.
>> Example:
>> ...
>> See referencing element; addressing attribute.
>> ______________________________________________
>>
>> I assume here that we omit the <object> attributes from the list.
>>
>> We don't have to say everything in each single definition. Although
>> DITA dogma says a glossary entry is a concept, definitions seldom
>> stand alone. I simplified "addressing attribute" to "attribute"
>> because "see addressing attribute" provides the necessary
>> information if the reader wants it.
>>
>> /Bruce
>>
>> From: Ogden, Jeff [mailto:jogden@ptc.com]
>> Sent: Thursday, December 03, 2009 12:12 PM
>> To: Kara Warburton; Joann Hackos
>> Cc: Bruce Nevin (bnevin); DITA TC; Eliot Kimber; Kristen James Eberlein
>> Subject: RE: [dita] Terminology issues: Linking and addressing
>> terms? Referencing and referenced element?
>>
>
>
>> The list of “addressing” attributes isn’t complete. It might be
>> better to skip the list of addressing attributes and just make the
>> definition something like this:
>> An element that targets another DITA element by using an addressing
>> attribute such as @href, @conref, @keyref, and @conkeyref.
>> More important than the definitions is using the terminology
>> correctly elsewhere in the DITA spec. and avoiding the terms source
>> and target.
>> But if we feel compelled to include a list of all of the
>> “addressing” attributes, then as mentioned in previous e-mails, the
>> list needs to include at least:
>> @href, @conref, @keyref, @conkeyref
>> @conrefend
>> @mapref, @longdescref, and @anchorref
>> and possibly @archive, @classid, @codebase, and @data (all on <object>)
>> -Jeff
>> From: Kara Warburton [mailto:kara@ca.ibm.com]
>> Sent: Thursday, December 03, 2009 9:47 AM
>> To: Joann Hackos
>> Cc: Bruce Nevin (bnevin); DITA TC; Eliot Kimber; Ogden, Jeff;
>> Kristen James Eberlein
>> Subject: Re: [dita] Terminology issues: Linking and addressing
>> terms? Referencing and referenced element?
>> A few suggestions if you are open to something cleaner and which
>> adheres to terminology best practices. Since the 2nd defintion
>> proposed by Kristen already contained the word "target", I tried
>> this as the verb in the definitions rather than "address" which I
>> find ambiguous. The main change is not to repeat what the
>> referencing element does in the definition of the referenced
>> element. Also, please lower case the terms. There should also be a
>> cross reference in both entries.
>>
>> I also would prefer to remove the list of attributes if they can be
>> grouped into a definition elsewhere as suggested by Kirsten. I've
>> modelled that below in the 2nd proposal but I don't know enough
>> about these attributes to know if it is correct.
>>
>> First proposal - attributes listed in definition of referencing element
>>
>> referencing element
>> An element that targets another DITA element by using one of the
>> following attributes:
>> @ conkeyref
>> @conref
>> @href
>> @keyref
>> See also referenced element.
>>
>> referenced element
>> An element that is the target of another DITA element. See also
>> referencing element.
>> Second proposal - separating attributes to their own entry
>>
>> referencing element
>> An element that targets another DITA element by using an addressing
>> attribute. See also referenced element.
>>
>> referenced element
>> An element that is the target of another DITA element. See also
>> referencing element.
>>
>> addressing attribute
>> One of the following attributes, which are used by a referencing
>> element to target a referenced element:
>> @ conkeyref
>> @conref
>> @href
>> @keyref
>>
>> Kara Warburton
>> IBM Terminology
>> Office: 905-413-2170
>> Mobile: 905-717-8014
>>
>> IBM terminology: http://w3.ibm.com/standards/terminology
>> Education about IBM terminology: http://w3.tap.ibm.com/medialibrary/
>> media_set_view?id=4981
>>
>> [image removed] Joann Hackos ---12/03/2009 08:47:07 AM---I really
>> think we need examples here ― the definitions are too circular,
>> which isn’t surprising cons
>>
>> [image removed]
>> From:
>>
>> [image removed]
>> Joann Hackos <joann.hackos@comtech-serv.com>
>>
>> [image removed]
>> To:
>>
>> [image removed]
>> Kristen James Eberlein <kris@eberleinconsulting.com>, "Bruce Nevin
>>
> (bnevin)"
>
>> <bnevin@cisco.com>
>>
>> [image removed]
>> Cc:
>>
>> [image removed]
>> "Ogden, Jeff" <jogden@ptc.com>, Eliot Kimber <ekimber@reallysi.com>, DITA
>>
> TC
>
>> <dita@lists.oasis-open.org>
>>
>> [image removed]
>> Date:
>>
>> [image removed]
>> 12/03/2009 08:47 AM
>>
>> [image removed]
>> Subject:
>>
>> [image removed]
>> Re: [dita] Terminology issues: Linking and addressing terms?
>> Referencing and referenced element?
>>
>>
>>
>>
>> I really think we need examples here — the definitions are too
>> circular, which isn’t surprising considering the concept is
>> circular. You need three elements to make a concept understandable:
>> a definition, an example, and a non-example. We have the first part,
>> but are missing the example and maybe the non-example.
>>
>> I recommend an example — that would easily clarify the idea we’re
>> trying to convey.
>> JoAnn
>>
>>
>> On 12/3/09 5:32 AM, "Kristen James Eberlein" <kris@eberleinconsulting.com
>>
>>> wrote:
>>>
>> Ouch. I think we have a problem here. I look at the two definitions
>> and find them VERY difficult to mentally parse. If I have problems
>> with them -- and I've been spending most of the last six months
>> working on DITA full-time, then I think a lot of other people will also.
>>
>> My analysis of the problem is:
>> 1. The two definitions are circular.
>> 2. We are trying to cram way too much information into a definition
>> Here's what I put in the terminology.dita topic yesterday morning as
>> a temporary placeholder:
>>
>> Referencing element
>> An element which specifies one of the following DITA attributes in
>> order to address another DITA element:
>> @conkeyref attribute
>> @conref attribute
>> @href attribute
>> @keyref attribute
>> Referenced element
>> An element that is referenced by another DITA element (the
>> referencing element). The referencing element specifies one of the
>> following DITA attributes:
>> @conkeyref attribute
>> @conref attribute
>> @href attribute
>> @keyref attribute
>> The referenced element is the target of the DITA attribute.
>>
>> Obviously I didn't have a complete list of the relevant attributes ...
>>
>> Now I have to go and look up information about attributes that are
>> unfamiliar to me (@mapref, @longdescref, @anchorref), and well as
>> the <object> element :(
>>
>> I do find "addressing attribute" to be a potentially useful and
>> descriptive term for the particular groups of attributes. Some of
>> these attributes fall into the "id-atts attribute group"; one of my
>> review comments during the last review was to suggest that we use
>> more descriptive names for the groups of attributes, rather than the
>> names of the literal parameter entities that are used to organize
>> the attribute declarations. We won't be doing this for DITA 1.2, but
>> it's definitely something that we need to consider for DITA 1.3. See
>> http://wiki.oasis-open.org/dita/LangRefAttributes if you want to
>> follow the review thread.
>>
>> Kris
>>
>> Bruce Nevin (bnevin) wrote:
>>
>> Then maybe this rev. 3 has got it:
>>
>> Referencing element
>> An element that identifies a referenced element in the value of an
>> addressing attribute. The addressing attributes include href,
>> conref, conrefend, keyref, conkeyref, mapref, longdescref, and
>> anchorref. See referenced element. This term may also be used for an
>> <object> element insofar as its archive, classid, and data
>> attributes are used to specify the data, resources, and
>> implementation of a non-XML object.
>>
>> Referenced element
>> The element that a referencing element identifies in the value of
>> one of the addressing attributes. The addressing attributes include
>> href, conref, conrefend, keyref, conkeyref, mapref, longdescref, and
>> anchorref. See referencing element.
>>
>> ø¤º°`°º¤ø,¸¸,ø¤º°`°º¤ø,¸¸,ø¤º°`°º¤ø
>>
>> Does this hook us into making "addressing attribute" a defined term?
>> I hope we can stop with defining it locally like this.
>>
>> I don't know if we actually use source/target anywhere that we talk
>> about <object> (we don't seem to in the lang ref), but someone might
>> use referring/referenced in the future. I omitted @codebase since it
>> only sets a base URL to which the other URLs are relative (when that
>> base URL is other than that of the current document).
>>
>> Question:
>> The "text description of the graphic or object" that @longdescref
>> references--is that text contained in a DITA element? If not (or if
>> not necessarily) it might call for an "also used" sentence like that
>> for @archive, etc.
>>
>>
>
>
>> -----Original Message-----
>> From: Ogden, Jeff [mailto:jogden@ptc.com]
>> Sent: Wednesday, December 02, 2009 4:44 PM
>> To: Eliot Kimber; Bruce Nevin (bnevin); Kristen James Eberlein
>> Cc: dita
>> Subject: RE: [dita] Terminology issues: Linking and
>> addressing terms? Referencing and referenced element?
>>
>> Bruce Nevin wrote:
>>
>> one of the following attributes: href, conref, keyref,
>>
>> conkeyref ...
>>
>> [complete the list].
>>
>> Eliot Kimber wrote:
>>
>> Add conrefend and I think the list of addressing attributes is
>>
>> complete.
>>
>> These need to be on the list too: @mapref, @longdescref, and
>> @anchorref
>>
>> I'm less sure about: @archive, @classid, @codebase, and
>> @data all on <object>
>>
>> And without more research, I can't be sure that there aren't
>> a few more tucked away that I don't remember. The above is
>> everything from a list I made and last updated in June 2007.
>>
>> -Jeff
>>
>
>
>> -----Original Message-----
>> From: Eliot Kimber [mailto:ekimber@reallysi.com]
>> Sent: Wednesday, December 02, 2009 12:59 PM
>> To: Bruce Nevin (bnevin); Kristen James Eberlein
>> Cc: dita
>> Subject: Re: [dita] Terminology issues: Linking and
>>
>> addressing terms?
>>
>> Referencing and referenced element?
>>
>> On 12/2/09 11:05 AM, "Bruce Nevin (bnevin)"
>>
>> <bnevin@cisco.com> <mailto:bnevin@cisco.com> wrote:
>>
>> Here's a straw man for starters:
>>
>> Referencing element
>> The element which identifies its referenced element in
>>
>> the value of
>>
>> one
>>
>> of the following attributes: href, conref, keyref, conkeyref ...
>> [complete the list]. See referenced element.
>>
>> Referenced element
>> The element which is identified in a referencing element by the
>>
>> value
>>
>> of
>>
>> one of the following attributes: href, conref, keyref,
>>
>> conkeyref ...
>>
>> [complete the list]. See referencing element.
>>
>> Whale away at it!
>>
>> C/which/that/
>>
>> Add conrefend and I think the list of addressing attributes is
>>
>> complete.
>>
>> Cheers,
>>
>> E.
>> --
>> Eliot Kimber
>> Senior Solutions Architect
>> "Bringing Strategy, Content, and Technology Together"
>> Main: 610.631.6770
>> www.reallysi.com <http://www.reallysi.com>
>> www.rsuitecms.com <http://www.rsuitecms.com>
>>
>>
>>
>
>
>> ---------------------------------------------------------------------
>>
>> 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
>>
>>
>
>
>> ---------------------------------------------------------------------
>> 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
>>
>>
>>
>
>
>> ---------------------------------------------------------------------
>> 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
>>
>
>
> ---------------------------------------------------------------------
> 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
>
>
>
>
>
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]