elifesciences / schematron-wiki

This contains the markdown from gitbook for schematron.
MIT License
2 stars 0 forks source link

Create Article structure page #138

Closed JGilbert-eLife closed 4 years ago

JGilbert-eLife commented 4 years ago

Definition of done

JGilbert-eLife commented 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?

fred-atherden commented 4 years ago

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

fred-atherden commented 4 years ago

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?

fred-atherden commented 4 years ago

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).

fred-atherden commented 4 years ago

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?]

fred-atherden commented 4 years ago

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

fred-atherden commented 4 years ago

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.

fred-atherden commented 4 years ago

Same as above for ra-sec-test-3 and ra-sec-test-4 (re not firing for Short Reports/Sci Corr)

fred-atherden commented 4 years ago

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?

fred-atherden commented 4 years ago

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)

fred-atherden commented 4 years ago

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.

fred-atherden commented 4 years ago

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.

naushinthomson commented 4 years ago

Is it worth including a screenshot of an editorial note approving an unusual article structure?

naushinthomson commented 4 years ago

Otherwise I think nothing from me!

Melissa37 commented 4 years ago

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.

Melissa37 commented 4 years ago

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?

Melissa37 commented 4 years ago

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

Melissa37 commented 4 years ago

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.

Melissa37 commented 4 years ago

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

Melissa37 commented 4 years ago

XXXXXX will be the title in question.

Do we do this for other pages? I found it a bit confusing initially

Melissa37 commented 4 years ago

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?

Melissa37 commented 4 years ago

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.

Melissa37 commented 4 years ago

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

Melissa37 commented 4 years ago

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.

?

Melissa37 commented 4 years ago

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"

Melissa37 commented 4 years ago

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

Melissa37 commented 4 years ago

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?

Melissa37 commented 4 years ago

Same as above for following rules for ra-sec-test-4 and ra-sec-test-3

Melissa37 commented 4 years ago

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?

Melissa37 commented 4 years ago

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?

Melissa37 commented 4 years ago

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.

Melissa37 commented 4 years ago

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.

Melissa37 commented 4 years ago

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.

bcollins14 commented 4 years ago

I also find this a tad confusing.

XXXXXX will be the title in question.

bcollins14 commented 4 years ago

I like the little table in sec-type-title-test 👍

bcollins14 commented 4 years ago

Everyone has covered everything else. Thanks!

JGilbert-eLife commented 4 years ago

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 !

fred-atherden commented 4 years ago

Thanks @JGilbert-eLife, all done in that linked commit above.

JGilbert-eLife commented 4 years ago

@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?

fred-atherden commented 4 years ago

Looks good to me :+1: - thanks

naushinthomson commented 4 years ago

Looks good to me! Thank you!

bcollins14 commented 4 years ago

No points to add, looking good 👍 thannnkkksss

Melissa37 commented 4 years ago

Looks good to me - thanks!

JGilbert-eLife commented 4 years ago

Brilliant, thanks gusy! Will share with Exeter ASAP.

fred-atherden commented 4 years ago

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]

JGilbert-eLife commented 4 years ago

@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.

fred-atherden commented 4 years ago

Sounds good to me - thanks

JGilbert-eLife commented 4 years ago

@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.