OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [dita] Terminology issues: Linking and addressing terms? Referencingand referenced element?


Hi Kris,

I like them.
Except please correct "addressing element" to "addressing attribute", and add the see also terms.

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

Inactive hide details for Kristen James Eberlein ---12/03/2009 02:48:56 PM---If we are defining terms, we need to follow convenKristen James Eberlein ---12/03/2009 02:48:56 PM---If we are defining terms, we need to follow conventions for glossaries. That means that a definition


From:

Kristen James Eberlein <kris@eberleinconsulting.com>

To:


Cc:

DITA TC <dita@lists.oasis-open.org>

Date:

12/03/2009 02:48 PM

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
      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
      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

      Inactive hide details for Joann Hackos ---12/03/2009 08:47:07 AM---I really think we need examples here ― the definitions are 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

From:

Joann Hackos
<joann.hackos@comtech-serv.com>

To:

Kristen James Eberlein
<kris@eberleinconsulting.com>, "Bruce Nevin (bnevin)" <bnevin@cisco.com>

Cc:

"Ogden, Jeff"
<jogden@ptc.com>, Eliot Kimber <ekimber@reallysi.com>, DITA TC <dita@lists.oasis-open.org>

Date:

12/03/2009 08:47 AM

Subject:

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.

                              ---------------------------------------------------------------------

                                      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]