Issue 493: example templates

ID: 
493
Starting Date: 
2020-04-20
Working Group: 
1
Status: 
Done
Background: 

This is a continuation of the issue 449.  The ad-hoc CRM SIG Editorial Team of version 7.0, working on issue 484 preparation of missing examples, asked Thanasi to formulate some rules for example writting.

April 2020

 

Old Proposal: 

Posted by Thanasis on 20/4/2020

Dear all,

Having received some notes from Chryssoula I went through the examples of CRMbase and CRMsci and I picked out what I could identify as consistent practices. I have put these in the attached documents and in some cases I have made some proposals to handle some special cases a bit better. Happy to discuss in the next meeting. I hope these templates do not contradict any current practices.

.....

Current Proposal: 

Posted by Martin on 21/4/2020

 On 4/20/2020 7:57 PM, Athanasios Velios wrote:
> Dear all,
>
> Having received some notes from Chryssoula I went through the examples of CRMbase and CRMsci and I picked out what I could identify as consistent practices. I have put these in the attached documents and in some cases I have made some proposals to handle some special cases a bit better. Happy to discuss in the next meeting. I hope these templates do not contradict any current practices.
> ......
..

Dear Thanasi,

Good work!

So far, we had the convention to omit the class identifier if it is the same as the class, domain or range it exemplifies. Doe we have good reasons to deviate from that? The idea was not to interrupt the flow of what may read nearly like natural language.

§  the capital of Italy (E53)[AV1]  is identified by[AV2]  “Rome” (E41)[AV3] 

§  text 25014–32 (E33) is identified by “The Decline and Fall of the Roman Empire” (E35)

Shouldn't the Appellation be in single quotes, as with the Maxwell equations ? See also good practice in FRBRoo.

I cc also to Pat Riva. We should have the same style.

I think only titles should be in double quotes, such as: the French “July Revolution” .

In the Maxwell Equations example, the explanation continues with ":". Shouldn't it be in brackets "[...]" ?

Posted by Thanasis on 21/4/2020

Dear Martin,

> So far, we had the convention to omit the class identifier if it is the same as the class, domain or range it exemplifies. Doe we have good reasons to deviate from that? The idea was not to interrupt the flow of what may read nearly like natural language.

Like I said in the comment the only reason to deviate is because of the multiple instantiation examples where we have the class identifier alongside other class identifiers. Including the class identifier there, but not elsewhere is inconsistent.

> §the capital of Italy (E53)[AV1]is identified by[AV2]“Rome” (E41)[AV3]
>
> §text 25014–32 (E33) is identified by “The Decline and Fall of the Roman Empire” (E35)
>
> Shouldn't the Appellation be in single quotes, as with the Maxwell equations ? See also good practice in FRBRoo.

I read a little bit about the use of single and double quotes. It looks like they are used in different ways by different groups. FRBRoo includes titles in single quotes, for example in F8:

Printing for the publisher named ‘Doubleday’ in 2003 all the copies of the first print run of the novel entitled ‘Da Vinci Code’ (F32)

and then you have titles in quoted text, for example F9:

The area referred to as ‘verso of the title page of the Library of Congress’s copy of the 1 st edition of the novel entitled ‘Da Vinci Code’’

which is general people would expect to see in double quotes, not single. Plus we have the Appellations and strings in the CMR which need quotes. So the rules around quotes are too fluid and I tried to keep quiet about it. We could recommend that everything is single quoted unless this confuses the meaning of the example, in which case double quotes can be used.

> I cc also to Pat Riva. We should have the same style.

Posted by Thanasis on 4/5/2020

Dear Pat,

I am doing a bit of work for the editorial guidelines for class and
property examples and Chryssoula kindly pointed to section 2.4 of FRBR
which explains that single quotes should be used for instances of E41
Appellation and E90 Symbolic Object. However, in FRBR the examples under
the E41 Appellation class all have double quote marks. Am I misreading
the text? What is the current best practice? I would agree with the use
of single quotes for everything. I am only a bit concerned about nested
quotes, i.e. names within names. I think we should avoid those.

Posted by Thanasis on 4/5/2020

Dear all,

I have made a few changes to the examples template based on the discussions from the last meeting. There are still a couple of pending issues but I think we should discuss those at the end of the meeting tomorrow if there is time:

* use of quotes
* use of conjunctions in examples featuring multiple properties
* new issue to update examples in CRMcore to match those in the template

Homework uploaded on Google Drive:

docx: https://drive.google.com/open?id=1rzGdUgSlanjEnvFcVdnFqCkChMUnDkDG
odt: https://drive.google.com/open?id=16q5A7TUIXVPtXE4xs_YS0yk0kmOxkVEJ

 

Post by Thanasis Velios (12 June 2021)

Dear all,

With Martin's contribution I am sending the updated homework for the example templates. You can find it here and here.

All the best,

Thanasis

 

[CRM SIG] 493 evote. 

Thanasis Velios via CRM-sig, Friday 18th June 2021

Dear all,

This issue is about agreeing a rationale and a template based on which CRMbase and CRM extension examples will be produced. The working document for this issue is here:

https://docs.google.com/document/d/1-PIIjXkDul1F0A7AoA4S95H0qY2CY9a7BKa1...

The homework including annotated templates is here:

odt: https://drive.google.com/file/d/1YtZBSx5ZCOQ5ntFUf34TY-_aeR4OIrJY/view?u...

docx: https://drive.google.com/file/d/1S6ZAy7Y3TO2ndNtJNkf-NrFeMpVNnXAj/view?u...

The vote is to decide on whether to adopt the homework document.

The possible votes are:

Yes = accept/agree
No = do not accept/agree
Other = With other you can either introduce a caveat (e.g.: 'Yes, but there is a typo on word x, fix it.') or you can write VETO, if you wish to stop the proposal, in which case you should also write a justification and reformulate the issue (e.g.: 'VETO, this change is unacceptable because it violates the following principle...')
Please send your e-votes by the 28th of June.

All the best,

Thanasis

Post by Robert Sanderson (18 June 2021)
YES.

Post by Christian-Emil Ore (19 June 2021)
Yes

Post by Achille Feliccetti (19 June 2021)

I vote YES.
A.

Post by Martin Doerr (19 June 2021)
YES 
 

Post by Donatella Fiorani (21 June 2021)
YES

Post by Oyvind Eide (21 June 2021)
YES

Post by George Bruseker (21 June 2021)

 

YES

Post by Francesco Beretta (21 June 2021)

 

YES

Post by Pat Riva (22 June 2021)

YES.

And just a note that I have tried out these templates on the latest LRMoo working draft, including some fairly complex examples of properties, and have been able to use them. 

Pat

Post by Maja Zumer (23 June 2021)

 

YES.

I have a question, though. The guideline says:
"Each example should include a bibliographical reference using the Harvard in-text citation
guidelines ( https://www.citethisforme.com/harvard-referencing#harvard-in-text-citations), if
it is not a commonly known fact. In particular, it should be not assumed that all cultures
using the CRM have the same historical background knowledge. Fictitious examples are
not preferred, but should be marked as such."

But there is no guideline how to enter the full reference. As a footnote/endnote? If no full reference is provided, the citation is meaningless...

Best regards
Maja
 

In the 53rd CIDOC CRM & 46th FRBRoo SIG meeting, the Sig decided that the example templates (.docx, .odt) will appear in the "Supplementary Material" section (under Resources) of the CRM website. Since they are collaboratively maintained, they will also be checked into the CIDOC repository as well. 

 

May 2022

Outcome: 

In the 54th CIDOC CRM & 47th FRBR/LRMoo SIG meeting, the issue was resolved by decision of Issue 596 (supplementary material), according to which the example templates will be published on the website under Resources\Guidelines and Templates\Templates. 

 

Rome, September 2022

Reference to Issues: