Closed JGilbert-eLife closed 4 years ago
https://app.gitbook.com/@elifesciences/s/productionhowto/article-details/content/article-structure is now ready for checking.
I'm not sure about the last two schematron errors since I'm not quite sure what the correct action is respective to the Kriya interface - probably would require support team intervention, but I can sort of imagine how it might happen due to editing by the author?
We have a handful of (old) articles with level 5 headings. Is it worth including an example of that? https://elifesciences.org/articles/04640#s4-1-4-3-2
sec-title-appendix-check
currently only fires if the section title starts with [Aa]ppendix. Do we also want to cover the use case where [Aa]ppendix is simply contained within the title?
sec-conformity
- All this currently does is fire for any level 1 section (outside of feature, review and correction/retraction articles) which isn't one of the following:
Do we need to refine this for each specific article type? Or add to the 'allowed' headers? (Model from T&R for example is not there - that may be the only one, and may just be an oversight on my part).
ra-sec-test-1 Error: At least one sec should be present in body for research-article content. Action: This error indicates that there are no section elements
<sec>
within an article using the research content template.
What would the action be?
[Edit: or was this one of the two you referred to above?]
Warning: _main body in XXXXXX content doesn't have either a child sec[@sec-type='results|discussion'] or a sec[@sec-type='results'] and a sec[@sec-type='discussion']. Is this correct?
Formatting looks to have gone awry here
ra-sec-test-2
will fire for any research article (meaning <article article-type="research-article">
) which is not a Short Report or Scientific Correspondence, so this text from the action can be removed:
... except for short reports, which may have one but do not need to.
Same as above for ra-sec-test-3
and ra-sec-test-4
(re not firing for Short Reports/Sci Corr)
What are the actions for ra-sec-test-2
, ra-sec-test-3
, and ra-sec-test-4
? If an author hasn't included them in their MS, what do we expect Exeter/us to do?
sec-type-title-test
Just noting that adding sec-type="model"
to a Model headed sec apparently requires development work, so is something we should include as Kriya 2 work. (See this Slack thread)
top-sec-id
, and lower-sec-test-1
appear to be duplicates of body-top-level-sec-id-test
and low-level-sec-id-test
respectively. I am going to remove the former pair.
I'm not sure about the last two schematron errors since I'm not quite sure what the correct action is respective to the Kriya interface - probably would require support team intervention, but I can sort of imagine how it might happen due to editing by the author?
Agreed. I suppose it might occur if something has gone wrong with the HTML/Kriya XML -> JATS transformation. It might be worth adding something generic to the end of the message, something like:
If the content looks fine in Kriya it likely to be a problem relating purely to the XML, in which case the Exeter support team should be contacted in order to fix the issue.
Is it worth including a screenshot of an editorial note approving an unusual article structure?
Otherwise I think nothing from me!
Any number of Level 2, 3 or 4 headings may appear within their parent sections. However, eLife limits the number of Level 1 headings in research content to between one and four in most cases.
Is it worth being explicit?
Any number of Level 2, 3 or 4 headings may appear within their parent sections, but levels cannot be skipped out, for example a level 2 heading cannot be followed by a level 4 heading. However, eLife limits the number of Level 1 headings in research content to between one and four in most cases.
For completeness and to prevent the reader from having to jump about, where you say eg "Replication studies share the same structure rules as research articles." is it worth repeating those section heads?
However, this is not mandated and other Level 1 headings are permitted. The article structure should follow that indicated in the exported article file.
There is an extra space in front of "However" at the start of the sentence
There are no rules for Level 1 headings in review articles. The article structure should follow that indicated in the exported article file.
This is said in 2 places - is it worth saying:
There are no rules for Level 1 headings (or any headings) in review articles. The article structure should follow that indicated in the exported article file.
Action: This warning will fire if a section title starts with 1), 2), 3) etc., or with a), b), c) etc. Check to make sure that this content is not actually intended as an entry in a list (this may require checking the exported article file). XXXXXX will be the title in question.
Are these allowed if the author included them initially? It does not say to remove these if it is a heading
XXXXXX will be the title in question.
Do we do this for other pages? I found it a bit confusing initially
Action: Section titles do not need to be placed in bold font to be styled correctly. Scientific terms can be placed in bold for consistency, but if the entire title is in bold, this formatting should be removed. XXXXXX indicates the affected tittle.
I don't understand why they would be in bold for consistency? Do authors put scientific terms in bold?
Action: Section titles should not be underlined. Individual terms can be underlined for consistency with the main text, but if the entire title is underlined, this formatting should be removed. XXXXXX indicates the affected tittle.
Suggest change:
Action: Section titles should not be underlined. Individual terms can be underlined for consistency with the corresponding term in the main text, but if the entire title is underlined, this formatting should be removed. XXXXXX indicates the affected tittle.
Action: Section titles should not be entirely in italics unless they only consist of a species name such as C. elegans. Scientific terms such as species names should be put in italics for consistency with the main text, but italics should be removed from any accompanying text. XXXXXX indicates the affected tittle.
I don't think this requires the text " for consistency with the main text" because this is a house style rule, irrespective of whether the term is used elsewhere in the text
The only exception to this rule is if this would involve making a sub-section of a Level 4 section, which is not allowed.
This flummoxed me on first read, think it might be clearer to say:
The only exception to this rule is if this would involve making a sub-section under a Level 4 section, which is not allowed.
?
f this warning appears post-author, check whether the author has reverted the above kind of change and if so, that this makes sense (they may prefer the text to appear as bold for highlighting purposes, but do not want it as a heading).
Comma missing before "if so"
Action: This error indicates that there are no section elements
within an article using the research content template.
What is the action? This is an explanation but does not tell the user what to do to fix it
Action: This warning indicates that there is no section element
with the type attribute @sec-type equal to 'intro'. If an 'Introduction' section is present in an article, it must have the @sec-type with a value of 'intro'. An 'Introduction' section should be present for all research content except for short reports, which may have one but do not need to.
Can a production person fix this, and if so how, or does it need to go back to Exeter to fix?
Same as above for following rules for ra-sec-test-4 and ra-sec-test-3
Action: The Level 1 section elements
in an article should each have an @id attribute, the value of which is determined by the order of the sections. The first Level 1 section should have the id 's1', the second an id of 's2' and so on (see XML structure). Correct the section id to the indicated value.
I don't think production staff can do this can they?
The ids for Level 2 sections within a Level 1 section should the id 's1-1', 's1-2', 's1-3' and so on
change to:
The ids for Level 2 sections within a Level 1 section should be 's1-1', 's1-2', 's1-3' and so on
And can production staff do this?
This sec id must be a concatenation of 's' and this element's position relative to it's siblings.
Should be:
This sec id must be a concatenation of 's' and this element's position relative to its siblings.
sec id must be a concatenation of it's parent sec id and this element's position relative to it's sibling secs. It must be XXXXXX.
Should be:
sec id must be a concatenation of its parent sec id and this element's position relative to its sibling secs. It must be XXXXXX.
Action: Each section should have a title. Check whether the text for the title has been captured as part of the first paragraph and, if so, correct the tagging.
Suggest changing to:
Action: Each section should have a title. Check whether the text for the title has been captured as part of the first paragraph of this section and, if so, correct the tagging.
I also find this a tad confusing.
XXXXXX will be the title in question.
I like the little table in sec-type-title-test 👍
Everyone has covered everything else. Thanks!
sec id must be a concatenation of it's parent sec id and this element's position relative to it's sibling secs. It must be XXXXXX.
Should be:
sec id must be a concatenation of its parent sec id and this element's position relative to its sibling secs. It must be XXXXXX.
One for you, @FAtherden-eLife !
Thanks @JGilbert-eLife, all done in that linked commit above.
@naushinthomson @FAtherden-eLife @bcollins14 @Melissa37 - I've revised the page and I think I've got everything covered now. Please could you let me know if ra-sec-test-1 to ra-sec-test-4 make sense?
Looks good to me :+1: - thanks
Looks good to me! Thank you!
No points to add, looking good 👍 thannnkkksss
Looks good to me - thanks!
Brilliant, thanks gusy! Will share with Exeter ASAP.
I tested an article with a level 6 heading (and 7) today and it causes a Kaboom page on Continuum. So I'm adding a test for this in the schematron. id - sec-test-5 role - Error message - Level XXXXXX sections are not allowed. Please either make this a level 5 heading, or capture the title as a bolded paragraph in its parent section.
XXXXXX = level number (which will be greater than 5)
Since I don't think this is permitted in Kriya, I don't expect it to fire in the near term and thus haven't included a pre/final version - I'm just adding it for completeness. Feel free to suggest better wording in the message.
(I assume that it is best placed on this page?)
[Edit: sec-test-5 not sec-test-3]
@FAtherden-eLife Yep, that sounds good to me.
I didn't add stuff about Level 5 headings yet, given current Kriya limits. Hmm. Probably that'll be the first update for this page, so perhaps adding this rule then would be best.
Sounds good to me - thanks
@FAtherden-eLife The page is ready, excepting the above update regarding level 5 headings. Please go ahead and add in the links at your convenience - I'd like to bring this additional change up at the huddle to check whether it's best left for Kriya 2.
Definition of done