Re: [Python-markdown-discuss] Future of the HeaderId extension??

[Waylan L. <wa...@gm...>]

Thanks for the feedback Jean-Philippe. Some comments below:

On Sat, Jun 25, 2011 at 2:21 PM, Jean-Philippe Fleury
<co...@jp...> wrote:
> Waylan Limberg a écrit le 2011-06-23 18:39 :
>> 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.
>
> For me, it's not really inappropriate to have options related to a
> subset of attributes in the attr_list extension. I imagine options for
> ids, classes... Example (non-existent options only for this example):

You make a good point, but ...

> ~~~~~~~~~~~~~~~
> extensions=['attr_list(forceid=True, overrideClasses=False,
> optionalColon=False)']
> ~~~~~~~~~~~~~~~
>
>> 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.
>
> I think the same code should be use to autogenerate ids on headers,
> regardless of the extension. For now, toc and headerid don't output the
> same result. toc:
>

I agree. And I think the proper place for this is in the HeaderId
Extension. If any other extension (like TOC) wants auto-generated ids,
they can use the HeaderId ext for that.

[snip]
>
> Using to the same algorithm would ensure uniformity and reduce code
> duplication. Between toc and headerid, toc algorithm is more interesting
> since its transliteration is more advanced (e.g., "intéressant" becomes
> "interessant" instead of "int+ressant").

You make a good point. I think I'll use the TOC algorithm and move it
over to the HeaderID extension.

>> 4) Do nothing and tell people to use the attr_list extension moving
>> forward for defining ids.
>
> IMHO:
>
> 1) using extensions=['extra'] should be sufficient to have full Markdown
> Extra support (without using other extensions), and a Markdown Extra
> document should be converted in HTML the same way whatever the
> implementation used (PHP, Python...). For now, we must use
> `extensions=['extra', 'headerid(forceid=False)']` to emulate correctly
> Markdown Extra, otherwise extra code (forced ids) is added that should
> not be added.

I understand your point and I even considered that when I first
implemented it. My thinking at the time was that adding ids to headers
it not even noticeable in the browser by the enduser reading a
document. It doesn't change the semantics of the html at all. It just
provides a few extra hooks (for styling or linking) which may or may
not be used.

I don't know how many times I've wanted to link to a specific section
of a long document and hit view-source in my browser to find the id of
the section so I could link to `somepage.html#somesection`. It has
always been dissatisfying to find no ids to utilize. And yet, when
they are there, I'm completely unaware of their existence until I need
them. Perhaps this was just me on a mission to make all websites (at
least the ones using python-markdown) include ids out of the box.

>
> 2) when using extensions=['extra'], extra elements that are not part of
> the Markdown Extra description should not be accessible, otherwise we
> open the door to a set of Markdown Extra documents not converted the
> same way according to the implementation used.

I find it interesting that PHP Markdown Extra's documentation [1]
specifically states that "Setting the id attribute will work only with
headers for now." That indicates to me that other attributes could be
forthcoming. Therefore, I'm going to have extra use the new attr_list
extension for defining ids (and classes and other stuff on headers and
anything else).

[1]: http://michelf.com/projects/php-markdown/extra/#header-id

The HeaderId ext will only be used to auto-generate ids. If you want
to define Ids, you'll need to use the attr_list extension (or extra).

As a side note. I've found that users tend to get confused by (and
therefore avoid using) extension configs. It is easy to add another
extension. Not so easy to change config settings for one though. In
other words, the typical user would rather do:

    markdown.markdown(text, extensions=['attr_list', 'headerid'])

rather than:

    markdown.markdown(text, extensions=['attr_list(forceid=True)'])

My proposed changes give them that. Besides, we are only 'forceing
ids' on headers. Not all elements that attributes can be defined on in
the attr_list ext.

Additionally, the first example is also doable with Django's markdown
template tag. IIRC the second is not. Of course that should not be the
controlling factor here, but it is an interesting datapoint.


-- 
----
\X/ /-\ `/ |_ /-\ |\|
Waylan Limberg