section / grouping concept using @section, @subsection, @subsubsection (or @group)
Toni Uebernickel
I just read the Second Public Draft and get wondered about the section/
grouping concept.
As mentioned in the document itself, CSSEdit (http://macrabbit.com/
cssedit/) uses @group with @end to group styles.
The first thing I was wondering while reading the draft was "How do I
close a section?" (without opening a new one).
This is imho well done by CSSEdit using a specific tag "@end" to close
a group. This however also solves the second issue "How to cascade
sections properly?".
In my opinion something like @section and @subsection should do the
trick, but I really don't like things like @subsubsection and later on
perhaps @subsubsubsubsubsection (exagurated, but you get the point).
Let's face this example:
/**
* Typography
*
* @section typography
*/
p { margin: 0px 2px 5px 0px; line-height: 1.2em; }
/**
* Headings
*
* @section typography
* @subsection headings
*/
h1 { font-size: 1.3em; }
/**
* Subheadings
*
* @section headings
* @subsection subheadings
*/
h3 { font-size: 1.1em; }
/**
* Lists
*
* @section typography
* @subsection lists
*/
ul, ol { list-style: none inside none; }
/**
* Navigation
*
* @section navigation
*/
#main_navigation li { font-weight: bold; }
This would generated a nested section tree similar to this
|_ Typography
|__ Headings
|___ Subheadings
|__ Lists
|_ Navigation
A parser, doing its work from top to the bottom, will know every
section that came up before. A new (unknown) @section identifier
(section name) opens a new top-level section. If the section's name is
known, a @subsection will not be required, but recommended. If no
@subsection is given, the part that follows is added to the given
section as it would be directly in the section itself.
This would eliminate @subsubsection and so on, while giving a clean
setup creating subsections and complex section trees.
Using @end(section) should be a simple and useful way of closing an
opened section.
@section itself does the same but opens a new section immediately.
Well done so far, I'm looking forward to upcoming versions :)
Best Regards,
Toni Uebernickel
sam foster
> trick, but I really don't like things like @subsubsection and later on
> perhaps @subsubsubsubsubsection (exagurated, but you get the point).
my concern also, the subsection thing just doesnt scale well, as
there's not really a useful "typical" section depth, and making a
arbitrary maximum depth in the specification is... arbitrary. Plus, if
you move code around, you may have to go through and correct all the
section levels. While best practices might dictate that a depth of
more than 2 or 3 section levels probably warrant a new stylesheet,
there are lots of times that's not desirable, or possible.
if you add an @end (explicitly end a block, which is implicitly means
end the @section) you get nesting for free (from the specification
point of view), as any new @section tag without an interceding @end
tag becomes a child section. That's kind of nice, but you lose
something in the ease of use, where each section docblock now must be
paired with an ending docblock to avoid unwanted nesting.
If its a toss-up between the 2, I guess I'd go with the @end (or
@endsection, or @sectionend even), but I'd love to hear other ideas.
Enjoying using cssdoc on a 2nd project, and hoping to port and publish
our parser and viewer sometime soon.
mot
> @endsection, or @sectionend even), but I'd love to hear other ideas.
yes, i would like to have some more ideas there as well because it
does not feel like this is having it in full.
i must say that subsection works quite well in practice. it is easy to
use even when i look conceptually at it it looks like having the said
flaws.
so it might be adviseable that current cssdoc users just give feedback
about their usage of the subsections.
Tom