JGilbert-eLife commented 5 years ago

Description

Sections are used to organise the content of an article.

User stories

Author

As an author, I want to be able to see the hierarchy of section headings within an article so that I can check this is correct.
As an author, I want to be able to add a new heading to my article text so that I can create a new section.
As an author, I want to be able to edit existing headings so that I can correct errors.
As an author, I want to be able to adjust a heading's level of hierarchy within my manuscript so that I can organize my content.
As an author, I want to be able to delete a heading so that I can merge one section of text into another.

But what if . . . ?

Consideration

At eLife, Level 1 headings are the top-level sections (for research content, these are standardised to Introduction, Results, Discussion, Materials and methods and a few variants thereof). Level 2 headings are for child sections of those top-level sections, Level 3 headings are for children of Level 2 sections, and Level 4 headings are for children of Level 3 sections. In the XML, these are denoted using the value of @id on elements: -- Level 1: s1, s2, s3 etc -- Level 2: s1-1, s1-2, s2-1 etc -- Level 3: s1-1-1, s2-2-1, s2-2-2 etc -- Level 4: s1-1-1-1, s1-1-1-2, s1-1-1-3 etc
eLife does not want authors to be able to define level 1 headings. Either these will be standard, fixed headings (Introduction, Results, Discussion [OR Results and Discussion], Materials and methods [OR Methods, Model]), predetermined by editorial and production staff agreement, or chosen by the Features team for non-research content.

XML requirements

Level of section headings determined by the nesting of sec.

Captured as a simple title. For eLife, every sec must have a title - this seems like a sensible rule to mandate (from a content architecture perspective).

<body>
    <sec>
        <title>...</title>
        ...
        <sec>
            <title>...</title>
            ...
            <sec>
                <title>...</title>
                ...
            </sec>
        </sec>
    </sec>
<body>

Children of sec/title:

italic
underline
sup
bold
xref
sub
inline-formula
ext-link
sc
monospace

The following elements should be allowed as children of sec elements in the body of the text/appendices:

title
p
sec
list
fig
fig-group
table-wrap
table-wrap-group
disp-quote
boxed-text
media
preformat
sec-meta
def-list
label (Érudit requirement)
verse-group

Mock ups

Proposal

fabiobatalha commented 5 years ago

@JGilbert-eLife

The following elements should also be included in sec.

verse
disp-formula
disp-formula-group
graphic
tex-math
mml:math

JGilbert-eLife commented 5 years ago

@FAtherden-eLife - please could you take a look at the elements Fabio mentioned? Was there any reason we excluded any of these from the XML requirements in this ticket? I think verse/verse-group may simply have been missed, but I'm not sure about the rest? I just want to make sure we don't need to make similar changes in other tickets.

Thanks!

fred-atherden commented 5 years ago

Thanks @JGilbert-eLife! verse-group I simply missed.

@fabiobatalha in #1318 we specified that disp-formula (and disp-formula-group elsewhere) should always be treated as inline content and captured in a p element (or similar, like td, title etc.). As a result I didn't include them as allowed children of sec - does that requirement still work for you?

With regard to graphic, tex-math, mml:math - can you tell me what context these would be used in. Would these always be captured in the following elements:

inline-graphic
fig
inline-formula
disp-formula

or do you need these to be able to be placed outside of these elements?

substance / texture

Sections #1329