Warnings when validating documents with headings

[fjpse1]

I have created a requirements document with headings (level ends with zero and normative is false). The headings have the text property empty, but header property not. For example, this is the content of RSTPS-0168.yml

active: true
derived: false
header: |
  Introduction
level: 1.0
links: []
normative: false
ref: ''
reviewed: jSEePfMc7TdjZaqommihYHtcPgHjbhYx2KP6Ed9iga4=
text: ''

When I execute doorstop to validate the requirements I got a lot of warnings related with the headings:

building tree...
loading documents...
validating items...
WARNING: RSTPS: RSTPS-0168: no text
...
...

In my opinion, if a requirement is a heading, instead of checking if the text is empty, it should be checked if the header is empty (or both, text and heder).

What do you think about it?

[opt12]

I fully agree with your analysis/proposal.

To structure a document, we need headings. And a natural way for pure structuring elements is to set the attributes

• normative = false
• level = x.y.z.0
• header = "title"

The text attribute may or may not contain some commenting and explanatory text on the paragraph/chapter.

--> In case of a structuring item with a non-empty header should not trigger a warning. The text attribute may or may not be empty in that case.
--> If the header attribute is empty and the level ends with ".0", the text attribute should not be empty and may trigger a warning.

Changing this behavior would be a great enhancement in usability.

[opt12]

Unfortunately, I still have problems with getting my local Doorstop up and running.

However, to change this behavior should be as easy as changing this in the `item_validator.py':

        # Check text
        if not item.level.heading:
            # non-heading item shall have text
            if not item.text:
                yield DoorstopWarning("no text")
        else:
            # heading item shall have either text or header or both
            if (not item.text) and (not item.header):
                yield DoorstopWarning("no text nor header")

Maybe, you could integrate this before I get my development environment up and running and could leave a pull request.