adding toc_height to exclude upper headings, proposal for #786 and #637 by klml · Pull Request #787 · Python-Markdown/markdown (original) (raw)

Your recent changes are a big improvement. They helped bring the new feature into focus for me. Thank you.

I agree that toc_height feels like the wrong name for this. Personally I would favor toc_top.

However, adding this feature introduces another problem, in that toc_depth is now misleading. A user might reasonably assume that the word "depth" refers to the total number of levels. So for example, she might expect the following settings: toc_top=2, toc_depth=2 to result in a TOC which included levels h2 and h3 for a depth of 2. But, in fact, toc_depth limits the bottom to h2 and the "depth" (or number of levels) of the TOC is no longer 2, but 1. Previously, when the "top" couldn't be altered, "depth" and "bottom" were always synonymous. But once the "top" is altered, "depth" and "bottom" are not the same any more. Therefore, toc_depth is a misleading name for the setting as it currently behaves.

I see a few ways forward:

  1. Alter toc_depth to be the actual "depth" (number of levels) of the TOC. Perhaps do something like bottom = top + depth - 1 (so for toc_top=2, toc_depth=2, bottom would be 3). For existing users who are not using toc_top, this changes nothing in the actual output. And as toc_top is new, the new behavior of toc_depth will be taken into consideration for any users of the new toc_top setting.
  2. Leave toc_depth behavior as-is, but deprecate the name and rename it to toc_bottom. This would be the most disruptive to existing users, which makes it my least favorite option. But having the two settings names "top" and "bottom" is attractive.
  3. Implement a range instead. If toc_depth is an integer, maintain the old behavior. If toc_depth is a range ('t-b' where t and b are integers), then treat the range as top and bottom.

Both for options 2 and 3, we would also need to handle the case where a user assigns values such that bottom < top. Of course, that would be an error. But in option 1 that is never a factor. As long as depth is any whole number between 1-6, we will always get bottom > top. Of course, as HTML never drops below h6 we don't actually care if bottom > 6.