Re: [Python-markdown-discuss] Overriding Functions, etc.

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

Hi Ben,

Ben Wilson wrote:
> I'm currently playing with a Python-based flat-file wiki that relies
> on Markdown syntax (mostly). This is more for my education as I
> understand MoinMoin is the premier wiki-engine for Python and it seems
> to support some Markdown markup.[1] So, I've made a few observations
> that I'm trying to explain here.
> 
> I would like to say the Python-Markdown class is great. I like being
> able to extend it. For example, I have a different way of handling the
> ==== and ---- headings that encourages me to short-circuit the
> headings_preprocessor. The reason for my short-circuiting is that I
> order headers differently and include ++++ and ~~~~, and the
> preprocessor presupposes that a section heading (====) should be
> <h1>.[2] I'm able to get both lines of a heading (the title and
> markup) by a regex without lookaheads, but it may not be stable.
> 
> I would also like to change the output to Tex/LaTeX format if possible.

I've thought about that as well. Currently, most of the output is stored 
in a minidom instance (the exception being raw htmlblocks). I suppose it 
could be possible to extend the minidom class to output different 
formats, but I haven't looked into it. Perhaps if python-markdown didn't 
use it's own custom minidom class, but one of the more common python dom 
modules, this would be easier (code might already exist). I don't know 
what Yuri's thought about this would be.
> 
> I was thinking that _perhaps_ the pre-processors could be a dictionary
> instead of an array, which would allow deleting by name. Presently, I
> set all the preprocessors by copying from the class, then delete the
> one preprocessor I don't want. This would also allow use of has_key(),
> as the present implementation (correct me if I'm wrong) does not allow
> listing or deleting a preprocessor directly.

This seems like a good idea until we remember that dictionaries do not 
preserve order. In this case, order is very important, as certain 
pre-processors must absolutely be run before others. That's imposable 
with a dictionary. With a little searching you'll find that various 
projects have implemented their own non-standard sorted-dict to address 
this issue, but every implementation is a little different. Another 
possibility could be a list of tuples [(key, value), (key. value)], but 
that can be a pain to work with. That is why a simple list is used. 
Currently is is easy enough to refer to each item by its index, but if 
you're making multiple changes, I can see how that could be problematic.
> 
> I'm also having a bit of a problem with the documentation. I'm used to
> an "undue experimentation" rule for documentation. This means that a
> programmer should be able to look to the documentation alone to
> explain _how_ to use the class---such as adding a preprocessor. I
> ended up having to look in the class itself to see how it added a
> preprocessor. Perhaps the example given could be an actual
> implementation of a simple preprocessor?

Generally the footnote extension is referred to as an example as it uses 
all three methods of adding extensions (pre-precessors, patterns, and 
post-processors).

> 
> FWIW, I am adding some non-Markdown syntax that is more expected in
> wiki markup (e.g. [[free links]]
> 
> Anyway, thanks for a great Markdown class. It moved my development of
> my wiki up by about three weekends.
> 

-- 
Waylan Limberg
wa...@gm...