Menu
▾
▴
python-markdown-discuss
|
From: Jack M. <ja...@co...> - 2008-10-17 07:03:13
|
Hi all.
I just wanted to point out that I wrote a TOC extension that's nicer than the
one linked to the wiki and (more importantly) is 2.0+ compatible. Some
differences from the aforementioned extension:
1. The anchor names aren't mangled... they are anchors generated by
slugifying the header contents (ala Django), which leads to much more
readable/memorizable links.
2. Header text is replaced by a self link of type toclink.
3. All instances of the marked (by default [TOC]) are replaced by the TOC
div, not just the first one. It also replaces the entire containing tag too.
It's designed for having
Textextextextextextextextextext
[TOC]
Moretextextextextextextex
So, to avoid messing up validation, it replaces the <p> tags created by
having the breaks.
Anyway, the code is available: http://codezen.org/static/toc.py
And it's in use on my project pages, if you want to see an example:
http://codezen.org/canto/config/
I'd like to get this included with the main source, if possible. Otherwise,
I'll just add a link to the wiki when 2.0 is officially released.
--Jack
|
|
From: Waylan L. <wa...@gm...> - 2008-10-17 13:26:00
|
Hi Jack, Interesting. I was just thinking about how to do that the other day. It looks like your approach is very similar to how mine would have been. There is a few things though: * Why are you creating anchors in each header? Why not just assign each header an "id" attribute? That is generally considered the correct way to do things and works just the same. * It would be nice if it worked with the HeaderID extension. That is, if a header already has an id attribute, that is used rather than recreating one which may be different. On Fri, Oct 17, 2008 at 2:18 AM, Jack Miller <ja...@co...> wrote: > Hi all. > > I just wanted to point out that I wrote a TOC extension that's nicer than the > one linked to the wiki and (more importantly) is 2.0+ compatible. Some > differences from the aforementioned extension: > > 1. The anchor names aren't mangled... they are anchors generated by > slugifying the header contents (ala Django), which leads to much more > readable/memorizable links. > > 2. Header text is replaced by a self link of type toclink. > > 3. All instances of the marked (by default [TOC]) are replaced by the TOC > div, not just the first one. It also replaces the entire containing tag too. > It's designed for having > > Textextextextextextextextextext > > [TOC] > > Moretextextextextextextex > > So, to avoid messing up validation, it replaces the <p> tags created by > having the breaks. > > Anyway, the code is available: http://codezen.org/static/toc.py > And it's in use on my project pages, if you want to see an example: > http://codezen.org/canto/config/ > > I'd like to get this included with the main source, if possible. Otherwise, > I'll just add a link to the wiki when 2.0 is officially released. > > --Jack > > ------------------------------------------------------------------------- > This SF.Net email is sponsored by the Moblin Your Move Developer's challenge > Build the coolest Linux based applications with Moblin SDK & win great prizes > Grand prize is a trip for two to an Open Source event anywhere in the world > http://moblin-contest.org/redirect.php?banner_id=100&url=/ > _______________________________________________ > Python-markdown-discuss mailing list > Pyt...@li... > https://lists.sourceforge.net/lists/listinfo/python-markdown-discuss > -- ---- Waylan Limberg wa...@gm... |
|
From: Waylan L. <wa...@gm...> - 2008-10-17 13:31:01
|
Oh, one other thing, wrap the toctitle in an if statement and only add it if a title is set in the config settings. Right now your getting a blank title ``<span class="toctitle" />``. On Fri, Oct 17, 2008 at 9:25 AM, Waylan Limberg <wa...@gm...> wrote: > Hi Jack, > > Interesting. I was just thinking about how to do that the other day. > It looks like your approach is very similar to how mine would have > been. > > There is a few things though: > > * Why are you creating anchors in each header? Why not just assign > each header an "id" attribute? That is generally considered the > correct way to do things and works just the same. > > * It would be nice if it worked with the HeaderID extension. That is, > if a header already has an id attribute, that is used rather than > recreating one which may be different. > > On Fri, Oct 17, 2008 at 2:18 AM, Jack Miller <ja...@co...> wrote: >> Hi all. >> >> I just wanted to point out that I wrote a TOC extension that's nicer than the >> one linked to the wiki and (more importantly) is 2.0+ compatible. Some >> differences from the aforementioned extension: >> >> 1. The anchor names aren't mangled... they are anchors generated by >> slugifying the header contents (ala Django), which leads to much more >> readable/memorizable links. >> >> 2. Header text is replaced by a self link of type toclink. >> >> 3. All instances of the marked (by default [TOC]) are replaced by the TOC >> div, not just the first one. It also replaces the entire containing tag too. >> It's designed for having >> >> Textextextextextextextextextext >> >> [TOC] >> >> Moretextextextextextextex >> >> So, to avoid messing up validation, it replaces the <p> tags created by >> having the breaks. >> >> Anyway, the code is available: http://codezen.org/static/toc.py >> And it's in use on my project pages, if you want to see an example: >> http://codezen.org/canto/config/ >> >> I'd like to get this included with the main source, if possible. Otherwise, >> I'll just add a link to the wiki when 2.0 is officially released. >> >> --Jack >> >> ------------------------------------------------------------------------- >> This SF.Net email is sponsored by the Moblin Your Move Developer's challenge >> Build the coolest Linux based applications with Moblin SDK & win great prizes >> Grand prize is a trip for two to an Open Source event anywhere in the world >> http://moblin-contest.org/redirect.php?banner_id=100&url=/ >> _______________________________________________ >> Python-markdown-discuss mailing list >> Pyt...@li... >> https://lists.sourceforge.net/lists/listinfo/python-markdown-discuss >> > > > > -- > ---- > Waylan Limberg > wa...@gm... > -- ---- Waylan Limberg wa...@gm... |
|
From: Jack M. <ja...@co...> - 2008-10-17 15:13:41
|
On Fri, Oct 17, 2008 at 09:30:49AM -0400, Waylan Limberg wrote: > Oh, one other thing, wrap the toctitle in an if statement and only add > it if a title is set in the config settings. Right now your getting a > blank title ``<span class="toctitle" />``. > Yeah, I actually just forgot the [0] on the config, so typo fixed. > > * Why are you creating anchors in each header? Why not just assign > > each header an "id" attribute? That is generally considered the > > correct way to do things and works just the same. > > Well, I like the headers to be turned into links. As with a lot of things that are pure preference, I just turned it into a config option (anchorlink) which defaults to 0, but if set makes the link. > > * It would be nice if it worked with the HeaderID extension. That is, > > if a header already has an id attribute, that is used rather than > > recreating one which may be different. Ah yes. Fixed. The code has been updated: http://codezen.org/static/toc-updated.py --Jack |
|
From: Waylan L. <wa...@gm...> - 2008-10-17 16:13:26
|
On Fri, Oct 17, 2008 at 11:13 AM, Jack Miller <ja...@co...> wrote: > On Fri, Oct 17, 2008 at 09:30:49AM -0400, Waylan Limberg wrote: >> Oh, one other thing, wrap the toctitle in an if statement and only add >> it if a title is set in the config settings. Right now your getting a >> blank title ``<span class="toctitle" />``. >> > > Yeah, I actually just forgot the [0] on the config, so typo fixed. Yeah, I've made that mistake before as well. Perhaps we need a better config system. I'll have to think about that. > >> > * Why are you creating anchors in each header? Why not just assign >> > each header an "id" attribute? That is generally considered the >> > correct way to do things and works just the same. >> > > > Well, I like the headers to be turned into links. As with a lot of things > that are pure preference, I just turned it into a config option (anchorlink) > which defaults to 0, but if set makes the link. Fair enough. Personally, I like it when a little paragraph symbol appears to the right of a header on hover, rather than the entire header being an anchor, but that may be beyond this extension (unless it was a third option) as the user would have to provide their own css etc. The current implementation is certainly good enough (tm). > >> > * It would be nice if it worked with the HeaderID extension. That is, >> > if a header already has an id attribute, that is used rather than >> > recreating one which may be different. > > Ah yes. Fixed. Well, mostly. Now, if a header already has an id, both the header and anchor will get the id. As ids should be unique, this creates invalid html. I'd suggest *not* assigning an id to the anchor - just the header. And speaking of unique, how are you guaranteeing that slugify does not create the same id for two different headers? Not a showstopper, but something to think about. You might be interested in how HeaderID addresses this. > > The code has been updated: > http://codezen.org/static/toc-updated.py > I don't mean to be so nitpicky Jack, but I would like something like this packaged up with Markdown and it has to be right before that happens. When I'm happy with it and with your blessings (and no objection from Yuri) I'll commit it to the repo. -- ---- Waylan Limberg wa...@gm... |
|
From: Yuri T. <qar...@gm...> - 2008-10-17 16:31:29
|
Thanks. I appreciate you doing this work. I checked the extension in under markdown_extensions/toc.py and put a test file under tests/extensions-x-toc/syntax-toc.txt. I can't get it to work for some reason, though. The file extension loads and does add the IDs, but doesn't seem to add the anchors or the actual TOC. Am I missing something? - yuri On Fri, Oct 17, 2008 at 8:13 AM, Jack Miller <ja...@co...> wrote: > On Fri, Oct 17, 2008 at 09:30:49AM -0400, Waylan Limberg wrote: >> Oh, one other thing, wrap the toctitle in an if statement and only add >> it if a title is set in the config settings. Right now your getting a >> blank title ``<span class="toctitle" />``. >> > > Yeah, I actually just forgot the [0] on the config, so typo fixed. > >> > * Why are you creating anchors in each header? Why not just assign >> > each header an "id" attribute? That is generally considered the >> > correct way to do things and works just the same. >> > > > Well, I like the headers to be turned into links. As with a lot of things > that are pure preference, I just turned it into a config option (anchorlink) > which defaults to 0, but if set makes the link. > >> > * It would be nice if it worked with the HeaderID extension. That is, >> > if a header already has an id attribute, that is used rather than >> > recreating one which may be different. > > Ah yes. Fixed. > > The code has been updated: > http://codezen.org/static/toc-updated.py > > --Jack > > ------------------------------------------------------------------------- > This SF.Net email is sponsored by the Moblin Your Move Developer's challenge > Build the coolest Linux based applications with Moblin SDK & win great prizes > Grand prize is a trip for two to an Open Source event anywhere in the world > http://moblin-contest.org/redirect.php?banner_id=100&url=/ > _______________________________________________ > Python-markdown-discuss mailing list > Pyt...@li... > https://lists.sourceforge.net/lists/listinfo/python-markdown-discuss > -- http://sputnik.freewisdom.org/ |
|
From: Magnus L. H. <ma...@he...> - 2008-10-17 17:07:15
|
On Oct 17, 2008, at 18:31 , Yuri Takhteyev wrote: > Thanks. I appreciate you doing this work. > > I checked the extension in under markdown_extensions/toc.py and put a > test file under tests/extensions-x-toc/syntax-toc.txt. One thing that *might* be related to toc generation is more of a "tag cloud" generation thing... Heres a description of what I mean: Anyone got a good text-parser for tagged text? http://www.boingboing.net/2008/08/12/anyone-got-a-good-te.html Maybe it's heretical to suggest something like this -- either some new syntax would have to be introduced, or some existing syntax would have to be hijacked -- but it's something I'm looking for, so I thought I'd mention it :) (In some ways this is more related to generating an index -- or multiple indices. After all, a tag cloud is just a topic index, with hyperlinks instead of page numbers.) -- Magnus Lie Hetland http://hetland.org |
|
From: Yuri T. <qar...@gm...> - 2008-10-17 17:52:39
|
> One thing that *might* be related to toc generation is more of a "tag
> cloud" generation thing... Heres a description of what I mean:
What may be useful for us to think about is how / whether both TOC and
some sort of tagcloud extension would work with multiple files. I
would assume that tagcloud would usually be more useful when it covers
multiple pages. TOC would _usually_ be used with a single page.
However, a multi-page TOC may be useful in some cases.
Up to now, the extensions has been allowed to be sticky by default. I
haven't tested it recently, but the footnote extension is really
supposed to allow you to run multiple files collecting the footnote
info and then dump the actual footnotes into a third. If you want to
forget what footnotes you've seen in earlier files, you need to call
Markdown.reset(). Two issues with this. First, I've been wondering
if this is a good default solution. Perhaps it would be best to
default to a clean-slate processing. Instead of convert() and
reset(), we could have convert() and convertMore(), with convert()
always resetting the state completely. So, your usage would be:
m = Markdown(extensions=["tagcloud"])
for x in pages:
m.convertMore(x)
tagcloud = m.convertMore("[TagCloud]")
Second, however, for this to be useful, extensions need to be able to
somehow keep track of what is coming from what file. So, convert()
and convertMore() would need to take some sort of ID parameter. In
other words, m.convertMore(page_source, id) would let the tagcloud
extension collect the tags knowing where those tags are coming from
and then generate proper links. So, we would get something like:
m = Markdown(extensions=["tagcloud"])
for id in page_ids:
converted[id] = m.convertMore(raw_pages[id], id)
tagcloud = m.convertMore("[TagCloud]")
- yuri
--
http://sputnik.freewisdom.org/
|
|
From: Waylan L. <wa...@gm...> - 2008-10-17 17:43:40
|
On Fri, Oct 17, 2008 at 12:31 PM, Yuri Takhteyev <qar...@gm...> wrote: > Thanks. I appreciate you doing this work. > > I checked the extension in under markdown_extensions/toc.py and put a > test file under tests/extensions-x-toc/syntax-toc.txt. > > I can't get it to work for some reason, though. The file extension > loads and does add the IDs, but doesn't seem to add the anchors or the > actual TOC. Am I missing something? Just guessing, but did you turn on anchors in the config (it's off by default - and should be IMO)? And did you add the marker ``[TOC]`` to the document for placement of the TOC. Which brings to mind another thought I had when I was planning my approach to this. What should be the default behavior when the document does not contain a marker? I can think of 3 reasonable behaviors: 1. Do nothing (current implementation). Without a marker you don't get a TOC - just ids. Although the HeaderID ext already gives you this, so the only value here is when an author wants some documents to have a TOC, but not others. 2. Insert the TOC into the beginning of the document by default. Although, this may be undesireable in some instances, so would need to be configurable. 3. Make the TOC available as an attribute on the Markdown class (much like Meta-Data ext does). This way a templating system could place the TOC elsewhere in a HTML template for a document if desired. Actually, this could happen regardless of 1 or 2. > > - yuri > > On Fri, Oct 17, 2008 at 8:13 AM, Jack Miller <ja...@co...> wrote: >> On Fri, Oct 17, 2008 at 09:30:49AM -0400, Waylan Limberg wrote: >>> Oh, one other thing, wrap the toctitle in an if statement and only add >>> it if a title is set in the config settings. Right now your getting a >>> blank title ``<span class="toctitle" />``. >>> >> >> Yeah, I actually just forgot the [0] on the config, so typo fixed. >> >>> > * Why are you creating anchors in each header? Why not just assign >>> > each header an "id" attribute? That is generally considered the >>> > correct way to do things and works just the same. >>> > >> >> Well, I like the headers to be turned into links. As with a lot of things >> that are pure preference, I just turned it into a config option (anchorlink) >> which defaults to 0, but if set makes the link. >> >>> > * It would be nice if it worked with the HeaderID extension. That is, >>> > if a header already has an id attribute, that is used rather than >>> > recreating one which may be different. >> >> Ah yes. Fixed. >> >> The code has been updated: >> http://codezen.org/static/toc-updated.py >> >> --Jack >> >> ------------------------------------------------------------------------- >> This SF.Net email is sponsored by the Moblin Your Move Developer's challenge >> Build the coolest Linux based applications with Moblin SDK & win great prizes >> Grand prize is a trip for two to an Open Source event anywhere in the world >> http://moblin-contest.org/redirect.php?banner_id=100&url=/ >> _______________________________________________ >> Python-markdown-discuss mailing list >> Pyt...@li... >> https://lists.sourceforge.net/lists/listinfo/python-markdown-discuss >> > > > > -- > http://sputnik.freewisdom.org/ > -- ---- Waylan Limberg wa...@gm... |
|
From: Yuri T. <qar...@gm...> - 2008-10-19 01:51:57
|
> Just guessing, but did you turn on anchors in the config (it's off by > default - and should be IMO)? And did you add the marker ``[TOC]`` to > the document for placement of the TOC. Turns out I was putting "[TOC]" into the wrong file. :) Yes, I agree that anchor links should be off by default. > 1. Do nothing (current implementation). Without a marker you don't get > a TOC - just ids. Although the HeaderID ext already gives you this, so > the only value here is when an author wants some documents to have a > TOC, but not others. > > 2. Insert the TOC into the beginning of the document by default. > Although, this may be undesireable in some instances, so would need to > be configurable. I am a little divided between those, but if we go with #2, then we would need a parameter to get #1 behavior, which I think may well be needed at times. If we stick with #1, again, a config parameter to get #2 may be helpful, but less important. > 3. Make the TOC available as an attribute on the Markdown class (much > like Meta-Data ext does). This way a templating system could place the > TOC elsewhere in a HTML template for a document if desired. Actually, > this could happen regardless of 1 or 2. Perhaps it would be a little cleaner to make those attributes of the extensions? I.e., have something like: md.extensions['toc'].tocTree - yuri -- http://sputnik.freewisdom.org/ |
|
From: Jack M. <ja...@co...> - 2008-10-21 22:45:14
Attachments:
toc.patch
|
> Well, mostly. Now, if a header already has an id, both the header and > anchor will get the id. As ids should be unique, this creates invalid > html. I'd suggest *not* assigning an id to the anchor - just the > header. > > And speaking of unique, how are you guaranteeing that slugify does not > create the same id for two different headers? Not a showstopper, but > something to think about. You might be interested in how HeaderID > addresses this. Attached is a patch that handles both of these issues. I didn't use HeaderID code, but I matched the style (_1, _2, etc) and it should produce globally unique ids. > I don't mean to be so nitpicky Jack, but I would like something like > this packaged up with Markdown and it has to be right before that > happens. When I'm happy with it and with your blessings (and no > objection from Yuri) I'll commit it to the repo. > Hahaha. You're not being unreasonable, it's not a big deal. Trust me, I work with much more nitpicky people at work =) --Jack |
|
From: Waylan L. <wa...@gm...> - 2008-10-29 02:34:25
|
On Tue, Oct 21, 2008 at 6:44 PM, Jack Miller <ja...@co...> wrote: [snip] > > Attached is a patch that handles both of these issues. I didn't use HeaderID [snip] I just pushed this. Thanks Jack. -- ---- Waylan Limberg wa...@gm... |
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X