[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita] Terminology issues: use of @attribute
I prefer When the conref attribute is used alone ...
Let's avoid code in sentences.
JoAnn
JoAnn Hackos PhD
President
Comtech Services, Inc.
joann.hackos@comtech-serv.com
Skype joannhackos
-----Original Message-----
From: Bruce Nevin (bnevin) [mailto:bnevin@cisco.com]
Sent: Friday, December 04, 2009 10:59 AM
To: Kristen James Eberlein; tself@hyperwrite.com
Cc: Robert D Anderson; DITA TC
Subject: RE: [dita] Terminology issues: use of @attribute
So which form should I use in work that I am doing now?
When @conref is used alone ...
When @<keyword>conref</keyword> is used alone ...
When <keyword>@conref</keyword> is used alone ...
When @<synph>conref</synph> is used alone ...
When <synph>@conref</synph> is used alone ...
When the conref attribute is used alone ...
When the <keyword>conref</keyword> attribute is used alone ...
When the @conref attribute is used alone ...
When the @<keyword>conref</keyword> attribute is used alone ...
When the <keyword>@conref</keyword> attribute is used alone ...
When the <keyword>conref</keyword> attribute is used alone ...
When the <synph>conref</synph> attribute is used alone ...
When the <synph>conref</synph> attribute is used alone ...
When the @<synph>conref</synph> attribute is used alone ...
When the <synph>@conref</synph> attribute is used alone ...
...
Not that all of these occur, and not that we will change all the content to one form for 1.2, but it would be nice for new work not to require such change when we do get around to it. (Not to mention that the spec might exemplify good practice.)
For me, "the @conref attribute" (with or without <keyword> or <synph> or the like) is as pleonastic as "El Camino Real Road", "hot water heater", and various forms of RAS syndrome or PNS syndrome (q.v.).
If we don't have consensus, let it not distract from real work, leave it for 1.3 guidelines and editor take the hindmost.
> -----Original Message-----
> From: Kristen James Eberlein [mailto:kris@eberleinconsulting.com]
> Sent: Thursday, December 03, 2009 8:34 PM
> To: tself@hyperwrite.com
> Cc: 'Robert D Anderson'; 'DITA TC'
> 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.ph
> >> p
> >>
> >>
> >
> >
> >>
> ---------------------------------------------------------------------
> >> 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.ph
> >> p
> >>
> >>
> >>
> >
> >
> >>
> ---------------------------------------------------------------------
> >> 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.ph
> >> p
> >>
> >
> >
> >
> ---------------------------------------------------------------------
> > 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_workgr
> oups.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]