I have a question about the HeaderID extension and what should happen to it.
To summarize, a bug report [1] was filed recently pointing out that
ids can not be set on setext style headers. At first I was just going
to fix it, but instead I added a new extension [2] implementing
attribute lists (inspired by Maruku [3]). The new extension adds the
same behavior and more (allowing classes and other attributes as
well). I even implemented the syntax with the colon optional so
existing documents would not need to be edited.
However, if I remove the HeaderID extension we loose 2 features which
it provides: the ability to define a starting header level and
automatically generated ids on headers. (see the docs [4])
I see the following options and would like some feedback about what
others would prefer.
1) Remove HeaderID ext and reimplement those features in the attr_list
extension. However, as they're header specific, that doesn't feel
right to me.
2) Remove duplicate id defining code and use the HeaderID ext only for
defining level and autogenerating ids on headers.
3) Patch the HeaderID extension to work with setext headers and have
two separate extensions which accomplish the same thing - one which
works only with headers (and only sets ids) and the other which works
with any element (and sets any attribute). Seems redundant and
potentially confusing.
4) Do nothing and tell people to use the attr_list extension moving
forward for defining ids.
I'm leaning toward #2 myself. But is also occurs to me that the TOC
extension also autogenerates ids when not defined (in a slightly
different manner). Perhaps we should provide some general code
specifically for autogenerating ids on headers. I suppose the HeaderID
extension could serve that purpose (especially if we went with option
2), or should that be something configurable on the Markdown class.
Leaving it as an extension would make the autogenerating algorism more
easily overridable.
The other consideration is that the Extra extension currently includes
the HeaderID extension. If we went with option #2, we would need to
use the attr_list extension. But PHP Markdown Extra doesn't offer the
header level and auto ids options, so that means the HeaderId
extension would be removed from our version of Extra as well. I wonder
if that could cause frustration from people using Extra and relying on
those features. If this is a real issue, I have no idea if option #1
or #4 would be the best way forward.
Any thoughts?
[1]: https://github.com/waylan/Python-Markdown/issues/16
[2]: https://github.com/waylan/Python-Markdown/blob/master/docs/extensions/attr_list.txt
[3]: http://maruku.rubyforge.org/proposal.html#attribute_lists
[4]: https://github.com/waylan/Python-Markdown/blob/06004bd900b7425641932d27f0bb5a77fadfcff5/docs/extensions/HeaderId.txt
--
----
\X/ /-\ `/ |_ /-\ |\|
Waylan Limberg
|
