search

cabo / kramdown-rfc

An XML2RFC (RFC799x) backend for Thomas Leitner's kramdown markdown parser
MIT License
195 stars 83 forks source link

What should I be looking for, when I see '$stderr.puts "Incorrect section nesting: Need to start with 1"' #194

Closed SpencerDawkins closed 1 year ago

SpencerDawkins commented 1 year ago

I made a decent number of changes to my markdown file, and am now seeing (for the first time in my life)

$stderr.puts "Incorrect section nesting: Need to start with 1"

I diffed my old and new markdown files, and don't see anything obvious, and part of my problem is almost certainly that I don't know how I can screw up "section nesting" in markdown.

Could you give me a clue?

Obviously this must have happened at least once in previous history, because the code checks for it now. What caused the problem last time? :upside_down_face:

cabo commented 1 year ago

kramdown-rfc needs to construct nested sections from what is essentially a flat input structure. It looks for headings and generates a nested section start for each increase of the heading level. This increase needs to be by 1 or we don't have a section title to give to the new nesting level.

So if your introduction starts with ## or you maybe have a ### heading inside a # heading, kramdown-rfc will reduce the heading level so there is only a by 1 increase and you get the warning.

Of course, decreasing the level is possible by any amount as sections can be closed without a needing a title.

SpencerDawkins commented 1 year ago

Thank you! Now, I know exactly what to look for.

On Wed, Apr 26, 2023, 20:44 cabo @.***> wrote:

kramdown-rfc needs to construct nested sections from what is essentially a flat input structure. It looks for headings and generates a nested section start for each increase of the heading level. This increase needs to be by 1 or we don't have a section title to give to the new nesting level.

So if your introduction starts with ## or you maybe have a ### heading inside a # heading, kramdown-rfc will reduce the heading level so there is only a by 1 increase and you get the warning.

Of course, decreasing the level is possible by any amount as sections can be closed without a needing a title.

— Reply to this email directly, view it on GitHub https://github.com/cabo/kramdown-rfc/issues/194#issuecomment-1524417962, or unsubscribe https://github.com/notifications/unsubscribe-auth/ADSWECJJSN6CTJJ6G5N2IPLXDHFRRANCNFSM6AAAAAAXNCQNEI . You are receiving this because you authored the thread.Message ID: @.***>

cabo commented 1 year ago

I plan to improve the error message in the next release.

cabo commented 1 year ago

Slightly better error message (with line number) now in 1.6.32. https://github.com/cabo/kramdown-rfc/commit/cad3018

SpencerDawkins commented 1 year ago

@cabo - thank you for this. If I'd had a line number pointing to "###", that would have helped me a lot!