The management of titles is a challenge in itself. With the original (16.0) approach we have two levels of titles to manage:

• One that is given by the artifact (and with the introduction of Structure, of artifacts)

• One that is inside the paragraph of the section (description)

With the introduction of Structure, we will have two series of titles to manage. The titles given by the Structure (1. Introduction, 1.1 Context) and the titles inside paragraphs.

This might not be too much of an issue for Requirement Sections because it's a special type of Sections. But for Structure, it will be unbearable for end users. They will be proposed to create a new Structure. This Structure could be just a Title, just a Text or both. If they choose to text, they can select a Title inside the paragraph but this title won't be taken into account in the outline 🤯.

Structure have 3 level of titles

Structure provides 3 levels of title (Heading 1, heading 2 and heading 3). While technically we can go up to 6 levels of titles, it's quite hard to make visual differences between levels after level 3. Plus it seems to be a good practice to limit the number of levels to reduce the complexity of documents. Finally, if a compelling need to have more than 3 levels of titles arise, we can add a new one whereas removing a level if it generates too much of complexity is way more complex.

Structure titles are the only one that appears in the Table of Contents.

Descriptions have one level of title

Descriptions (of artifacts or free text) only propose one level of title that is called Subtitle. Subtitles doesn't appears in the table of contents and cannot be linked.

The goal is to let users organize their descriptions with a meaningful tag (subtitle vs using bold to fake a title) while limiting the risk of misunderstanding between Headings and and Subtitles.

Note: existing artifacts that use more than one level of title in their description are rendered with an appropriate font size. It's however not possible to use the other description titles size (h2 and h3) in Artidoc.

Automated titling and numbering

When a new Section is introduced it gets a new number automatically (1, 1.1, 1.2, ...). This number comes from the location of the section in the document, and the type of Section being created.

A new Freetext Section automatically gets the heading level of the previous section.

Example, given:

1. Requirements (Freetext Section)
2. [New Freetext Section]

[New section] is Heading 1, because it comes after Requirement that is Heading 1. Note:The user can change the heading level (h2 or h3) before or after saving.

1. Requirements
1.1 Sub-requirements (Freetext Section)
1.2 [New Freetext Section]
2. Scenario

[New section] is Heading 2 because it comes after Sub-requirements that is Heading 2.

A new Artifact Section automatically gets the heading level:

• bellow the previous one, if the previous one is a Freetext Section

• equal to the previous one if the previous one is an Artifact Section

1. Requirements (Freetext)
1.1 [New Artifact Section]

[New artifact] gets Heading 2 because Requirements is a Heading 1 Freetext section.

1. Requirements
1.1 Some artifact (Artifact Section)
1.2 [New Artifact Section]

[New artifact] gets Heading 2 because Some artifact is a Heading 2 Artifact section.

When the new Artifact Section is added after a Heading 3 Freetext Section, Artifact Section is created with Heading 3 as well (as there is no Heading 4). Example:

1. Requirements
1.1 Optical Requirements
1.1.1 Lens Requirements [Freetext Section]
1.1.2 [New Artifact Section]

Rules

Terms:

• Rank corresponds to the place of a Section in the order of appearance (vertical move)

• Level corresponds to the depth of a Section in hierarchy tree (horizontal move)

• Reorder is the action of changing Rank

Rules

• Reorder doesn't change the Level of Sections

• Reorder of sections is done one rank after another

• Reorder moves the selected Section and its Sub-sections

• Change of Level of one Section doesn't cascade change of Level of Sub-sections

Scenario of title usage

Limitation of headings

Example:

1. Requirements
2. <h1>Radiation [-> cannot move]
2.1 <h2>Advanced spacecraft [-> can move to h1]
2.1.1 <h3>Life support [-> can move to h1, h2]

• Radiation title cannot be changed because there is already an h2 and h3 below

• Advanced spacecraft can move to h1 but not h2 because there is a h3 below

• Life support can move to h1 or h2

Reorder section doesn't change the depth of titles/sections

1. Requirements
2. Radiation
2.1 Advanced spacecraft
2.1.1 Life support [move bottom]
3. Random stuff

Becomes

1. Requirements
2. Radiation
2.1 Advanced spacecraft
3. Random stuff
3.1.1 Life support [move top]

Becomes

1.1.1 Life support
2. Requirements
3. Radiation [move top]
3.1 Advanced spacecraft
4. Random stuff

Becomes

1. Radiation
1.1 Advanced spacecraft
1.1.1 Life support [move down]
2. Requirements
3. Random stuff

Becomes

1. Radiation
1.1 Advanced spacecraft
2. Requirements
2.1.1 Life support
3. Random stuff

User can create incoherent levels of titles

1. Requirements
2. Radiation
3. Advanced spacecraft
4. Random stuff -> move h3

Becomes

1. Requirements
2. Radiation
3. Advanced spacecraft
3.1.1. Random stuff

Reorder of blocks

1.1.1 Life support
2. Requirements
2.1.1 Other
3. Radiation [move up]
3.1 Advanced spacecraft
4. Random stuff

Becomes

1.1.1 Life support
2. Requirements
3. Radiation
3.1 Advanced spacecraft
3.1.1 Other
4. Random stuff

If the user meant to have "Radiation" at n⁰2 of numbering, they should move "Radiation" one more time.

This is the result of the rule "Reorder of sections is done one rank after another"