Review C items: Short description for <cite>

[Kristen James Eberlein <kris@eberleinconsulting.com>]

Lots of comments about the short description for <cite>. We started the review with the short description reading: "A citation is the name or the title of a bibliographic resource." Below is the discussion from DITAweb:

I honestly find "title of a bibliographic resource" a bit restrictive. When I see the word "bibliographic" I think that means I have to have some collection of references listed in my document somewhere. I generally think of cite as just a reference to a title of another document or resource. I might also think that I can't use this element unless I have some fancy other thing set up. If I don't have the DITA APPROVEDâ bilbiography that can be referenced by a <cite> is it worth using this element? Or maybe I'm just haunted by MLA manuals.	zlawson	new	comment	5/12/2021 01:35:39
A couple of considerations here: We don't want to exclude a new type of "bibliographic resourse" by providing a list of items. My personal hope is that people would use cite for all the sorts of things that are referenced in bibliographies: books, articles, CDs, videos ... We cannot use the phrase "another document or resource" here. For implementors consulting the spec (rather than authors seeing the shortdesc as a pop-up or hovertext when authoring), "document or resource" has a very different meaning! We do prioritize the audiences when it comes to the shortdesc; the needs of implementors comes before those of authors. If you can think of a better way to word the shortdesc, I'm all ears! ------------ I did a little Googling on "citation." Wikipedia says "a bibliographic citation isÂÂa reference to a book, article, web page, or other published item." Maybe we could state "A citation is the name or title of a book, article, Web page, audio or video recording, or other published item." But, I'll be honest, I don't like it: I think it lists too many items, and a reader is going to be just as likely to think "my thing" doesn't fit into this category. It raised the whole issue of whether something is published or not. And changing "published item to simply "item" would tell people that citation can be used for the name of anything!	keberlein	updated	comment	5/12/2021 13:52:21
A citation is the title of a resource outside the scope of the content, for example the title of a different manual, the name of a blog, or movie title. Probably not in the right language for the spec.	zlawson	new	comment	5/12/2021 23:02:39
I tend to agree with Zoe here. I have seen <cite> being used by our authors when they refer to a specific "manual" that is outside the scope of the DITA map referencing their particular topic. Since xrefing across DITA maps is discouraged, they'd like to mark this as an external resource of interest (with the processing expectation of getting it rendered in italic). So I also think that the actual usage of this element is broader than just targeting a bibliographic resource.	fwegmann	new	comment	5/12/2021 21:24:29
I'm sorry, Kris, I read your comment after saving mine. I see the point of something being published or even not. But maybe something along this line could help: "A citation is the name or title referencing a piece of work such as a bibliographic resource."	fwegmann	new	comment	5/12/2021 21:34:23
As an aside, in the context of developing DITA for Practitioners and as part of DITA for Publishers, I tried to adapt the DocBook bibliographic markup to DITA. I gave up when I realized that the DocBook grammars were so intermingled that it would be days of work to tease out the declarations for the elements that went in the bibliography. I fell back to a very simple bibliography entry specialization that made no attempt to parameterize the details of the entry. So cite is very definitely just a format control as it stands today (unless you specify @keyref)	ekimber	new	comment	6/12/2021 20:30:37
@Eliot, I 100% disagree with your atatement that cite is "just a format control." The cite element clearly conveys the semantic meaning that its contents is the name or title of some sort of resource or document.	keberlein	updated	comment	6/12/2021 22:00:45
Based on today's spec editors' call: Changing the shordesc (provisionally) to: "A citation is the name or the title of a bibliographic resource, for example, a document, online article, or an instructional video." @Zoe, @Frank: Does this work for you?

--
Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
OASIS Distinguished Contributor
Principal consultant, Eberlein Consulting LLC
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)