Headings are lost during reorder

[blastur]

For a document ABC that has the following item order:

initial: 1.0
outline:
    - ABC001: # Overview
        - ABC002: # Terms and definitions
    - ABC003: # This is a requirement

And ABC001 and ABC002 are headings (non-normative and level 1.0 and 1.1.0). If I run the reorder command on this and change nothing, ABC002 is no longer a heading. So it seems that doorstop assumes that 1.1.0 is the same as 1.1, which it is in terms of ordering, but it ruins the heading property of the item.

Steps to reproduce:

1. Create the ABC document as shown above. ABC001 and ABC002 are headings, ABC003 is normative.
2. Publish the document, notice 1.1 is a heading.
3. Run doorstop reorder ABC
4. Re-publish, notice 1.1 is no longer a heading.

[michaelnt]

This is a limitation that has always existed in the reorder command, I recreated this in doorstop 1.2.1 at least. I get a slightly different index.yml to yours.

initial: 1.0
outline:
    - ABC001: # Heading 1
        - ABC002: # Sub Heading
        - ABC003: #  More requirements

You can work around the problem by adding an item under the heading either separately or during reorder, i.e.

initial: 1.0
outline:
    - ABC001: # Heading 1
        - ABC002: # Sub Heading
                 - NEW : # A new item at level 1.1.1
        - ABC003: #  More requirements

Why have a heading without any items under it?

Perhaps doorstop could issue a warning whilst creating the index.yml?

[blastur]

Yes, I agree that this is not a new issue, it is not related to the new functionality in reorder that allows it to create new and delete items from index.yml.

Consider the following item

level: X.x.x.0
normative: false
text: |
  My heading

  Body text goes here.

It will display the heading and the body text. I do this a lot in my documents because I find it convenient to use a single item to represent both a heading and its text body when i write non-normative chapters. Especially because doorstop does not publish the item UID, and I only want the UID to display in normative chapters. With this approach, the last "subheading-item" of each level will be subject to this bug.

So yeah, maybe the issue here is that I'm abusing the heading item to become both a heading and to display a body of text? IMO it's a very useful feature :)

[jacebrowning]

If this is not a new issue, I'm going to remove it from the v1.3 milestone.

[guille-r]

I agree that it would be useful. In addition to blastur's use case, I sometimes need to mark an entire chapter as "non applicable". So I'm running into the same limitation when using reorder.

In the reorder functionnality, assuming whether an item is a heading or not is based on its children's count.

document.py :

def _reorder_section(section, level, document, list_of_ids):
    [...]
    # An item is a header if it has a subsection
    [...]
    if len(subsection) > 1:
        level.heading = True
    [...]

The difficulty is that the structure of index.yml file doesn't give any other clue whether an item is a heading or not.

Do you have any clue on how to implement/correct this feature ? Let me know if I can help implementing this, but from my external point of vue it seems to be a rather big refactoring.

[jacebrowning]

A quick win could involve including more of each Item's metadata in the generated comment: https://github.com/jacebrowning/doorstop/blob/b97a0db3f3df1a5ea4f1766db2c6b1a1108a9043/doorstop/core/document.py#L446