Review C items: Short description for

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)