I had made a pull request for a simple change, but then I discovered some further challenges so I wanted to capture it all here for other folks to find the things I miss.

After working with this for a while, I realized the terms were starting to confuse me, so let me define what I'm using up front:

• Heading: an item where the following conditions are met:
  • levels ends in .0
  • normative is False
• Header: a "title" text attribute on both heading and non-heading items.
  • expected to be a single line
• Text: a "description" text attribute on both heading and non-heading items.
  • may be multiple lines
  • if header is blank, then the first line of text is used as the item's title.

The logic to extract the header and non-title lines of text is repeated in multiple of the publisher. In some of those (example), the logic is broken and conditionally prepends the header to the text, but then unconditionally removes the first line from text -- resulting in a lost line of text in certain circumstances.

My guess is that the header attribute was added later, and originally the first line of the text attribute was always used for the title. That may or may not be true, but it would describe the current state of the repo. The easy fix here would be to switch to using only the header attribute and stop using the first line of text as a title. But if people are currently using it that way, then it would break things for them.

The more backwards-compatible solution is probably to add some new methods to item as follows:

• title gets the title from either the header or if that is blank then from the first line of text
• description gets the description from text, omitting the first line only if it would appear in title

Then we just have to update things to use those new methods. I think I can knock that out pretty easily.

That being said, I'm not familiar with the testing framework or the decorators (@auto_save, @property`, etc) that are on the other methods, nor have I updated the documentation before. So if someone felt like pointing me to some resources on that stuff I wouldn't complain. 😊