Issue 493: example templates

ID: 
493
Starting Date: 
2020-04-20
Working Group: 
1
Status: 
Open
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