Create References page

[naushinthomson]

• [x] Create page
• [x] Add description of what is being covered
• [x] Add description of checks required on this content, compiled from current protocol documents
• [x] Add examples covering correct and incorrect scenarios, as required to support checks
• [x] Populate with schematron messages
• [x] Provide explanations for how to fix schematron errors and warnings
• [x] Review house style document to ensure all requirements are covered by GitBook and schematron
• [x] Review schematron messages related to this topic to ensure they are user friendly
• [x] Melissa approved page
• [x] Fred approved page
• [x] James approved page
• [x] Naushin approved page
• [x] Claudia approved page
• [x] Share page with Exeter and invite feedback
• [x] Revise with Exeter's suggestions

Definition of done

• [x] Page completed
• [x] Team reviewed and approved page?
• [ ] Assign Fred to update the Schematron

[JGilbert-eLife]

Make it clear that the changes to reference ordering rules will be implements on Kriya 2 - we'll need to include both current and future sets of rules.

[JGilbert-eLife]

@FAtherden-eLife - I've got a few questions about some of the rules.

pre-element-cite-string-date + final-element-cite-string-date - the logic here looks like it's checking for a string-date in full, but the messages only refer to the year. Is that just a case of the message needing to be clarified?

tagging-elem-cit-des - is this specifically targetting tags that have been entered as text? The fail case uses em tags, but obviously something like italics in a title is fine, so I presume this is about catching badly copied text.

pub-id-doi-test-2 - slightly confused by this one, since the test cases provided on the repo don't seem to match how we handle DOIs in references. E.g the pass case is

<pub-id assigning-authority="other" pub-id-type="doi" xlink:href="https://doi.org/10.17617/3.3v">10.17617/3.3v</pub-id>

but we'd normally tag that as

<pub-id pub-id-type="doi">10.17617/3.3v</pub-id>

(Obviously ditching assigning-authority entirely at this point!) Am I missing an obvious alternative use case, or has this fallen out of sync with how we handle DOIs?

Thanks!

[fred-atherden]

@JGilbert-eLife

pre-element-cite-string-date + final-element-cite-string-date - the logic here looks like it's checking for a string-date in full, but the messages only refer to the year. Is that just a case of the message needing to be clarified?

Yup - will replace the word year with string-date.

tagging-elem-cit-des - is this specifically targetting tags that have been entered as text? The fail case uses em tags, but obviously something like italics in a title is fine, so I presume this is about catching badly copied text.

Yes it's checking that the text has tagging like text. I think it's basically to catch when the tagging is pulled from Crossref/PubMed incorrectly (either due to bug in reference validation in Kriya, or due to bad data being supplied to those places).

pub-id-doi-test-2 ... (Obviously ditching assigning-authority entirely at this point!) Am I missing an obvious alternative use case, or has this fallen out of sync with how we handle DOIs?

The latter, you can ignore this one.

[JGilbert-eLife]

Brilliant, thanks @FAtherden-eLife !

[JGilbert-eLife]

@griffithscm, @FAtherden-eLife, @Melissa37, @naushinthomson - this page is now ready for your review. It is very long!

https://app.gitbook.com/@elifesciences/s/productionhowto/article-details/content/references

[Melissa37]

Each reference list applies to the entire article in which it appears; references cited in appendices are not treated separately from those in the main text.

It does not cover the decision letter and author response so not quite the entire article! Can you add a bit about references in DL/AR are left untagged and intext and why we don't add to ref list (citation counts etc)?

[Melissa37]

Where the formatting of a reference appears incorrect in the proofing system or the PDF — such as there being misplaced full-stops, italics applied to the wrong piece of text etc — this will usually indicate that the content has been mistagged. In most cases this can be resolved by editing the reference in the proofing system and re-entering the details in the correct fields, as per the guidance on the type-specific pages.

It can also happen when you change reference content and don't revalidate it.

[Melissa37]

As you can see, the first author provides the main ordering criterion, followed by the publication date in cases where the first surnames for separate references are the same. In cases where the first surname and date are the same, the second and then third author surnames provide the next level of ordering (here, Keeley and Soldati are followed by Keeleym Soldati and Smith).

So zero authors trumps next in alphabet in a list? ie A,B,C 2000 versus A,B 2000 the latter would be first?

[Melissa37]

all of them would be cited as 'Keeley et al., 2004'. In order to prevent confusion, references with identical citation strings are distguished by added a letter to the year.

Typo distguished

[Melissa37]

Warning: The numeric value of the first 4 digits of the element must be between 1700 and the current year + 5 years (inclusive). Reference 'XXXXXX' does not meet this requirement as it contains the value 'XXXXXX'.–

Is there a way to refine the future date ie future date only allowed if In Press is present?

[Melissa37]

Warning: The numeric value of the first 4 digits of the @iso-8601-date attribute on the element must be between 1700 and the current year + 5 years (inclusive). Reference 'XXXXXX' does not meet this requirement as the attribute contains the value 'XXXXXX'.

There should only ever be 4 digits on the @iso-8601-date. Thta's the point of it - a,b,c etc is in the visual year field, this is pure.

[Melissa37]

Is there a warning if there should be a,b,cs in year and there are not?

You could use the author list and iso date to find that?

[fred-atherden]

The number of references cited will vary considerably between different article types. ... high as 200+ references.

Is it worth specifying that there is no limit to the number of references in an eLife article?

[Melissa37]

Warning: 'XXXXXX' type references must have a string-date. Reference 'XXXXXX' does not. If you are unable to determine this, please ensure to add an author query asking for the date of publication. Action: This warning indicates at the pre-author stage that a reference is missing a publication date (this will fire on reference types that use the element in place of ). Check that the reference details have been correctly processed from the provided article file and if no date (day, month, year) was provided, please query the authors:

Can you list the reference types that have this? X2 messages

[Melissa37]

final-pub-id-test-2 Error: pub-id is tagged as a doi, but it is not one - XXXXXX Action: This error indicates, at the pre-author stage,

This is the post author stage

[Melissa37]

I wonder whether somewhere we need to explain that the iso date is pure and needs to be but the display date can have a,b,c,d etc and why?

[Melissa37]

Nice! Thanks James, this will be really helpful and looks like it will bump our Schematron % up quite a bit too (fingers crossed).

[fred-atherden]

link-href-conformance

I realise we need to allow for sftp as well. Please update the text for the message so that it reads:

@xlink:href must start with either "http://", "https://", "sftp://" or "ftp://" ...

I will update the schematron.

It's pedantry but:

A URL that does not begin with one of these is invalid, so this will need to be corrected.

Isn't technically correct, since there are various other valid protocols. Maybe we could say something like:

A URL that does not begin with one of these is undesirable since it's less likely to be universally supported by browsers. Therefore it will need to be corrected.

or similar.

[fred-atherden]

Same as above applies for pre-pub-id-test-1 and final-pub-id-test-1. I will update the Schematron, but leave the message text as they are.

[fred-atherden]

Web and periodical references missing from the list under:

eLife permits references to the following kinds of publication, for which type-specific guidance has been provided on dedicated pages:

[fred-atherden]

pre-element-cite-year ... final-element-cite-year

These won't fire on periodical refs.

[fred-atherden]

I think the following tests would be best suited to this page as well:

• err-elem-cit-gen-name-5
• err-elem-cit-gen-date-1-9
• fpage-lpage-test-1
• err-elem-cit-gen-name-3-1
• err-elem-cit-gen-name-3-2
• err-elem-cit-gen-name-4

[fred-atherden]

More we should probably add to this page (sorry!):

• pre-year-element-citation-conformity
• final-year-element-citation-conformity
• publisher-name-colon
• publisher-name-inc
• pub-name-replacement-character-presence
• pub-name-newspaper
• author-test-1
• author-test-2
• author-test-3
• all-caps-surname
• surname-number-check
• surname-ellipsis-check
• surname-count
• given-names-count
• given-names-count-2
• isbn-conformity-test - (there's also isbn-conformity-test-2, but I don't think we've ever used the isbn element so we can probably ignore for now).
• doi-in-display-test
• link-in-display-test

Unsure whether text-v-cite-test is best placed on this page, or a general one. Presumably missing-ref-in-text-test should be elsewhere.

[fred-atherden]

Nice job, thanks @JGilbert-eLife

[griffithsc]

The reference list is placed at the end of the article, in the back matter.

• is it worth saying that they come before any appendices?

[griffithsc]

References are ordered alphabetically by the surname of the first author for each entry, then by year, and then by the surnames of the second, third, fourth etc authors as necessary.

• Might be helpful to point out that the ordering is an automatic process

[griffithsc]

This warning indicates a reference has a date that is outside the range 1700 to five years past the current year.

• could this be rephrased to 'This warning indicates a reference has a date that is outside the range spanning from 1700 to five years into the future' (otherwise ‘past’ seems a bit unclear)

[griffithsc]

pub-id-test-4 Warning: pub id contains whitespace - XXXXXX - which is very likely to be incorrect. Action: This warning indicates that a pub id (DOI or PubMed ID)

• should this be ‘pub ID'?

[griffithsc]

pre-ref-link-presence Warning: 'XXXXXX' has no linked citations. Either the reference should be removed or a citation linking to it needs to be added. Action: At the pre-author stage, this warning indicates that a reference is not cited in the text. All reference listed must be cited at least once. The author should be queried to provide the missing citation.

• is it worth saying that you should check whether there are any citations for it currently unlinked and in plain text/possibly check the article file to ensure a citation hasn’t been missed in pre-editing?

[JGilbert-eLife]

The reference list is placed at the end of the article, in the back matter.

* is it worth saying that they come before any appendices?

For simplicity I'd rather not, since appendices display in different places in the PDF and online!

[JGilbert-eLife]

* isbn-conformity-test - (there's also isbn-conformity-test-2, but I don't think we've ever used the isbn element so we can probably ignore for now).

I've left this one off for now; maybe we should discuss if we want to retain ISBN elements as an option?

Unsure whether text-v-cite-test is best placed on this page, or a general one. Presumably missing-ref-in-text-test should be elsewhere.

My instinct is that the citation tests below together on the reference citation page.

[naushinthomson]

(compare Axten et al., 2021 in the two lists shown above)

I think this should say 2012

[naushinthomson]

The italics for journal or books titles, the bolding for volume numbers, and so on is all provided by the platform on which the reference list is being displayed.

I'm a bit confused by this sentence - does it mean the formatting is pulled from where the reference is hosted?

[naushinthomson]

This refers not to to the reference details

Extra to can be deleted

[naushinthomson]

This will be carried out during initial processing of the article files so there usually will not be nothing to check at the subsequent stages.

I think the double negatives are confusing me here - can you clarify?

[naushinthomson]

@FAtherden-eLife I think there's a typo in surname-ellipsis-check

Error: surname in ref 'XXXXXX' begins with an ellipsis which is wrong - XXXXXX. Are there preceding author missing from the list?

should it be 'are there preceding authors'?

[naushinthomson]

Should pre-element-cite-string-date and final-element-cite-string-date not be on the periodicals refs page?

[naushinthomson]

Nothing further to add, thanks for tackling this mammoth page!

[JGilbert-eLife]

Should pre-element-cite-string-date and final-element-cite-string-date not be on the periodicals refs page?

I think it would seem a bit odd to list the ones for non-periodicals here but not these as well. I can be persuaded otherwise though.

The italics for journal or books titles, the bolding for volume numbers, and so on is all provided by the platform on which the reference list is being displayed.

I'm a bit confused by this sentence - does it mean the formatting is pulled from where the reference is hosted?

Tried to clarify what I mean!

I've updated everything else and will share this with Exeter.