search

gfranko / jquery.tocify.js

A jQuery Table of Contents plugin that can be themed with Twitter Bootstrap or jQueryUI.
http://gregfranko.com/jquery.tocify.js/
MIT License
927 stars 217 forks source link

Content Outlining Algorithm #46

Closed oleersoy closed 10 years ago

oleersoy commented 10 years ago

This is related to issue number https://github.com/gfranko/jquery.tocify.js/issues/36

I figured I'd start a new issue since the other one is "Old" and my comments there might be missed.

I was going to do a write up on what type of structure tocify expects and it turns out there's already an official spec for the algorithm that determines the document outline. The mozilla article sort of hints at it, but this makes it a lot more clear:

http://coding.smashingmagazine.com/2011/08/16/html5-and-the-document-outlining-algorithm/ http://developers.whatwg.org/sections.html#headings-and-sections

Do you think it's good enough to just reference this material?

gfranko commented 10 years ago

I think this paragraph from the whatwg article would be perfect:

The first element of heading content in an element of sectioning content represents the heading for that section. Subsequent headings of equal or higher rank start new (implied) sections, headings of lower rank start implied subsections that are part of the previous one. In both cases, the element represents the heading of the implied section.

Feel free to expand upon this if you think it would still be confusing to someone. Also, sorry for the late response!

oleersoy commented 10 years ago

I perform best when I can see a simple example and extract the usage pattern from the example, so I lean more towards this type of guidance.

Something like "For information on how to structure your content google 'html content outlining algorithm' and you will find simple markup examples and more.", I think will provide the best starting point, assuming it's attempting to guide the user in terms of how to structure markup.

On 10/11/2013 10:41 PM, Greg Franko wrote:

I think this paragraph from the whatwg article would be perfect:

The first element of heading content in an element of sectioning content represents the heading for that section. Subsequent headings of equal or higher rank start new (implied) sections, headings of lower rank start implied subsections that are part of the previous one. In both cases, the element represents the heading of the implied section.

Feel free to expand upon this if you think it would still be confusing to someone.

At first read it seems like it only deals with headers within sections, but the wording is fairly generic so I could be wrong. I feel a little bit like I'm reading a patent. Hope I'm not being to harsh.

Also, sorry for the late response!

Hey been there :), so no worries!

gfranko commented 10 years ago

Yea, I think pointing at those two resources will work. The only reason for having some sort of summary is so everyone does not have to wade through rather long resources.

oleersoy commented 10 years ago

I think the site does a terrific job of getting developers started as is. I got tripped up a bit by bootstrap, as I was trying to apply it to the way bootstrap writes it's help documentation, and it stopped a bit short of my initial expectation, but that's because bootstrap's markup is outside the scope of the content outlining algorithm. So at that point I really needed to understand the algorithm, or look at a few simple example of how the content should be structured. I wanted to make sure I structured my content in ways that did not "Trap" the algorithm. If I had read the summary, I think I still would feel uncomfortable with respect to how to structure the markup. It's a bit like reading a summary on what thread safety is...you're still going "How the heck do I make it thread safe?".

This is only my personal preference though. Perhaps litmus test the summary out on a few other developers and see if they feel it's helpful.

On Mon, Oct 14, 2013 at 7:23 AM, Greg Franko notifications@github.comwrote:

Yea, I think pointing at those two resources will work. The only reason for having some sort of summary is so everyone does not have to wade through rather long resources.

— Reply to this email directly or view it on GitHubhttps://github.com/gfranko/jquery.tocify.js/issues/46#issuecomment-26251651 .

gfranko commented 10 years ago

Okay, so for now I am going to close this issue unless other developers are confused.

oleersoy commented 10 years ago

Sounds good.

On 10/15/2013 03:41 PM, Greg Franko wrote:

Okay, so for now I am going to close this issue unless other developers are confused.

— Reply to this email directly or view it on GitHub https://github.com/gfranko/jquery.tocify.js/issues/46#issuecomment-26370231.