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