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: use of @attribute


I think that leaving the @ (in untagged text) would leave a mechanism for later search and replace, as Kris suggested.

 

Is the use of “pleonastic” instead of “redundant” floccinaucinihilipilification?

 

Tony Self

 

 

From: Bruce Nevin (bnevin) [mailto:bnevin@cisco.com]
Sent: Saturday, 5 December 2009 7:21 AM
To: Kristen James Eberlein
Cc: tself@hyperwrite.com; Robert D Anderson; DITA TC
Subject: RE: [dita] Terminology issues: use of @attribute

 

OK. For now, no DITA tags around the attribute name itself, then, and the redundancy (pleonasm) of the word "attribute" plus @ meaning "attribute". Decision to be made later as part of a general stylesheet for spec/ref authors.

 

JoAnn, if the audience is adopters I would agree, but if the audience is coders, I see no problem using code in sentences. In any case, this use of @ isn't even code (computer code). It's a kind of quotation device, like the lt/gt brackets in <element>. Is it objectionable to say "an attribute in the <map> element"? (Note that this also expresses the same information twice.)

 

pleonasm

pleonastic, adj. pleonastically, adv.

/plee"euh naz'euhm/, n.

1. the use of more words than are necessary to express an idea; redundancy.

2. an instance of this, as free gift or true fact.

3. a redundant word or expression.

[1580-90; < LL pleonasmus < Gk pleonasmós redundancy, surplus, deriv. of pleonázein to be or have more than enough, itself deriv. of pleíon more (see PLEO-)]

 


From: Kristen James Eberlein [mailto:kris@eberleinconsulting.com]
Sent: Friday, December 04, 2009 1:14 PM
To: Bruce Nevin (bnevin)
Cc: tself@hyperwrite.com; Robert D Anderson; DITA TC
Subject: Re: [dita] Terminology issues: use of @attribute

What does pleonastic mean?

I don't think this is a high-priority issue, either. Long run, it would be nice to have it settled, so that (1) the rendered output was consistent for readers, and (2) the topics were uniformly tagged. But I am much more focused on content issues.


I'd suggest using the following form:

When the @conref attribute is used alone ...
 
This would give us uniform rendering, and it also would be easiest to run search-and-replace operations later if or when we have a consensus on this issue.

Kris

Bruce Nevin (bnevin) wrote:

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]