python-markdown-discuss

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

[Jean-Philippe F. <co...@jp...>]

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):

~~~~~~~~~~~~~~~
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:

~~~~~~~~~~~~~~~
text = """
# L'intéressant titre
"""
print markdown.markdown(text, extensions=['toc'])
~~~~~~~~~~~~~~~

will output:

~~~~~~~~~~~~~~~
<h1 id="linteressant-titre">L'intéressant titre</h1>
~~~~~~~~~~~~~~~

headerid:

~~~~~~~~~~~~~~~
text = """
# L'intéressant titre
"""
print markdown.markdown(text, extensions=['headerid'])
~~~~~~~~~~~~~~~

will output:

~~~~~~~~~~~~~~~
<h1 id="lint+ressant_titre">L'intéressant titre</h1>
~~~~~~~~~~~~~~~

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").

> 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.

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'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 think so, but I don't know if it should be as an extension or not.

Regards,

Jean-Philippe

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

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

[Jean-Philippe F. <co...@jp...>]

Waylan Limberg a écrit le 2011-06-29 11:28 :
> 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.

Good point, and it happens to me too.

> 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.

Other good point.

> 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).

It would be interesting to have a dedicated mailing list about Markdown
Extra to discuss about the evolution of its specification.

Regards,

Jean-Philippe

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

[Marco P. <mar...@gm...>]

On Wed, Jun 29, 2011 at 5:28 PM, Waylan Limberg <wa...@gm...> wrote:

> 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)'])
>
>
What about

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

or even:

markdown.markdown(text, extensions={'attr_list': {'forceid': True}, ...})

?

Even if I'd prefer the use of the OO interface, through the Markdown class,
in such cases.

-- 
Marco Pantaleoni

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

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

On Wed, Jun 29, 2011 at 12:00 PM, Marco Pantaleoni
<mar...@gm...> wrote:
> On Wed, Jun 29, 2011 at 5:28 PM, Waylan Limberg <wa...@gm...> wrote:
>>
>> 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)'])
>>

Keep in mind that the above syntax is only available because that's
how the comandline script takes ext configs. It just so happens that
the code that parses that is contained in the Markdown class. It is
really a coincidence that it works at all. However, as many people
have been using it, I'm not going to disable that feature.

>
> What about
>
> markdown.markdown(text, extensions=[('attr_list', {'forceid': True}), ...])
>

This is already possible through the extension_config keyword on
either the class or the wrapper function (IIRC support for this on the
function is a recent addition). Yes that means you have to list the
extension twice (extensions and configs), but that was the API before
I came to the project. We've made too many other API changes in the
past, so it is staying. I'm certainly not creating a third way.




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